Configuring HTTPS

This document describes the HTTPS (SSL/TLS) certificate requirements for deploying your Apcera cluster in production, and how to configure Apcera to service HTTPS requests from clients.

HTTPS requirements

You can use HTTP or HTTPS (HTTP over SSL/TLS) for your cluster. Apcera recommends using HTTPS for production clusters. You need an SSL/TLS private key, a Certificate Signing Request (CSR), a certificate from the Certificate Authority, and the intermediate trust chain as well. You use this information to populate the cluster.conf file.

Considerations for using HTTPS

If you are deploying a load balancer in front of Apcera routers, enabling HTTPS will use SSL/TLS between the load balancer and Apcera routers. Configuring HTTPS between the client and the load balancer is the responsibility of your load balancer administrator.

When you add HTTPS support to a Apcera cluster, you must consider what DNS namespace you want to secure. For example, consider the cluster name In this example, there are three locations where the desired DNS namesapce must match:

1) The Subject Alternative Name (SAN) field of a certificate

Most browsers limit wildcard support to one level on the far left side per SAN entry. This restriction is imposed by the x509 spec for wildcards. Any HTTPS implementation that accepts multi level wildcards is non-compliant with the spec. The x509 spec is explicit that the wildcard only matches a single token and must be the left most token in the name.

2) The server_names configuration option defined in cluster.conf

This attribute informs the router which certificate should be presented based on the hostname requested in the client. More than one tlshosts may be defined in situations where more than one set of server_names,certificate_chain,private_key are required.

If you are using multiple tlshosts, each cert is a separate entry in cluster.conf. Each “server_names” entry must match the Subject Alternative Names (SAN) DNS of the certificate. See the example.

3) The route defined for a Apcera app

Once HTTPS is configured, the following will be true:

  • All routes will automatically have HTTPS enabled in addition to HTTP.

  • Supported HTTPS clients connecting to any route which matches both a server_names entry and matches a certificate's SAN will be accessible via HTTPS.

  • Supported HTTPS clients accessing a route which does not match any server_names in any tlshosts entries are presented the certificate_chain of first tlshosts entry, which will likely result in an "invalid certificate" error on the client. We recommend that the first tlshosts entry be for a hostname (or wildcard) which you are willing to disclose to the public in error situations. For example, Apcera uses * for public disclosure. The next tlshosts entry should protect the base_domain of the cluster and include one level of wildcard. Next can come any number of additional tlshosts for additional applications.

Configuring HTTPS

Prerequisites for configuring HTTPS:

End of life clients:

  • Only TLS is supported. SSL is not supported.
  • Windows XP with Internet Explorer is not supported.

HTTPS client requirements

Apcera reserves the right to exercise our best judgment in adapting the list of cryptographic protocols, ciphers and other details as the public security landscape changes. For the time being, here is a partial list of what is supported.

1) HTTPS client must support Server Name Indication (SNI)

  • Review RFC 6066 for more info (

2) Supported cryptographic protocols:

  • TLSv1
  • TLSv1.1
  • TLSv1.2

3) Supported ciphers:

  • EDH+aRSA

Certificate requirements

1) For production systems, a certificate issued from a Certificate Authority trusted by the expected client population is recommended.

2) The list of Apcera Routes identified as requiring HTTPS must be included in the Subject Alternative Name of one (or more) certificates. Wildcards are supported.

3) Certificate and private key must be in the format of ASCII armored, Base64 encoded text ("PEM format") to be included in the cluster.conf file. The certificate text must also be in UNIX file format, not DOS file format. (There can be no hidden DOS characters at the end of each line).

NOTE: Certificates may be converted from one encoding to another. Use the openssl command line tool to perform the conversion.

Security and Patching considerations

Apcera packages security updates with Apcera. Performing a cluster deploy will install the most recent security updates.

Update firewall rules for HTTPS support

If you enable HTTPS you must update firewalls external to Apcera to allow traffic from the desired clients to the https_port.

See required ports for the HTTP Router.

HTTPS Configuration Example

