Managing Secrets with CredHub

Overview
How Secrets are Distributed to Apps
Adding and Removing Secrets Using the cf CLI Plugin
- Adding a Secret
- Removing a Secret
Adding and Removing Secrets Using the /secrets Endpoint

Page last updated:

Overview

The Spring Cloud Services Config Server uses the runtime CredHub within VMware Tanzu Application Service for VMs (TAS) 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.

How Secrets are Distributed to Apps

A secret is stored in CredHub using a path including the name of the app that will use the secret, the profile to which the secret applies, the label, and the name of the secret:

[APP_NAME]/[PROFILE_NAME]/[LABEL_NAME]/[SECRET_NAME]

The default value for [APP_NAME] is application, and a secret stored using a path beginning with application/ will be made available to all apps that retrieve CredHub configuration from the Config Server instance. A secret stored using a path beginning with a specific app name (for example, a path beginning with myapp/) will only be made available to the app that uses that name (in this example, an app named myapp).

If you have two apps, myapp and cook, which both retrieve CredHub configuration using the same Config Server service instance, and you add:

A menu secret using the CredHub path application/cloud/master/menu, with a value of tacos
A menu secret using the CredHub path cook/cloud/master/menu, with a value of pizza

Then:

The myapp app will receive one Spring property source, for secrets under the path application/*, and its value for menu will be tacos.
The cook app will receive two Spring property sources, one for secrets under the path cook/* and one for secrets under the path application/*, and its value for menu will be pizza.

App-specific secrets take precedence over default secrets. If you store two secrets with the same name menu, one under a path beginning with application/ and one under a path beginning with a specific app name, the app with that specific name will use its app-specific menu secret and other apps will use the default menu secret.

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