Configure TLS

danger

This feature is not fully released yet!

We strongly recommend to test this feature in testing environments and do not deploy to production environments yet.

Prerequisites

---

One of the supported components is the a9s SSO Proxy. We're using it to restrict access to the Service Dashboard to only authenticated users. The authentication will be handled by the Cloud Foundry UAA. Cloud Foundry secures all its APIs with a component named Gorouter. The Gorouter is the entrypoint for requests to the CloudFoundry APIs. This Gorouter is secured by default with TLS.

In order to communicate with the Gorouter, we need to make the certificate which secures the Gorouter available in CredHub under a specific path. The Ops-files expect that the certificate is stored under the path /cf_router_ssl.

This enables us to use this certificate in our BOSH deployment manifests, to authenticate the requests from the a9s SSO Proxy to the CloudFoundry APIs.

The first step is to export the TLS certificate of the Gorouter from CredHub which is in use by the BOSH Director, where CloudFoundry (BOSH deployment name e.g. cf) runs.

The path for the certificate is /<Name of BOSH director>/<Name of CloudFoundry deployment>/router_ssl.

You can get the name of your current BOSH director by executing:

bosh env --json | jq '.Tables[0].Rows[0].name' -r

Hint: The CredHub paths are always built by the same schematic. It is always /<BOSH Director name>/<BOSH Deployment name>/<Manifests variable name>, where the Manifests variable name can be found in the respective BOSH deployment manifest under variables. You can search for all variables in you BOSH deployment manifest with:

bosh interpolate <BOSH Deployment manifest> --path /variables

Furthermore, whether the Certificate Authorities (CAs) used in the deployments are self-signed, the second step is to add the a9s Components CAs in the trust-store of the Gorouter virtual machine (VM) from Cloud Foundry. For more information, have a look at the Certificate Authority Overview. You don't need to add the certificates to the Gorouter's trust-store when you're using certificates which are signed by a globally trusted Certificate Authority.

Export the CredHub Variable

---

You need to set the following environment variables in order to proceed:

export BOSH_DIRECTOR_NAME=$(bosh env --json | jq '.Tables[0].Rows[0].name' -r)
export CLOUDFOUNDRY_DEPLOYMENT_NAME=cf

Please make sure that:

• The variable /<BOSH Director name>/<CloudFoundry deployment name>/router_ssl exists.

  • Use

    credhub get -n /${BOSH_DIRECTOR_NAME}/${CLOUDFOUNDRY_DEPLOYMENT_NAME}/router_ssl

    to verify this.

To export the certificate from CredHub follow these instructions:

# Export private key
credhub get -k private_key -n "/${BOSH_DIRECTOR_NAME}/${CLOUDFOUNDRY_DEPLOYMENT_NAME}/router_ssl" > router_private_key.pem

# Export certificate
credhub get -k certificate -n "/${BOSH_DIRECTOR_NAME}/${CLOUDFOUNDRY_DEPLOYMENT_NAME}/router_ssl" > router_certificate.pem

# Export ca
credhub get -k ca -n "/${BOSH_DIRECTOR_NAME}/${CLOUDFOUNDRY_DEPLOYMENT_NAME}/router_ssl" > router_ca.pem

You should now have three files in your current path, containing the private_key, certificate, and ca.

Set the CredHub Variable

---

We can now use those three files to create a new variable in CredHub where the Ops-file expects the certificate which is used by the Gorouter.

credhub set -n "/cf_router_ssl" -t certificate -c router_certificate.pem -p router_private_key.pem -r router_ca.pem

The output should be similar to:

id: <GUID>
name: /cf_router_ssl
type: certificate
value: <redacted>
version_created_at: <TIMESTAMP>

Add the Component CAs to the Gorouter

This step must be done when using self-signed certificates.

It is necessary to add the Root CA (/a9s_components_ca) and the Intermediate CA for the SSO Proxy of each data service (/a9s_[data_service]_sso_proxy_ca) to the trust-store of the Gorouter VM of Cloud Foundry.

The Gorouter BOSH release provides a BOSH property to configure certificates that are trusted by the Gorouter.

In order to trust the self-signed certificates, we need to append those to the already existing ones.

1. Extend the BOSH Property router.ca_certs:

Please make sure beforehand that the certificates exist in CredHub!

jobs:
- name: gorouter
  properties:
    router:
      ca_certs: |
        ...[other certificates]...
        ((/a9s_components_ca.certificate))
        ((/a9s_[data_service]_sso_proxy_ca.certificate))

Please keep in mind to replace [data_service] with the data services name, e.g.: rabbitmq, postgresql, and so forth.

Certificate Authority Overview

---

In simple words, Certificate Authorities (CA) are used to create, sign, and authenticate certificates.