HTTPS support must be configured using the Orchestrator tool via the corresponding cluster.conf file.

Here is an example cluster.conf file snippet with HTTPS configured. Follow this format to configure HTTPS using cluster.conf.

chef: {
   "continuum": {
      "router": {
         # port to listen on for HTTPS
         "https_port": 443,
         "ssl": {
            # set to true to enable HTTPS (TLS) Support
            # ensure that at least one tlshosts is defined
            "enable": true,

            # Each tlshosts entry relates to a certificate chain and a private key.
            # To run the cluster over HTTPS, provide 1 or more tlshosts.server_names
            # entries that include the `base_domain` and the wildcard `*.base_domain`
            # that match the system-created routes based upon the base_domain value.
            # Each additional tlshost is defined as an additional server_names entry.
            # Each server certificate requires its own tlshosts entry. Certificates and
            # private key must be in the format of ASCII armored, Base64 encoded text
            # ("PEM format").
            # Each "certificate_chain" must begin with a server certificate. The only
            # additional certificates that may be included in a chain are certificates
            # which include the signature of the certificate before it, ending in the
            # root certificate.
            # Only one private_key is permitted per tlshost entry. It is related to the
            # first certificate in the related certificate_chain.

            # If you have multiple tlshosts, each is a separate server_names entry.
            # The “server_names” field must match the SAN DNS of the certificate.
            "tlshosts": [
                  "server_names": ["*", ""],
                  # Certificate chain
                  "certificate_chain": (-----BEGIN CERTIFICATE-----
                     # Contents of Server Certificate
                     -----END CERTIFICATE-----
                     -----BEGIN CERTIFICATE-----
                     # Contents of Intermediate Certificate (optional)
                     -----END CERTIFICATE-----
                  # Private key
                  "private_key":(-----BEGIN RSA PRIVATE KEY-----
                     -----END RSA PRIVATE KEY-----
                  "server_names": ["*", ""],
                  "certificate_chain": (-----CERT-----)
                  "private_key":(-----PRIVATE KEY-----)
            ] # tlshosts
         } # ssl
      } # router
   } # continuum
} # chef

Updating SSL Certs

If you need to update an SSL certficate chain, replace both the certificate and the private key in the cluster.conf, as the key and Certificate Signing Request (CSR) will be regenerated, and then redeploy the cluster. Assuming no other configuration changes, you can use the --machines flag to target the machine host role where the HTTP router(s) is installed, such as central.

You can use the following command to get information from a cert file:

openssl x509 -in my.chained.crt -noout -text

For example:

    Issuer: C=US, O=CaCert Inc, CN=CaCert SHA2 Secure Server CA
        Not Before: Apr 18 00:00:00 2017 GMT
        Not After : May  9 12:00:00 2018 GMT
    Subject: C=US, ST=California, L=San Francisco, O=Acme, Inc., CN=*

Generating SSL Cert and Key

If necessary you can create your own self-signed certificate and key using OpenSSL.

Copy the system file openssl.cnf (on Mac the path is /System/Library/OpenSSL/openssl.cnf) to your local working directory and edit it by adding the following line to the [ v3_ca ] section:

[ v3_ca ]

# Extensions for a typical CA
subjectAltName = ${ENV::SUBJECTALTNAME}

On Unix machines (Mac and Linux), run the following shell script, replacing the cluster-name and domain.tld values with your own.


(umask 077 && openssl genrsa -out ${CLUSTER:?}.key 2048 )

openssl req -x509 -nodes -days 3650 \
-config openssl.cnf \
-new -key ${CLUSTER:?}.key -out ${CLUSTER:?}.crt \
-subj "/C=US/ST=California/L=San Francisco/O=The Zoo, Inc./CN=*.${DOMAIN:?}"

Run the following command:

openssl x509 -in mycert.crt -noout -text | less

This will result in the following for the cert:

        X509v3 extensions:
            X509v3 Subject Alternative Name:
                DNS:*.cluster.domain.tld, DNS:cluster.domain.tld