Preparing for TLS

WARNING: As of PCC v1.6.2, PCC increases security by requiring TLS encryption for gfsh and Pulse. Complete the procedures in this topic before installing the PCC tile as part of an upgrade.

This topic describes how to provide an existing Certificate Authority (CA) certificate to BOSH CredHub and how to generate a new CA certificate with BOSH CredHub, if you do not already have one.

WARNING: This procedure involves restarting all of the VMs in your PCF deployment in order to propagate a CA certificate. The operation can take a long time to complete.

Overview

Enabling TLS provisions PCC service instances with a certificate so that apps, gfsh, and Pulse can establish an encrypted connection with the PCC service instance.

The certificate deployed on the PCC service instance is a server certificate. The server certificate is generated by CredHub, a component designed for centralized credential management in PCF. CredHub is deployed on the same VM as the BOSH Director.

CredHub generates the server certificate using a Certificate Authority (CA) certificate. The CA certificate must be provided to CredHub by the operator or generated by CredHub.

Apps use the CA certificate to authenticate components of PCC service instances. Apps that communicate with PCC must have access to the CA certificate in order to validate that the server certificate can be trusted.

WARNING: An operator must rotate the CA certificate if it expires or if it becomes compromised. To rotate your CA certificate, see Rotating CA Certificates for Pivotal Cloud Foundry Services in the Pivotal Knowledge Base. Do not attempt to rotate a CA certificate on your own. Contact Pivotal Support and perform the procedure in the Pivotal Knowledge Base article with their assistance.

Provide or Generate a CA Certificate

Perform the following procedures to create a User Account and Authentication (UAA) client for CredHub, log in to CredHub, and provide or generate a CA certificate.

Create a UAA Client

Perform the following 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 performing 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 performing 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 from the Status tab of the Ops Manager Director tile 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. Retrieve the UAA Admin User Credentials and record the identity and password values.

  6. 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.

    For example:

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

  7. When prompted for a user name and password, enter the values for identity and password of the UAA Admin User Credentials that you retrieved in step 5. For example:

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

  8. 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
    
  9. 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

Perform the following 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 client secret you set in step 9 above.

    For example:

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

  3. Use the CredHub CLI to check whether a services CA certificate already is present.

    • Enter the following command:
      $ credhub get \
           --name="/services/tls_ca"
      
    • If you already have a certificate at the services/tls_ca path, skip to step 5.
  4. 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" \
          --no-overwrite \
          --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:
      $ credhub set \
          --name="/services/tls_ca" \
          --type="certificate" \
          --certificate=./root.pem \
          --private=ERKSOSMFF...
      
  5. Use the BOSH CLI v2 to extract the certificate portion from the CA certificate and print it. Enter the following command:

    $ bosh2 interpolate <(credhub get --name=/services/tls_ca) \
    --path /value/certificate
    

  6. Record the output of the bosh2 interpolate command from step 5.

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

  8. Paste the contents of the CA certificate into Trusted Certificates. Append to existing Trusted Certificates, if there are already certificates listed. Click Save.

  9. The CA certificate must also be added for the Gorouter. Navigate to the PAS Settings tab. Click on Networking. Add the CA certificate to the box labeled Certificate Authorities Trusted by Router and HAProxy and click Save.

  10. Click Review Pending Changes (see Reviewing Pending Product Changes).

  11. Click Apply Changes.