Managing TLS Certificates

This topic describes how to manage Certificate Authority (CA) certificates in your deployment, including how to determine when your CA certificates expire, how to set a custom CA certificate, and how to regenerate and rotate both configurable and non-configurable CA certificates.

For information about rotating IPsec certificates, see Rotating IPsec Certificates.

Planning for Certificate Expiration

CA certificates expire 2 years after creation, and root certificates expire after 4 years. Because CA certificates do not last as long as root certificates, you can rotate CA certificates without creating and applying a new root certificate.

Depending on which certificates are due to expire, use one of the following approach to certificate rotation:

Rotating Configurable Certificates

Configurable certificates are certificates you generate yourself, as opposed to certificates that are given to you by the company whose product you are using. There are several types of configurable certificates. One such example is SAML service provider credentials.

Pivotal Application Service (PAS) UAA service holds a CA certificate which signs outbound communication to an external SAML identity provider. This CA certificate also has a 2-year expiration period and requires regeneration after this time.

SAML service provider credentials are only required for your PAS deployment’s UAA service if all of these conditions are met:

  • You are using SSO in production for apps.
  • You are using SAML identity providers for SSO service plans.
  • You had Ops Manager generate a certificate for you by clicking the Generate RSA Certificate button.
  • You are validating the signature of SAML authentication request with your identity provider.

Checking Certificate Expiration Dates

To retrieve information about the expiration dates for CA certificates in your deployment, do the following:

  1. Navigate to UAA > SAML Service Provider Credentials in your PAS tile.

  2. Copy the contents of the SAML Service Provider Credentials field into a temporary file such as test.pem.

  3. Run the command to validate the expiration time on the certificate. For example:

    $ openssl x509 -enddate -noout -in test.pem

    notAfter=Dec  7 21:01:04 2017 GMT

Once you have completed the above procedure, find the certificate with the uaa.service_provider_key_credentials property and validate its expiration. For example: "field "property_reference":".uaa.service_provider_key_credentials"..."valid_until":"2019-06-14T11:37:11Z"

If the certificate is nearing expiration, you must regenerate and rotate it.

Regenerating and Rotating SAML Service Provider Certificates

If PAS is configured to use SSO/SAML and your identity provider is validating the requests, you must import a new certificate to avoid disrupting PAS when you rotate the certificate.

To regenerate and rotate SAML service provider certificates, do the following:

  1. Disable certificate validation in your identity provider.

  2. Navigate to UAA > SAML Service Provider Credentials in your PAS tile.

  3. Click Generate RSA Certificate.

  4. Following the procedure in the Configure SAML as an Identity Provider for PCF section of the Configuring Authentication and Enterprise SSO for PAS topic to import the new certificate to your identity provider. These steps will vary depending on which SAML provider you are using.

  5. Re-enable certificate validation in your identity provider.

Rotating Non-Configurable Certificates

Non-configurable certificates are certificates that are given to you by the company whose product you are using, as opposed to certificates you generate yourself.

If you need to rotate non-configurable certificates, follow the procedure below. If you need to rotate all your certificates, including creating and applying a new root certificate, follow the procedure in Regenerate and Rotate CA Certificates.

Checking Certificate Expiration Dates

The non-configurable certificates in your deployment expire every two years. To retrieve information about the expiration dates for RSA and CA certificates in your deployment, do the following:

  1. Perform the steps in the Using Ops Manager API topic to target and authenticate with the Ops Manager User Account and Authentication (UAA) server. Record your Ops Manager access token, and use it for YOUR-UAA-ACCESS-TOKEN.

  2. To check the system for certificates that expire within a given time interval, use curl to make an API call.

    Use the https://OPS-MAN-FQDN/api/v0/deployed/certificates?expires_within=TIME endpoint, replacing TIME with an integer and a letter code. Valid letter codes are d for days, w for weeks, m for months, and y for years.

    For example, run the following command to search for certificates expiring within six months:

    $ curl "https://OPS-MAN-FQDN/api/v0/deployed/certificates?expires_within=6m" \
          -H "Authorization: Bearer YOUR-UAA-ACCESS-TOKEN"
    
    Replace YOUR-UAA-ACCESS-TOKEN with the access_token value you recorded in the previous step.

Regenerating and Rotating CA Certificates

Warning: You must complete the procedures in this topic in the exact order specified below. Otherwise, you risk doing damage to your deployment.

