Preparing for TLS

Note: RabbitMQ for Pivotal Cloud Foundry (PCF) v1.13 is no longer supported because it has reached the End of General Support phase. To stay up to date with the latest software and security updates, upgrade to a supported version.

This topic provides an overview of how to prepare for using Transport Layer Security (TLS) with the RabbitMQ on-demand service to secure communication between apps and service instances. The topic also includes the procedure for providing an existing CA certificate to BOSH CredHub, or generating a new CA certificate with BOSH CredHub.

Note: To enable TLS for RabbitMQ 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. If you want to change this certificate, see Rotating CA Certificates.

Overview

Enabling TLS provisions a RabbitMQ server with a certificate so that apps and clients can establish an encrypted connection with the data service. This certificate is a server certificate generated by CredHub, a component designed for centralized credential management in PCF, colocated 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 RabbitMQ server must have access to the public component of the CA certificate in order to use the certificate and to validate that the server certificate can be trusted.

PCF distributes the public component of the CA certificate to apps in two ways:

  • PCF provisions a copy of the CA certificate in the trusted store of each container’s operating system. Apps written in Java and Spring automatically discover the CA certificate in the trusted store.
  • PCF supplies the public CA certificate in an environment variable called VCAP_SERVICES that exists in every container. Apps not written in Java and Spring can retrieve the public component of the CA certificate from VCAP_SERVICES and use it to establish an encrypted connection with the data service.

Workflow for Enabling and Using TLS

The following workflow is required to enable TLS and to allow developers to use it with their apps:

  1. An operator provides a CA certificate to CredHub by completing the procedures in Provide or Generate a CA Certificate below.
  2. An operator enables TLS in the tile configuration while installing RabbitMQ for PCF. See Configure Security.
  3. A developer enables TLS for an existing service instance. See Configure TLS for Your Service Instance.
  4. A developer modifies their app to communicate securely with the RabbitMQ server. See one of the following links, depending on the type of app:

Note: An operator must also rotate the CA certificate if it expires or if it becomes compromised. For information on how to rotate your CA certificate, see Rotating CA Certificates.

Provide or Generate a CA Certificate

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.

Create a UAA Client

Follow these steps to create a UAA client for CredHub on your UAA server:

  1. 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 colocated on the BOSH Director VM.

  2. SSH into the Ops Manager VM by completing the steps in SSH into Ops Manager VM.

  3. From the Ops Manager VM, use the UAA Command Line Interface (UAAC) to target the UAA server on the BOSH Director VM. In the UAAC command, specify the IP address for the BOSH Director VM and port 8443.

    Run the following command:

    uaac target BOSH-DIRECTOR:8443
    


    Where BOSH-DIRECTOR is the IP address of the BOSH Director VM. You retrieved this address as part of the procedures in Step 1.

    For example:

    $ uaac target 10.0.0.5:8443
    

  4. In the Credentials tab of the Ops Manager Director tile, retrieve the Uaa Login Client Credentials and record the identity and password values.

    Note: These are the credentials for the UAA server colocated on the BOSH Director, not the UAA server colocated on Pivotal Application Service.

  5. From the Ops Manager VM, use the UAAC to get a token.

    Run the following command:

    uaac token owner get login --secret=UAA-LOGIN-CLIENT-CRED
    


    Where UAA-LOGIN-CLIENT-CRED is the password value of the Uaa Login Client Credentials that you retrieved in Step 4 above.

    For example:

    $ uaac token owner get \
        login --secret=abcdefghijklm123456789
    

  6. When prompted for a user name and password, enter the values for identity and password of the Uaa Admin User Credentials you retrieved in step 4 above.

    For example:

    User name:  admin
    Password:  ********************************
    

  7. Add a UAA client for CredHub with the correct grants.

    Enter the following command:

    $ uaac client add \
        --authorized_grant_types client_credentials \
        --authorities credhub.read,credhub.write
    
  8. When prompted for Client ID, enter credhub. When prompted for New client secret, enter a secure password of your choice. For example:

    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
    

Add the CA Certificate

Follow these steps to log in to CredHub, provide or generate a CA certificate, and add the certificate to Ops Manager:

  1. From the Ops Manager VM, set the API target of the CredHub CLI to your CredHub server.

    Run the following command:

    credhub api https://BOSH-DIRECTOR:8844 --ca-cert=/var/tempest/workspaces/default/root_ca_certificate
    


    Where BOSH-DIRECTOR is the IP address of the BOSH Director VM.

    For example:

    $ credhub api https://10.0.0.5:8844 --ca-cert=/var/tempest/workspaces/default/root_ca_certificate
    

  2. Log in to CredHub.

    Run the following command:

    credhub login --client-name=credhub --client-secret=CLIENT-SECRET
    


    Where CLIENT-SECRET is the New client secret you set in step 8 in the procedure above.

    For example:

    $ credhub login \
        --client-name=credhub \
        --client-secret=abcdefghijklm123456789
    

  3. Use the CredHub CLI to generate a CA certificate or provide an existing one.

    Note: Your PCF deployment may 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. Enter the following command:
      $ credhub generate \
          --name="/services/tls_ca" \
          --type="certificate" \
          --is-ca \
          --common-name="rootCA"
      
    • If you have an existing CA certificate that you want to use, create a new file called root.pem with the contents of the certificate. Then enter the following command, specifying the path to root.pem and the private key for the certificate. For example:
      $ credhub set \
          --name="/services/tls_ca" \
          --type="certificate" \
          --certificate=./root.pem \
          --private=ERKSOSMFF...
      
  4. Use the BOSH CLI v2 to extract the certificate portion from the CA certificate and print it. Run the following command:

    $ bosh2 int <(credhub get \
    --name=/services/tls_ca) \
    --path /value/certificate
    
  5. Copy the output.

  6. Navigate to the Ops Manager Installation Dashboard and select the BOSH Director tile. Click Security.

  7. Paste the contents of the CA certificate into Trusted Certificates, and then click Save.

  8. After preparing your environment for TLS, you must enable TLS in the tile configuration, following the appropriate step below.

    WARNING: Restarting all of the VMs in your PCF deployment in order to apply a CA certificate takes a long time to complete.

    • For an Existing Installation: Complete the steps in Configure Security to enable TLS in the tile, click Review Pending Changes, and then click Apply Changes in the Installation Dashboard. This restarts all the VMs in your PCF deployment and applies your CA certificate.

      Note: Make sure the upgrade-all-service-instances errand is set to On. This errand must be run to ensure all service instances have the needed changes.

    • For a New Installation: Complete the procedures in Installing and Configuring RabbitMQ for PCF, including enabling TLS in the Security for On-Demand Plans tab, click Review Pending Changes, and then click Apply Changes in the Installation Dashboard. This deploys RabbitMQ for PCF, restarts all the VMs in your PCF deployment, and applies your CA certificate.