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 CA
s 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.
- 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
, ...
- For example:
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
- For example:
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.