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.

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.

Prerequisites for configuring HTTPS

  • Supported certificate and related private key
  • Supported HTTPS client

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.

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

Please update firewalls external to Apcera to allow traffic from the desired clients to the https_port.

Configuration format for cluster.conf

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

Here is an example cluster.conf file with HTTPS configured:

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 tlshost relates a list of server_names to a certificate chain
            # and a private key. The first entry should be the public name 
            # of the continuum cluster. This may or may not be the same as cluster's
            # base_domain. Next should come the base_domain and a wildcard entry for one 
            # level below the base_domain for Apcera services. Any additional tlshosts
            # may be defined after the second 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.
            "tlshosts": [
               "server_names": ["*", ""],

               "certificate_chain": (-----BEGIN CERTIFICATE-----
# Contents of Server Certificate
# Contents of Intermediate Certificate (optional)

               "private_key":(-----BEGIN RSA PRIVATE KEY-----
            ] # tlshosts
         } # ssl
      } # router