Support for Roles with Invalid SSL Certificates

A common scenario during the development or test phase of an application utilizing the Service Gateway is the requirement to make HTTPS requests to roles that do not feature valid SSL certificates. Ordinarily, if the Service Gateway cannot validate the SSL certificate served by the role it will return a 502 - Bad Gateway error. This is necessary when the application is in production to protect against Man In The Middle Attack. However, during dev/test it is common for test roles to have self-signed or other invalid SSL certificates and yet the Service Gateway should still proxy the requests to these roles.

This feature should never be applied in production environments. Always request valid SSL certificates from well known issuers.

Adding the Signing Authority Certificate(s)

Self-signed and other test certificates are only 'invalid' because the issuer chain cannot be validated up to a set of well-known certificate authorities (CA) that are pre-installed in the VM hosting the Service Gateway certificate store. In all other respects, they are cryptographically valid. Therefore, all that is required to recognize the test certificate as valid is to install the certificates representing the issuer chain. In the case of a self-signed certificate, this is the certificate itself. In the case of unknown CA, all certificates representing the full issuer chain should be installed.

A point to note at this stage is that only the public key of these certificates are required to be installed. Therefore, there is no risk of internal CA credentials being leaked and used in an unauthorized manner.

Deploying and Installing Issuer Certificates with the Service Gateway

Note: This option is currently only available when building and deploying the Service Gateway from Visual Studio. See Deployment Guide for full details on deployment options with the Service Gateway.

Export the Issuer Certificates

If you already have the Issuer certificates exported to X.509 format, skip this section.

  1. Open the Certificate Manager on the computer that issued the test certificate.
  2. Find the test certificate, right-click and select Properties.
  3. Select the Certification Path tab. Repeat the following set of steps for each certificate above the test certificate in the chain by clicking the View Certificate button. For self-signed certificates, perform the next steps for this certificate.
  4. Select the Details tab and click the Copy to File... button.
  5. The Certificate Export Wizard is displayed. Click Next.
  6. Select 'No, do not export the private key'. Click Next.
  7. Select 'Base-64 encoded X.509 (.CER)'. Click Next.
  8. Enter a file name in the \Setup\Startup directory beneath the root of the Service Gateway codebase (or any location if on a different computer. Manually copy all exported certificates to this location on the build computer). Click Next. Click Finish. The certificate will be exported to the filename specified.

Add the Certificates to the Visual Studio Solution

  1. Open the Gateway.sln solution file in Visual Studio 2013.
  2. In the Solution Explorer window, navigate to the Setup project.
  3. For each issuer certificate exported in the previous section, select Project -> Add Existing Item... Select the certificate file.
  4. In the Solution Explorer window, select the newly added file, right-click and select Properties. Set the following properties:

    Build Action: None
    Copy to Output Directory: Copy always
    
  5. Open the InstallTestRoleCerts.cmd file. For each certificate added, ensure a line appears in the script of the following pattern:

    certutil -enterprise -addstore root startup\xxxxxxx.cer >> %logfile% 2>&1
    
  6. Build and deploy the Gateway. Inspect the installTestRoleCerts.log log file in the wad-startup-tasks-logs container of the configured diagnostics store for any errors raised when installing the issuer certificates.

  7. Verify that the Gateway is proxying requests for the role with a test SSL certificate.

Last edited Jul 7, 2014 at 6:33 PM by jamesbak, version 2