All certificates used by our components are inherited by the root CA stored in CredHub with the path /a9s_components_ca. This CA is used to sign all other intermediate CAs, and the intermediate CAs are used to sign the leaf certificates, which are in turn used to provide the TLS endpoints of our components.

The reason why we have decided to use intermediate CAs is that in case of a compromised certificate, we keep the number of affected certificates as low as possible. This results then in a lower amount of instances that needs to be updated.

An overview can be found here, where

• [data_service] is the name of the Data Service

  • For example: messaging, postgresql, mysql, mariadb, redis, logme, ...

• The Components Certificate CredHub path is stored under /<BOSH director name>/<BOSH Deployment name>/<Components Certificate name>

  • For example:
    • /<BOSH Director name>/messaging-service/a9s_messaging_broker_tls_cert
    • /<BOSH Director name>/postgresql-service/a9s_postgresql_deployer_tls_cert

Root CA	Intermediate CA	Components Certificate
/a9s_components_ca	/a9s_[data_service]_broker_ca	a9s_[data_service]_broker_tls_cert
	/a9s_[data_service]_spi_ca	a9s_[data_service]_spi_tls_cert
	/a9s_[data_service]_deployer_ca	a9s_[data_service]_deployer_tls_cert
	/a9s_[data_service]_sso_proxy_ca	a9s_[data_service]_sso_proxy_tls_cert

Using a Pre-Existing CA Certificate

---

If you want to use a pre-existing CA certificate, for example one from your company, please follow these instructions before deploying the a9s Data Services and service instances. If you have running Data Services and Service Instances that are using certificates of a CA from your company, please use exactly this CA certificate for the next steps.

To force BOSH to inherit from your own CA, we need to set the CredHub variable /a9s_components_ca manually first. This requires the following files:

• The CA certificate
• The CA certificates private key

You don't necessarily need to set this certificate (/a9s_components_ca) upfront. You can skip this step and CredHub will create a self-signed certificate on deployment.

They both need to be in PEM format.

Please make sure that the CA certificate has the CA:TRUE flag

openssl x509 -in [CA_Certificate_File] -text -noout | grep 'CA:'

If so, we can start to set the CredHub variable. For this, create two files, one containing the certificate and one containing the corresponding private key.

Use this command to set the new certificate:

credhub set -t certificate -n '/a9s_components_ca' -c [CA_Certificate] -r [CA_Certificate] -p [CA_Certificate_Private_Key]

This way, we are setting the root CA certificate upfront, before CredHub does it when deploying the Data Service manifest. All certificates listed in the Certificate Authority Overview under Intermediate CA and Components Certificate are now created and signed from your own CA certificate.

General Configuration

---

This is the configuration of the TLS properties for each supported component in the BOSH deployment manifests:

protocols:
  http:
    enabled: true
    port: 3000
  https:
    enabled: true
    port: 3001
    ca: ((example_certificate.ca))
    cert: ((example_certificate.certificate))
    key: ((example_certificate.private_key))

Enable or Disable Endpoints

---

It is possible to

• have only plain-text endpoints (HTTP) enabled
• have only TLS secured endpoints (HTTPS) enabled
• have both enabled at the same time

by setting the enabled property to either true or false.

danger

We strongly advise you to not permanently enable both protocols at the same time.

This is only useful for the transition of the a9s Framework from plain-text HTTP to TLS secured HTTPS communication of the components.

Ports

---

The old default port for most of our components is 3000. To keep compatibility and not break the environment, we recommend to still using port 3000 for the plain-text (HTTP) endpoint, until the transition to TLS secured communication (HTTPS) is fully done and tested.

The port for the TLS interface is always HTTP port + 1, so in most of the cases 3001.

An overview of the used ports in the a9s Framework can be found in the ports overview.

Errands

---

The template-uploader errand can be configured to communicate via TLS with the a9s Deployer API:

properties:
  anynines_service_broker:
    bosh_deployer:
      api_endpoint: https://[data_service]-service-deployer.service.dc1.consul.example:3001
      skip-ssl-validation: false
      ca: ((/a9s_deployer_ca.certificate))((/a9s_components_ca.certificate))
      password: ((/[data_service]_service_deployer_password))
      username: admin

Please keep in mind to replace [data_service] with the data services name, e.g.: rabbitmq, postgresql, and so forth.

The deployment-updater errand can be configured to communicate via TLS with the a9s Service Broker:

properties:
  deployment-updater:
    force-update: true
    service-broker-host: [data_service]-service-broker.service.dc1.consul.example
    service-broker-password: ((/[data_service]_service_broker_password))
    service-broker-protocol: 'https'
    service-broker-port: 3001
    service-broker-skip-ssl-validation: false
    service-broker-username: admin
    service-broker-ca: ((/a9s_[data_service]_broker_ca.certificate))((/a9s_components_ca.certificate))

Please keep in mind to replace [data_service] with the data services name, e.g.: rabbitmq, postgresql, and so forth.