Preparing for TLS
Page last updated:
This topic provides an overview of how to prepare for using Transport Layer Security (TLS)
with the Redis on-demand service to secure communication between apps and service instances.
This topic also includes procedures for providing an existing CA certificate to BOSH CredHub and generating a new CA certificate with BOSH CredHub.
Warning: To enable TLS for Redis for PCF,
you must perform the procedures in
Provide or Generate a CA Certificate
below before installing and configuring the tile.
This certificate is shared by multiple tiles. If you have already performed this procedure, you do not need to repeat it. To change this certificate, follow the steps in Rotating Certificates.
Enabling TLS co-locates a second TLS-enabled port on Redis for PCF service instances.
Apps and clients can use this port to establish encrypted connections with the data service.
The certificate used in this connection is a server certificate generated by CredHub.
CredHub is a component designed for centralized credential management in PCF and is co-located on the BOSH Director. CredHub generates the server certificate with a Certificate Authority (CA). The operator can provide a certificate to CredHub or have CredHub generate a new certificate.
Apps and clients that communicate with the Redis for PCF server must have access to the public component of the CA certificate to use the certificate and check that it is trustworthy.
PCF distributes the public component of the CA certificate by provisioning a copy of the CA certificate in the trusted store of each container’s operating system. Apps written in Java and Spring, or C# and Steeltoe, automatically discover the CA certificate in the trusted store.
The following workflow is required to enable TLS and to allow developers to use it with their apps:
- An operator does one of the following:
- If you are using Ops Manager 2.5 or earlier or want to provide a custom certificate, an operator provides a CA certificate to CredHub by completing the procedures in Provide or Generate a CA Certificate below.
- If you are using Pivotal Ops Manager v2.6 or later, a default CA certificate is provided by Ops Manager. You do not need to generate the CA certificate. To use the default CA certificate, do the last two steps in Add the CA Certificate below.
- An operator enables TLS Optional in the tile configuration while installing Redis for PCF. For more information, see On-Demand Service Settings.
- An app developer modifies their app to communicate securely with the Redis server. For more information, see Using TLS.
Note: An operator must also rotate the CA certificate if it expires or if it becomes compromised. For information about how to rotate your CA certificate, see Rotating CA Certificates.
To enable and use TLS, you must complete the procedures below before installing and configuring the tile.
Warning: This procedure requires restarting all of the VMs in your PCF deployment in order to apply a CA certificate. This operation can take a long time to complete.
Note: If you are using Pivotal Ops Manager v2.6 or later and want to use the default CA certificate provided by Ops Manager, do not do the following procedure.
Follow these steps to create a UAA client for CredHub on your UAA server:
Retrieve the IP address of the BOSH Director VM and the Director credentials by completing the steps in Gather Credential and IP Address Information.
Both the UAA and CredHub servers are co-located on the BOSH Director VM.
SSH into the Ops Manager VM by following the steps in SSH into Ops Manager VM.
From the Ops Manager VM, target the UAA server on the BOSH Director VM by running the following command in the UAA Command Line Interface (UAAC):
uaac target BOSH-DIRECTOR-IP:8443
BOSH-DIRECTOR-IPis the IP address of the BOSH Director VM and
8443is the port to use. You retrieved the BOSH Director IP address in step 1.
$ uaac target 10.0.0.5:8443
In the Credentials tab of the BOSH Director tile, retrieve and record the
- UAA Login Client Credentials
- UAA Admin User Credentials
Note: These are the credentials for the UAA server that is co-located on the BOSH Director, not the UAA server that is co-located on Pivotal Application Service (PAS).
From the Ops Manager VM, use the UAAC to get a token by running the following command:
uaac token owner get login --secret=UAA-LOGIN-CLIENT-CRED
passwordvalue of the UAA login client credentials that you retrieved in the previous step.
$ uaac token owner get \ login --secret=abcdefghijklm123456789
When prompted for a username and password, enter the values for
passwordof the UAA Admin User Credentials that you retrieved in the previous step.
User name: admin Password: ********************************
Add a UAA client for CredHub with the correct grants by running the following command:
uaac client add \ --authorized_grant_types client_credentials \ --authorities credhub.read,credhub.write
When prompted for a client ID, enter
When prompted for a new client secret, enter a secure password of your choice.
Client ID: credhub New client secret: ******* Verify new client secret: ******* scope: uaa.none client_id: credhub resource_ids: none authorized_grant_types: client_credentials autoapprove: authorities: credhub.write credhub.read name: credhub required_user_groups: lastmodified: 1518198701452 id: credhub created_by: f609e861-39ec-4a16-8aee-cba9e9b079e3
Note: If you are using Pivotal Ops Manager v2.6 or later and want to use the default CA certificate provided by Ops Manager, only do the last two steps in this procedure.
Follow the steps below to log in to CredHub, provide or generate a CA certificate, and add the certificate to Ops Manager.
From the Ops Manager VM, set the API target of the CredHub CLI as your CredHub server by running the following command:
credhub api https://BOSH-DIRECTOR:8844 --ca-cert=/var/tempest/workspaces/default/root_ca_certificate
BOSH-DIRECTORis the IP address of the BOSH Director VM.
$ credhub api https://10.0.0.5:8844 --ca-cert=/var/tempest/workspaces/default/root_ca_certificate
Log in to CredHub by running the following command:
credhub login --client-name=credhub --client-secret=CLIENT-SECRET
CLIENT-SECRETis the new client secret you created earlier in Create a UAA Client.
$ credhub login \ --client-name=credhub \ --client-secret=abcdefghijklm123456789
Check whether a services CA certificate already exist by running the following command:
credhub get --name="/services/tls_ca"
If you already have a certificate at the
services/tls_capath, skip step 4.
Use the CredHub CLI to generate a CA certificate or provide an existing one.
Note: Your PCF deployment can have multiple CA certificates. Pivotal recommends a dedicated CA certificate for services.
If you do not have a CA certificate, use the CredHub CLI to generate one by running the following command:
credhub generate \ --name="/services/tls_ca" \ --type="certificate" \ --no-overwrite \ --is-ca \ --common-name="rootCA"
If you have a CA certificate that you want to use, create a new file called
root.pemwith the contents of the certificate. Then run the following command, specifying the path to
root.pemand the private key for the certificate.
$ credhub set \ --name="/services/tls_ca" \ --type="certificate" \ --certificate=./root.pem \ --private=ERKSOSMFF...
certificateportion from the CA certificate and print it by running the following command in BOSH CLI v2:
bosh int <(credhub get \ --name=/services/tls_ca) \ --path /value/certificate
Copy the output.
Navigate to the Ops Manager Installation Dashboard and select the BOSH Director tile.
Paste the contents of the CA certificate into Trusted Certificates and then click Save.
Ensure relevant app security groups are open for port 16379. This can be done through the cf CLI. For more information, see Managing ASGs with the cf CLI.
After preparing your environment for TLS, enable TLS in the tile configuration by following the appropriate step below.
Warning: Restarting all of the VMs in your PCF deployment to apply a CA certificate takes a long time to complete.
- For an existing installation:
- Complete the steps in Upgrade to Redis for PCF v2.2 to enable TLS in the tile.
- Click Review Pending Changes.
- Ensure the
upgrade-all-service-instanceserrand is set to On.
- Click Apply Changes in the Installation Dashboard. This restarts all the VMs in your PCF deployment and applies your CA certificate. This causes downtime to all on-demand service instances.
- For a new installation:
- Complete the procedures in On-Demand Service Settings, including enabling TLS in the On-Demand Service Settings tab.
- Click Review Pending Changes.
- Click Apply Changes in the Installation Dashboard. This deploys Redis for PCF, restarts all the VMs in your PCF deployment, and applies your CA certificate.
After enabling TLS Optional, app developers must modify their apps to communicate over TLS. For more information, see Using TLS.