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.
Service | Versions with Secure Binding Credentials | Pivotal Network Listing |
---|---|---|
Cloud Cache | v1.7 and later | Cloud Cache |
CredHub Service Broker for Pivotal Platform | All | CredHub Service Broker for Pivotal Platform |
MySQL for Pivotal Platform | v2.3 and later (available to user groups only) | MySQL for Pivotal Platform |
RabbitMQ for Pivotal Platform | v1.12 and later | RabbitMQ for Pivotal Platform |
Redis for Pivotal Platform | v1.13 and later | Redis for Pivotal Platform |
Spring Cloud Services for Pivotal Platform | v1.5 and later | Spring Cloud Services for Pivotal Platform |
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:
From the PAS tile, click Assign AZs and Networks and record the selected network where the tile is installed.
From the BOSH Director tile, in the Settings tab, click Create Networks.
In the Networks section, click the name of the PAS network to expand it.
Record the CIDR for the PAS network.
Create a file named
runtime-credhub.json
for specifying your ASG rules. Copy the content below into the file. ReplaceYOUR-PAS-CIDR
with the CIDR you recorded in the previous step.[ { "protocol": "tcp", "destination": "YOUR-PAS-CIDR", "ports": "8844" } ]
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
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 thep-spring-cloud-services
space of thesystem
org.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:
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.
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.
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 thecf-env
command, see the VCAP_SERVICES section of the PAS Environment Variables topic.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 runcf-env
again, you can see theVCAP-SERVICES
environment variable now contains the credentials for the service instance binding.