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:

$ curl https://[SERVER_URL]/secrets/[APP]/[PROFILE]/[LABEL]/[NAME] \
-H "Authorization: $(cf oauth-token)" -X PUT --data '{"key": "value"}' \
-H "Content-Type: application/json"

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"

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.

$ curl -k https://[SERVER_URL]/secrets/[APP]/[PROFILE]/[LABEL]/[NAME] \
-H "Authorization: $(cf oauth-token)" -X DELETE

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