Managing Secrets with CredHub
Page last updated:
Overview
The Spring Cloud Services Config Server uses the runtime CredHub within Pivotal Cloud Foundry (PCF) for secure storage of secrets. The Spring Cloud Services plugin for the Cloud Foundry Command Line Interface (cf CLI) adds commands which can store or delete a secret within the runtime CredHub, and the Config Server also provides a /secrets endpoint that can be used to store and remove secrets.
Secrets stored by one Config Server service instance are accessible only to that service instance, and a given Config Server service instance can add, serve, or delete only its own secrets in the runtime CredHub. Each secret stored by the Config Server is associated with an app name, a profile name (the default profile name is default), and a label (the default label is master).
See below for information about using a Config Server service instance to add or delete secrets within the runtime CredHub.
Adding and Removing Secrets Using the cf CLI Plugin
See below for information about adding and removing secrets in CredHub using the Spring Cloud Services cf CLI plugin.
Adding a Secret
You can add a secret to CredHub using the cf config-server-add-credhub-secret command added by the Spring Cloud Services cf CLI plugin. The command accepts three arguments:
- the name of the Config Server service instance
- the CredHub path with which to store the secret, formatted as
[APP_NAME]/[PROFILE_NAME]/[LABEL_NAME]/[SECRET_NAME] - the value of the secret (as JSON)
The following example command adds a secret {"key": "value"} at the path cook/encrypt/master/mysecret using the my-config-server Config Server service instance:
$ cf config-server-add-credhub-secret my-config-server \
cook/encrypt/master/mysecret '{"key": "value"}'
Removing a Secret
You can remove a secret from CredHub using the cf config-server-remove-credhub-secret command added by the Spring Cloud Services cf CLI plugin. The command accepts two arguments:
- the name of the Config Server service instance
- the CredHub path with which to store the secret, formatted as
[APP_NAME]/[PROFILE_NAME]/[LABEL_NAME]/[SECRET_NAME]
The following example command removes a secret at the path cook/encrypt/master/mysecret using the my-config-server Config Server service instance:
$ cf config-server-remove-credhub-secret my-config-server \ cook/encrypt/master/mysecret
Adding and Removing Secrets Using the /secrets Endpoint
See below for information about adding and removing secrets in CredHub using the /secrets endpoint of the Config Server.
Locating the Service Instance URL
In order to use the /secrets endpoint to add or remove secrets in CredHub, you must obtain the URL of the service instance’s backing app.
To obtain the URL, run the cf service command, giving the name of the service instance:
$ cf service my-config-server Showing info of service my-config-server in org myorg / space dev as user... name: my-config-server service: p.config-server tags: plan: standard description: Config Server documentation: dashboard: https://config-server-3007518e-302e-4e28-be3a-f516e7b2a4fe.apps.example.com/dashboard
Copy the URL given for dashboard, removing the /dashboard path. This is the URL of the service instance’s backing app. In the example above, this would be:
https://config-server-3007518e-302e-4e28-be3a-f516e7b2a4fe.apps.example.com
Adding a Secret
You can add a secret to CredHub by making an HTTP PUT request to the Config Server’s /secrets endpoint. The secret itself is given as JSON. You must provide an OAuth 2.0 bearer token, which can be supplied by the cf CLI through the cf oauth-token command.
You must also provide:
- the relevant app name
- the relevant profile name
- the relevant label
- the name of the secret (unique for this Config Server service instance)
- the value of the secret (as JSON)
The following example command uses cURL to make the request, including the -i flag so that cURL returns the HTTP response code:
$ curl [SERVER_URL]/secrets/[APP]/[PROFILE]/[LABEL]/[NAME] \
-H "Authorization: $(cf oauth-token)" -X PUT --data '{"key": "value"}' \
-H "Content-Type: application/json" -i
HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Content-Length: 0
Date: Wed, 06 Nov 2019 23:43:23 GMT
Expires: 0
...
In this example, replace the following placeholders with these values:
[SERVER_URL]with the Config Server service instance backing app’s URL[APP]with the relevant app name[PROFILE]with the relevant profile name[LABEL]with the relevant label[NAME]with the name of the secret
With the placeholders replaced, the example might be similar to the following:
$ curl https://config-server-a5782192-8036-4f57-8312-4756a2604240.apps.example.com/secrets/cook/production/mylabel/secretmenu \
-H "Authorization: $(cf oauth-token)" -X PUT --data '{"secretMenu": "tacos"}' \
-H "Content-Type: application/json" -i
HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Content-Length: 0
Date: Wed, 06 Nov 2019 23:43:23 GMT
Expires: 0
...
Removing a Secret
You can remove a secret from CredHub by making an HTTP DELETE request to the Config Server’s /secrets endpoint. You must provide an OAuth 2.0 bearer token, which can be supplied by the cf CLI through the cf oauth-token command.
You must also provide:
- the relevant app name
- the relevant profile name
- the relevant label
- the name of the secret
The following example command uses cURL to make the request, including the -i flag so that cURL returns the HTTP response code:
$ curl [SERVER_URL]/secrets/[APP]/[PROFILE]/[LABEL]/[NAME] \ -H "Authorization: $(cf oauth-token)" -X DELETE -i HTTP/1.1 200 OK Cache-Control: no-cache, no-store, max-age=0, must-revalidate Content-Length: 0 Date: Wed, 06 Nov 2019 23:48:21 GMT Expires: 0 ...
In this example, replace the following placeholders with these values:
[SERVER_URL]with the Config Server service instance backing app’s URL[APP]with the relevant app name[PROFILE]with the relevant profile name[LABEL]with the relevant label[NAME]with the name of the secret
With the placeholders replaced, the example might be similar to the following:
$ curl https://config-server-a5782192-8036-4f57-8312-4756a2604240.apps.example.com/secrets/cook/production/mylabel/secretmenu \ -H "Authorization: $(cf oauth-token)" -X DELETE -i HTTP/1.1 200 OK Cache-Control: no-cache, no-store, max-age=0, must-revalidate Content-Length: 0 Date: Wed, 06 Nov 2019 23:48:21 GMT Expires: 0 ...