Secure the Gateway Using Trusted Certificates

You can configure secure networking between Kaazing Gateway and its clients and back-end servers using trusted certificates issued by a Certificate Authority. A trusted certificate can be issued from a trusted public Certificate Authority or a Certificate Authority within your company and trusted by both your enterprise clients and servers. Using a trusted certificate also ensures that WebSocket connections are not dropped by intermediaries in the network such as proxy servers and firewalls.

In this procedure, you will do the following:

  1. Configure the Gateway with a trusted certificate for the Gateway’s host name, and then configure the Gateway with a HTTPS directory service that uses that host name. This will configure the Gateway for TLS/SSL connections from clients.
  2. Configure the Gateway with a trusted certificate for the back-end server’s host name, and configure the Gateway with a proxy service that accepts the WebSocket Secure (wss://) connection on the Gateway’s host name and connects over TLS/SSL to the back-end server. This will configure the Gateway for TLS/SSL connections to back-end servers.

Note: You could choose to configure the proxy service only, as it configures both TLS/SSL client and server connections to the Gateway, but the directory service configuration is included because it is a useful method for learning client to Gateway TLS/SSL connections.

Before You Begin

This procedure is part of Secure Network Traffic with the Gateway:

To Secure Gateway Connections Using Trusted Certificates

Secure Client-to-Gateway Connections

  1. Identify the host name of the server running the Gateway. Clients must be able to resolve the host name to the IP address of the server running the Gateway in order to establish a secure session with the Gateway.

    The Gateway supports certificates that are generated for wildcard names. For example, *.example.com represents example.com and all of its subdomains, such as my.example.com and secure-mail.example.com.

  2. Create the custom keystore password file for the Gateway to use with the custom keystore. If you are going to use the default keystore and password file, skip this step. The Gateway is configured to use the default keystore and password already.

    To create the password file, create a new text file using a text editor, enter the password, and save the password file in the directory GATEWAY_HOME/conf/.

    To configure the Gateway to use the custom keystore and password file, open the GATEWAY_HOME/conf/gateway-config.xml file in a text editor and update the keystore element (contained in the security element) to use the new keystore and the password file you created, as shown in the following example:

          <keystore>
            <type>JCEKS</type>
            <file>mykeystore.db</file>
            <password-file>mykeystore.pw</password-file>
          </keystore>
    
  3. Locate the Java keytool utility that is part of your Java installation. It can be found in the Java bin directory. For example, C:\Program Files\Java\jdk1.7.0_21\bin (Windows) or /Library/Java/home/bin (Mac OS X).
  4. Create a Certificate Signing Request (CSR).

    A trusted certificate is obtained by creating a CSR and sending that request to a public Certificate Authority, such as Symantec, Thawte, and Entrust, or to a Certificate Authority that is already configured in your corporate network, such as a Windows Domain Controller running as a Certificate Authority. A CSR is a public key generated on the server running the Gateway that validates information about the server and your organization when you request a certificate. To create a CSR, do the following:

    1. Create a private key for the host name the Gateway will use in its accept element (the host name clients will use when connecting to the Gateway). Substitute your GATEWAY_HOME and password in the example:

      keytool -genkeypair -alias example.com -keysize 2048 -keyalg RSA-keystore
      "GATEWAY_HOME\conf\keystore.db" -storetype JCEKS-storepass password
      

      You will be prompted to provide information about your organization. This information is used to verify the CSR in the future.

      The password value for -storepass is located in the keystore password file that is located in the GATEWAY_HOME/conf folder (by default, keystore.pw). You can open the file with a text editor to read the default password and enter it in the command.

    2. Generate the CSR using the same alias:

      keytool -certreq -alias example.com -file certreq.txt-keystore
      "GATEWAY_HOME\conf\keystore.db" -storetype JCEKS-keyalg RSA -storepass password
      

      A text file containing the CSR is stored in the same folder as keystore.db.

    3. Send the CSR text file to the trusted Certificate Authority. The Certificate Authority will return a trusted certificate that you can import into the keystore. In the case of public Certificate Authorities, you will likely need to perform some kind of offline identity verification.

  5. Import the trusted certificate for the host name of the Gateway into the keystore used by the Gateway.

    The following example shows how to import the certificate into the default keystore, called keystore.db, located in GATEWAY_HOME/conf.

    keytool -importcert -keystore GATEWAY_HOME\conf\keystore.db -storetype JCEKS -storepass password
    -alias example.com -file example.cer
    

    The Gateway is now configured with a certificate for its host name, and you can use the host name to accept secure connections from clients over HTTPS or WSS.

  6. Configure the Gateway to accept secure communication requests at the same host name used in the certificate by adding a new directory service element.

    For example, create a new directory service element and specify URLs that use TLS/SSL (HTTPS or WSS) in the accept element for the directory service, as shown in the following example:

          <service>
            <accept>https://www.example.com:9000/</accept>
            <type>directory</type>
            <properties>
              <directory>/base</directory>
              <welcome-file>index.md</welcome-file>
            </properties>
          </service>
    
  7. Save gateway-config.xml.
  8. Verify that the certificate is valid by starting the Gateway. If the Gateway does not start, it might not be accepting the same host name used in the certificate. Check the directory service in gateway-config.xml and confirm that the domain name in the service element’s accept domain matches the domain name used in the certificate. If they do not match, update the accept domain in gateway-config.xml, save the file, and then start the Gateway.

    To troubleshoot TLS/SSL errors and exceptions, see Troubleshooting Kaazing Gateway Security.

    If you configured an HTTPS service on the Gateway, enter the URL in a web browser, for example https://www.example.com:9000. The web browser will indicate that the certificate is trusted and proceed to the secure web page.

    A web browser indicates that the certificate is trusted

    Figure: A web browser indicates that the certificate is trusted

    At this point, you have a trusted certificate on the Gateway and have configured secure networking between the Gateway and clients for a directory service.

    Secure Gateway-to-Server Connections

    **Note:** For secure connections from the Gateway to a JMS broker, see the note below.

    Now you can configure the Gateway to connect securely with the back-end server by importing a Certificate Authority-issued certificate for the host name of the back-end server into the truststore on the Gateway. The truststore contains the CA-issued certificates for use between the Gateway and back-end servers.

  9. Import the CA-issued certificate for the host name of the back-end server into the truststore in the Gateway (if you do not have a certificate for the host name of the back-end server, see step 4 for information on how to obtain it).

    The following example shows how to import the certificate to the truststore, called truststore.db, located in GATEWAY_HOME/conf/:

    keytool -importcert -keystore GATEWAY_HOME\conf\truststore.db -storepass changeit
    -trustcacerts -alias example.com -file certificate.cer
    

    The Gateway is configured with a certificate for the host name of the back-end server, and you can use the host name to connect to the back-end server over TLS/SSL. As an example, configure the Gateway to act as a back-end server proxy for the secure networking requests from the client.

  10. Open gateway-config.xml again and add a new proxy service element.

    Add a service element using the proxy type to gateway-config.xml, for example:

         <service>
            <accept>wss://www.example.com:9001/</accept>
            <connect>ssl://offline.example.com:61617</connect>
            <type>proxy</type>
          </service>
    

    The Gateway uses the new service element to act as a proxy for the back-end server. The service element contains an accept URL for the WSS connection from the client and a connect URL for the connection to the back-end server using the security protocol supported by the back-end server.

  11. Restart the Gateway and verify that the certificate is valid by using the WSS URL configured in the Gateway. If you cannot connect to the back-end server through the Gateway over TLS/SSL, verify the certificate has not expired and that it exists in the truststore.

Next Steps

To troubleshoot TLS/SSL errors and exceptions, see Troubleshooting Kaazing Gateway Security.

Notes

See Also