Configuring SSL#

The server node uses NGINX to proxy all incoming http(s) requests to the server running on a local port, and uses NGINX for SSL termination. The default setup uses http—non-SSL—since cert files are required to configure SSL and each enterprise will have their own cert files.

The www.enterprise.conf file is the default nginx.conf file used for AEN. It is copied to the /etc/nginx/conf.d directory during server installation.

NOTE: This section describes setting up SSL after your gateway node has been installed and registered with the server node.

Copying the required files#

To configure SSL on AEN, you will need the following files:

  • Server certificate and key

  • Server CA bundle

  • Gateway certificate and key

  • Gateway CA bundle

Configure SSL on AEN:

  1. Copy the Gateway certificate and key to /opt/wakari/wakari-gateway/etc/ on the Gateway as gateway.crt and gateway.key.

  2. Copy the Gateway CA bundle to /opt/wakari/wakari-server/etc/ on the Server.

  3. Copy the Server certificate and key to /etc/nginx on the Server as server.crt and server.key.

  4. Copy the Server CA bundle to /opt/wakari/wakari-gateway/etc/ on the Gateway.

If you have a certificate that was signed by a private root CA and/or an intermediate authority:

  • The Gateway CA bundle must contain the full chain: root CA, any intermediate authority and the certificate.

    cat gateway.crt intermediate.crt root.crt >> gatway-crt-int-root.crt
    
  • The Server CA bundle must be separated into individual files for the root CA, any intermediate and the certificate.

Configuring SSL on the server node#

The www.enterprise.https.conf is an NGINX configuration file for SSL. It is set up to use the server.crt and server.key cert files.

CAUTION: You must change these values to point to the signed cert files for your domain.

NOTE: Self-signed certs or those signed by a private root CA require additional configuration.

Perform the following steps as root:

  1. Stop NGINX:

    service nginx stop
    
  2. Move the /etc/nginx/conf.d/www.enterprise.conf file to a backup directory.

  3. Copy the /opt/wakari/wakari-server/etc/nginx/conf.d/www.enterprise.https.conf file to /etc/nginx/conf.d.

    NOTE: /etc/nginx/conf.d may have www.enterprise.conf or www.enterprise.https.conf but it may not have both.

  4. Edit the /etc/nginx/conf.d/www.enterprise.https.conf file and change the server.crt and server.key values to the names of the real cert and key files if they are different.

  5. Restart NGINX by running:

    service nginx start
    
  6. Update the WAKARI_SERVER and CDN settings to use https instead of http in the following configuration files:

    /opt/wakari/wakari-server/etc/wakari/config.json
    /opt/wakari/wakari-gateway/etc/wakari/wk-gateway-config.json
    /opt/wakari/wakari-compute/etc/wakari/config.json
    
  7. Copy the gateway certificate, gateway.crt to /opt/wakari/wakari-server/etc/.

  8. In an editor, open /opt/wakari/wakari-server/etc/wakari/wk-server-config.json and add:

    "verify_gateway_certificate": "/opt/wakari/wakari-server/etc/gateway.crt"
    
  9. Restart AEN services on the server by running:

    service wakari-server restart
    

    NOTE: This step may return an error since the gateway has not yet been configured for SSL.

  10. In AEN, verify that the browser uses https. On the Admin Settings page, under Data Centers, click Gateway, then select https:

Configuring SSL on the gateway#

  1. For all types of SSL certificates, in /opt/wakari/wakari-gateway/etc/wakari/wk-gateway-config.json, add:

    {
        EXISTING_CONFIGURATION,
        "https": {
            "key": "/opt/wakari/wakari-gateway/etc/gateway.key",
            "cert": "/opt/wakari/wakari-gateway/etc/gateway.crt"
        }
    }
    
  2. For a server certificate signed by a private root CA or signed by an intermediate authority, add:

    {
        EXISTING_CONFIGURATION,
        "https": {
            "key": "/opt/wakari/wakari-gateway/etc/gateway.key",
            "cert": "/opt/wakari/wakari-gateway/etc/gateway.crt",
            "ca": ["/opt/wakari/wakari-gateway/etc/server.crt"]
        }
     }
    

    NOTE: When the certificate chain has more than one intermediate cert signed by a higher root CA authority, you must manually break up the certs in the chain into individual files, and enumerate them in the ca key:

    {
       EXISTING_CONFIGURATION,
       "https": {
           "key": "/opt/wakari/wakari-gateway/etc/gateway.key",
           "cert": "/opt/wakari/wakari-gateway/etc/gateway.crt",
           "ca": ["/opt/wakari/wakari-gateway/etc/server1.crt",
                  "/opt/wakari/wakari-gateway/etc/server2.crt",
                  "/opt/wakari/wakari-gateway/etc/server3.crt"]
        }
     }
    
  3. For a gateway certificate that is encrypted using a passphrase, add:

    {
       EXISTING_CONFIGURATION,
       "https": {
           "key": "/opt/wakari/wakari-gateway/etc/gateway.key",
           "cert": "/opt/wakari/wakari-gateway/etc/gateway.crt",
           "passphrase": "mysecretpassphrase"
        }
     }
    

    NOTE: Alternatively, the passphrase can be passed using an environment variable or entered when the wakari-gateway service is manually started.

    EXAMPLES:

    # using an environment variable
    AEN_GATEWAY_SSL_PASSPHRASE='mysecretpassphrase' wk-gateway
    
    # starting wakari-gateway manually
    sudo service wakari-gateway start --ask-for-passphrase
    Passphrase?
    
  4. Restart the gateway:

    sudo service wakari-gateway restart
    

Configuring SSL on compute nodes#

Anaconda Enterprise does not support direct SSL on Compute Nodes. If you need SSL on Compute Nodes, you must install each Compute Node on the same server as a Gateway using http://localhost:5002 for the URL value while adding it as a resource, and you must use a Gateway for each and every Compute Node.

Security reminder#

The permissions on the cert files must be set correctly to prevent them from being read by others. Since NGINX is run by the root user, only the root user needs read access to the cert files.

EXAMPLE: If the cert files are called server.crt and server.key, then use the root account to set permissions:

chmod 600 server.key
chmod 600 server.crt

Enabling or disabling the Strict-Transport-Security header#

By default, Strict-Transport-Security (STS) is enabled in the www.enterprise.https.conf file:

add_header Strict-Transport-Security max-age=31536000;

It can remain enabled if either of the following is true:

  • The gateway is running on a different host than the server.

    or

  • SSL has been enabled for the gateway.

You must comment out this line if both of the following are true:

  • The gateway is running on the same host as the server.

    and

  • SSL has not been enabled for the gateway.

Leaving STS enabled when these conditions are true will cause a mismatch in protocols between the server and gateway, causing your apps to fail to launch correctly.