Depending on the requirements of your deployment, you may need to rotate your CA certificates. CA certificates can expire or fall out of currency, or your organization’s security compliance policies may require you to rotate CA certificates periodically.

You can rotate the CA certificates in your Pivotal Cloud Foundry (PCF) deployment using curl. PCF provides different API calls with which you can manage certificates and CAs. New CA certificates generated through this process use SHA-256 encryption.

These API calls allow you to create new CAs, apply them, and delete old CAs. The process of activating a new CA and rotating it in gives new certificates to the BOSH Director. The BOSH Director then passes the certificates to other components in your PCF deployment.

Note: These procedures require you to return to Ops Manager and click Apply Changes periodically. Clicking Apply Changes redeploys the BOSH Director and its tiles. If you apply your changes during each procedure, a successful redeploy verifies that the certificate rotation process is proceeding correctly.

Step 1: Add a New CA

Use the following procedure to add a new CA. You can use a Pivotal-generated CA or provide your own CA using the API calls in this section.

  1. Perform the steps in the Using Ops Manager API topic to target and authenticate with the Ops Manager User Account and Authentication (UAA) server. Record your Ops Manager access token, and use it for YOUR-UAA-ACCESS-TOKEN in the following procedures.

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

  2. To use a Pivotal-generated CA, use curl to make the following API call:

    $ curl "https://OPS-MAN-FQDN/api/v0/certificate_authorities/generate" \
      -X POST \ 
      -H "Authorization: Bearer YOUR-UAA-ACCESS-TOKEN" \
      -H "Content-Type: application/json" \
      -d '{}'
    

    If the command succeeds, the API returns a response that includes the new CA certificate.
      HTTP/1.1 200 OK
    {
      "guid": "f7bc18f34f2a7a9403c3",
      "issuer": "Pivotal",
      "created_on": "2017-01-19",
      "expires_on": "2021-01-19",
      "active": false,
      "cert_pem": "-----BEGIN EXAMPLE CERTIFICATE-----
      MIIC+zCCAeOgAwIBAgIBADANBgkqhkiG9w0BAQsFADAfMQswCQYDVQQGEwJVUzEQ
      EXAMPLEoCgwHUGl2b3RhbDAeFw0xNDarthgyMTQyMjVaFw0yMTAxMTkyMTQyMjVa
      EXAMPLEoBgNVBAYTAlVTMRAwDgYDVVaderdQaXZvdGFsMIIBIjANBgkqhkiG9w0B
      EXAMPLEoAQ8AMIIBCgKCAQEAyV4OhPIIZTEym9OcdcNVip9Ev0ijPPLo9WPLUMzT
      EXAMPLEo/TgD+DP09mwVXfqwBlJmoj9DqRED1x/6bc0Ki/BAFo/P4MmOKm3QnDCt
      EXAMPLEooqgA++2HYrNTKWJ5fsXmERs8lK9AXXT7RKXhktyWWU3oNGf7zo0e3YKp
      EXAMPLEoh1NwIbNcGT1AurIDsxyOZy1HVzBLTisMyDogJmSCLsOw3qUDQjatjXKw
      EXAMPLEojG3nv2hvD4/aTOiHuKM3+AGbnaS2MdIOvFOh/7Y79tUp89csK0gs6uOd
      EXAMPLEohe4DcKw5CzUTfHKNXgHyeoVOBPcVQTp4lJp1iQIDAQABo0IwQDAdBgNV
      EXAMPLEoyH4y7VEuImLStXM0CKR8uVqxX/gwDwYDVR0TAQH/BAUwAwEB/zAOBgNV
      EXAMPLEoBAMCAQYwDQYJKoZIhvcNAQELBQADggEBALmHOPxdyBGnuR0HgR9V4TwJ
      EXAMPLEoGLKVT7am5z6G2Oq5cwACFHWAFfrPG4W9Jm577QtewiY/Rad/PbkY0YSY
      EXAMPLEokrfNjxjxI0H2sr7qLBFjJ0wBZHhVmDsO6A9PkfAPu4eJvqRMuL/xGmSQ
      EXAMPLEoCynMNz7FgHyFbd9D9X5YW8fWGSeVBPPikcONdRvjw9aEeAtbGEh8eZCP
      EXAMPLEob33RuR+CTNqThXY9k8d7/7ba4KVdd4gP8ynFgwvnDQOjcJZ6Go5QY5HA
      EXAMPLEoPFW8pAYcvWrXKR0rE8fL5o9qgTyjmO+5yyyvWIYrKPqqIUIvMCdNr84=
      -----END EXAMPLE CERTIFICATE-----
      "
    

    To provide your own CA, 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 EXAMPLE RSA PRIVATE KEY-----\EXAMPLE-KEY"}'
    
    Replace EXAMPLE-CERTIFICATE with your custom CA certificate and EXAMPLE-KEY with your custom RSA key.

  3. Confirm that your new CA has been added 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 the following:
    HTTP/1.1 200 OK
    {
      "certificate_authorities": [
        {
          "guid": "f7bc18f34f2a7a9403c3",
          "issuer": "Pivotal",
          "created_on": "2017-01-09",
          "expires_on": "2021-01-09",
          "active": true,
          "cert_pem": "-----BEGIN CERTIFICATE-----\nMIIC+zCCAeOgAwIBAgI....etc"
        }
        {
          "guid": "a8ee01e33e3e3e3303e3",
          "issuer": "Pivotal",
          "created_on": "2017-04-09",
          "expires_on": "2021-04-09",
          "active": false,
          "cert_pem": "-----BEGIN CERTIFICATE-----\zBBBC+eAAAe1gAwAAAeZ....etc"
        }
      ]
    }
    
    Identify your newly added CA, which has active set to false. Record its GUID.

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

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

Step 2: Activate the New CA

  1. Use curl to make an API call to activate the new CA, replacing CERT-GUID with the GUID of your CA that you retrieved 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 '{}' 
    
    The API 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"
    
    Examine the response to ensure that your new CA has active set to true.

Step 3: Regenerate Non-Configurable Certificates to Apply the New CA

  1. Use curl to make an API call to regenerate all non-configurable certificates and apply the new CA to your existing BOSH Director:

    $ curl "https://OPS-MAN-FQDN/api/v0/certificate_authorities/active/regenerate" \
        -X POST \
        -H "Authorization: Bearer YOUR-UAA-ACCESS-TOKEN" \
        -H "Content-Type: application/json" \
        -d '{}'
    
    The API returns a successful response:
    HTTP/1.1 200 OK

  2. Navigate to Ops Manager and click Apply Changes. When the deploy finishes, continue to the next section.

Step 4: Delete the Old CA

  1. List your root CAs to retrieve the GUID of your old, inactive CA:

    $ curl "https://OPS-MAN-FQDN/api/v0/certificate_authorities" \
        -X GET \
        -H "Authorization: Bearer YOUR-UAA-ACCESS-TOKEN"
    

  2. Use curl to make an API call to delete your old CA, replacing OLD-CERT-GUID with the GUID of your old, inactive CA:

    $ curl "https://OPS-MAN-FQDN/api/v0/certificate_authorities/:OLD-CERT-GUID" \
        -X DELETE \
        -H "Authorization: Bearer YOUR-UAA-ACCESS-TOKEN"
    
    The API returns a successful response.
    HTTP/1.1 200 OK

  3. Navigate to Ops Manager and click Apply Changes.

Generating and Retrieving Certificates

To manage and retrieve information about certificates in your deployment, use the API calls in this section.

Perform the steps in the Using Ops Manager API topic to target and authenticate with the Ops Manager User Account and Authentication (UAA) server. Record your Ops Manager access token, and use it for YOUR-UAA-ACCESS-TOKEN.

Rotating Root Certificates

Retrieving the Root Certificate

To return the Ops Manager root certificate as a file, use curl to make the following API call:

$ curl "https://OPS-MAN-FQDN/download_root_ca_cert \
      -X GET \
      -H "Authorization: Bearer YOUR-UAA-ACCESS-TOKEN"

To return the Ops Manager root certificate as JSON, use curl to make the following API call:

$ curl "https://OPS-MAN-FQDN/api/v0/security/root_ca_certificate \
      -X GET \
      -H "Authorization: Bearer YOUR-UAA-ACCESS-TOKEN"

Retrieving and Generating RSA Certificates

To generate and return a new RSA certificate signed by the root CA, use curl to make the following API call:

$ curl "https://OPS-MAN-FQDN/api/v0/certificates/generate \
      -X POST \
      -H "Authorization: Bearer YOUR-UAA-ACCESS-TOKEN"

To return metadata from all deployed RSA certificates signed by the root CA, use curl to make the following API call:

$ curl "https://OPS-MAN-FQDN/api/v0/deployed/certificates \
      -X GET \
      -H "Authorization: Bearer YOUR-UAA-ACCESS-TOKEN"

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