Securing Services Instance Credentials with Runtime CredHub

Page last updated:

Warning: Pivotal Cloud Foundry (PCF) v2.4 is no longer supported because it has reached the End of General Support (EOGS) phase as defined by the Support Lifecycle Policy. To stay up to date with the latest software and security updates, upgrade to a supported version.

This topic describes how Pivotal Cloud Foundry (PCF) operators can ensure service instance credentials are securely stored in CredHub.

  • What is runtime CredHub?
    • 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.
  • What is runtime CredHub used for?
    • Runtime CredHub exists to securely store service instance credentials. Previously, PCF could only use the Cloud Controller database for storing these credentials.
  • What are service instance credentials?
    • When developers want their app to use a service, such as those provided by the Spring Cloud Services tile for PCF, 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.
  • How can I ensure that service instance credentials are stored in runtime CredHub?
    • You must configure PAS to enable this functionality by following the procedure below. Not all services support the use of runtime CredHub.
  • Can I use runtime CredHub to store service instance credentials if some of my services do not 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.
  • Can I rotate service instance credentials in runtime CredHub?

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

Service Versions with Secure Binding Credentials Pivotal Network Listing
CredHub Service Broker for PCF All CredHub Service Broker for PCF
MySQL for PCF v2 v2.3 and later (available to user groups only) MySQL for PCF v2
Spring Cloud Services for PCF v1.5 and later Spring Cloud Services for PCF
RabbitMQ for PCF v1.12 and later RabbitMQ for PCF
Redis for PCF v1.13 and later Redis for PCF


Breaking Change: If you opt out of the BOSH DNS feature, your PCF deployment cannot support Secure Service Instance Credentials.

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 need to:

  • 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, follow the instructions in the PAS installation topic for your IaaS:

Step 2: Create Application Security Groups

Application Security Groups (ASGs) are network policy rules specifying protocols, ports, and IP ranges that apply to outbound network connections initiated from apps. You must follow the steps below to ensure the ASGs for your deployment allow apps to communicate with the runtime CredHub API.

Note: The default ASGs in PCF 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 that PAS runs on, as documented in Restricting App Access to Internal PCF Components.

  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, within 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. Run the following command to create an ASG that allows apps to access the CredHub API:

    $ 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 Bind ASGs. 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.

  1. Unbind the service instance from the app:

    $ cf unbind-service YOUR-APP YOUR-SERVICE-INSTANCE
  2. Rebind the service instance to the app:

    $ cf bind-service YOUR-APP YOUR-SERVICE-INSTANCE
  3. Review the VCAP_SERVICES environment variable to verify that the new service instance binding includes CredHub pointers:

    $ cf env YOUR-APP

    See the VCAP_SERVICES section of Cloud Foundry Environment Variables for help parsing the output of the cf-env command.

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

    $ cf restart YOUR-APP

    If you run cf-env again, you can see the VCAP-SERVICES environment variable now contains the credentials for the service instance binding.