Securing Services Instance Credentials with Runtime CredHub

Page last updated:

This topic describes how Pivotal Platform operators can ensure service instance credentials are securely stored in CredHub.

Overview

The Pivotal Application Service (PAS) tile includes its own CredHub component, separate from the CredHub component included with the BOSH Director tile. For more information about this centralized credential management component, see the CredHub documentation.

Runtime CredHub exists to securely store service instance credentials. Previously, Pivotal Platform could only use the Cloud Controller database for storing these credentials.

When developers want their app to use a service, such as those provided by the Spring Cloud Services tile for Pivotal Platform, they must bind their app to an instance of that service. Service bindings include credentials that developers can use to access the service from their app. For more information, see Binding Credentials.

To ensure that service instance credentials are stored in runtime CredHub, you must configure PAS to enable this functionality. Not all services support the use of runtime CredHub.

PAS supports both services that do and do not use runtime CredHub. Services that do not use runtime CredHub continue to pass their credentials to the Cloud Controller database.

Runtime CredHub supports credential rotation. For more information, see Rotating Runtime CredHub Encryption Keys.

Pivotal Platform Services that Use Secure Binding Credentials

The procedures in this document are only effective for services that support storing their instance credentials in runtime CredHub. To learn whether a service supports this feature, see the table below or the documentation for that service.

Prerequisites

Breaking Change: If you opt out of the BOSH DNS feature, your Pivotal Platform deployment cannot support Secure Service Instance Credentials. For more information, see BOSH DNS Service Discovery for Application Containers (Beta) in the PAS v2.0 release notes.

Runtime CredHub allows you to use one or more Hardware Security Modules (HSMs) to store encryption keys. If you wish to use an HSM with CredHub, you must configure the HSM before completing the procedures below. For more information, see Preparing CredHub HSMs for Configuration.

Step 1: Configure the PAS Tile

To configure the PAS tile to support securing service instance credentials in CredHub, you must:

• In the CredHub pane, provide at least one encryption key. CredHub supports multiple encryption key providers.

• In the Resource Config pane, set the number of CredHub instances to at least one.

CredHub configuration options include:

• Internal or external databases

• Encryption keys stored internally, externally in a Hardware Security Module (HSM), or both

To configure the PAS tile, see Configuring PAS.

Step 2: Create App Security Groups

App Security Groups (ASGs) are network policy rules specifying protocols, ports, and IP ranges that apply to outbound network connections initiated from apps.

Note: The default ASGs in Pivotal Platform allow apps running on your deployment to send traffic to almost any IP address. This step is only required if your ASGs restrict network access from apps to the network on which PAS runs. For more information, see Restricting App Access to Internal Pivotal Platform Components.

To ensure the ASGs for your deployment allow apps to communicate with the runtime CredHub API:

1. From the PAS tile, click Assign AZs and Networks and record the selected network where the tile is installed.

2. From the BOSH Director tile, in the Settings tab, click Create Networks.

3. In the Networks section, click the name of the PAS network to expand it.

4. Record the CIDR for the PAS network.

5. Create a file named runtime-credhub.json for specifying your ASG rules. Copy the content below into the file. Replace YOUR-PAS-CIDR with the CIDR you recorded in the previous step.

   [
     {
     "protocol": "tcp",
     "destination": "YOUR-PAS-CIDR",
     "ports": "8844"
     }
   ]
   

6. Create an ASG that allows apps to access the CredHub API by running:

   cf create-security-group runtime-credhub ~/workspace/runtime-credhub runtime-credhub.json
   

7. Bind this ASG to your deployment or the specific space in which you want apps to access CredHub. For more information about binding ASGs, see the Bind ASGs section of the App Security Groups topic. Ensure that apps deployed as part of the service tile installation process have access to CredHub in addition to the apps pushed to the platform by developers. For example, the Spring Cloud Services tile deploys the spring-cloud-broker app to the p-spring-cloud-services space of the system org.

8. Restart apps for the ASGs to take effect. Optionally, you can use the app-restarter cf CLI plugin to restart all apps in a particular space, org, or deployment.

Step 3: Unbind and Rebind Service Instances

For any service instance bindings that existed before runtime CredHub was supported for that service, you must work with your developers to unbind and rebind the service instances to their apps. If you do not unbind and rebind the service, apps continue functioning as normal and fetching credentials from the Cloud Controller database.

Note: This step is not required for bindings created after you installed the new version of the service tile that supports CredHub and you completed the procedures in steps 1 and 2 of this topic.

To unbind and rebind your service instances to their apps:

1. Unbind the service instance from the app by running:

   cf unbind-service YOUR-APP YOUR-SERVICE-INSTANCE
   

   Where:

   • YOUR-APP is the app to which you bound the service instance.
   • YOUR-SERVICE-INSTANCE is the service instance you want to unbind from the app.

2. Rebind the service instance to the app by running:

   cf bind-service YOUR-APP YOUR-SERVICE-INSTANCE
   

   Where:

   • YOUR-APP is the app from which you unbound the service instance.
   • YOUR-SERVICE-INSTANCE is the service instance you want to rebind to the app.

3. Review the VCAP_SERVICES environment variable to verify that the new service instance binding includes CredHub pointers by running:

   cf env YOUR-APP
   

   Where YOUR-APP is the app to which you bound the service instance.
   
   For help parsing the output of the cf-env command, see the VCAP_SERVICES section of the PAS Environment Variables topic.

4. Restart the app to apply the service instance binding by running:

   cf restart YOUR-APP
   

   Where YOUR-APP is the app to which you bound the service instance.
   
   If you run cf-env again, you can see the VCAP-SERVICES environment variable now contains the credentials for the service instance binding.