Adding a Custom Certificate Authority

This topic describes how to add a custom certificate authority (CA) to issue digital certificates in a Pivotal Cloud Foundry (PCF) deployment.

Custom CA Overview

To secure traffic in your PCF deployment, you must provide a CA to issue digital certificates. When you add and activate a new CA, a digital certificate is issued to BOSH Director. BOSH Director then passes the certificate to other components in your PCF deployment.

Pivotal recommends you supply a CA from a trusted provider when using a production environment. While you can create your own custom CAs if necessary, a trusted CA is more secure because it has been authenticated by the trusted entities permitted to issue them.

Note: You can also use the Pivotal Application Service (PAS) interface to issue wildcard certificates signed by the Ops Manager CA. Wildcard certificates include both the root domain and sub-domains in a single certificate. However, you should only use this Pivotal-generated CA in testing and development environments. For more information on creating a Pivotal-generated CA, see Creating a Wildcard Certificate for PCF Deployments.

Use the below procedures to add and activate a new CA.

Step 1: Add a Custom CA

When adding a custom CA, you must have access to your User Account and Authentication (UAA) access token. Perform the steps in User Account and Authentication (UAA) Server to target and authenticate with the Ops Manager UAA server. Record your access token.

Note: When you record your access token, remove any new line characters such as /n. Otherwise the API call in the following step will not succeed.

You can add a new CA by using the following API calls and the curl command:

  1. Use curl to make the following API call:

    $ curl "https://OPS-MAN-FQDN/api/v0/certificate_authorities" \
        -X POST \
        -H "Authorization: Bearer YOUR-UAA-ACCESS-TOKEN" \
        -H "Content-Type: application/json" \
        -d '{"cert_pem": "-----BEGIN CERTIFICATE-----\EXAMPLE-CERTIFICATE", "private_key_pem": "-----BEGIN RSA PRIVATE KEY-----\EXAMPLE-KEY"}'
    
    Replace EXAMPLE-CERTIFICATE with your certificate and EXAMPLE-KEY with your RSA key. The APl call returns a response that includes the new CA:
    HTTP/1.1 200 OK
    {
      "certificate_authorities": [
        {
          "guid": "f7bc18f34f2a7a9403c3",
          "issuer": "YOUR-CA",
          "created_on": "2017-01-09",
          "expires_on": "2021-01-09",
          "active": true,
          "cert_pem": "-----BEGIN CERTIFICATE-----\nMIIC+zCCAeOgAwIBAgI....etc"
        }
      ]
    }
    

  2. Confirm that you have added your new CA by listing all of the root CAs for Ops Manager:

    $ curl "https://OPS-MAN-FQDN/api/v0/certificate_authorities" \
        -X GET \
        -H "Authorization: Bearer YOUR-UAA-ACCESS-TOKEN"
    
    The API call returns a response listing all of the root CAs:
    HTTP/1.1 200 OK
    {
      "certificate_authorities": [
        {
          "guid": "f7bc18f34f2a7a9403c3",
          "issuer": "YOUR-CA",
          "created_on": "2017-01-09",
          "expires_on": "2021-01-09",
          "active": false,
          "cert_pem": "-----BEGIN CERTIFICATE-----\nMIIC+zCCAeOgAwIBAgI....etc"
        }
      ]
    }
    
    Confirm that your new CA has active set to false.

  3. Record the new CA’s GUID.

  4. Navigate to https://OPS-MAN-FQDN in a browser and log in to Ops Manager.

  5. Click Review Pending Changes, then Apply Changes. When the deploy finishes, continue to the next section.

Step 2: Activate the New CA

After adding your CA you must activate it. Once the CA is activated, the CA issues digital certificates to BOSH Director.

  1. Use curl to make an API call to activate the new CA. Replace CERT-GUID with the GUID of your CA that you recorded in the previous section:

    $ curl "https://OPS-MAN-FQDN/api/v0/certificate_authorities/CERT-GUID/activate" \
      -X POST \
      -H "Authorization: Bearer YOUR-UAA-ACCESS-TOKEN" \
      -H "Content-Type: application/json" \
      -d '{}'
    
    If the API call succeeds, it returns a successful response:
    HTTP/1.1 200 OK

  2. List your root CAs to confirm that the new CA is active:

    $ curl "https://OPS-MAN-FQDN/api/v0/certificate_authorities" \
        -X GET \
        -H "Authorization: Bearer YOUR-UAA-ACCESS-TOKEN"
    
    Confirm that your new CA has active set to true.

  3. Navigate to Ops Manager, click Review Pending Changes, and click Apply Changes.

After following this procedure, your custom CA can issue digital certificates for your PCF deployment.

Create a pull request or raise an issue on the source for this page in GitHub