You can develop your Tanzu Operations Manager service tile to support secure service instance (SSI) credentials using Runtime CredHub.

For more information about Runtime CredHub, see Runtime CredHub in the TAS for VMs documentation.

Background required for securing your service credentials

When developers bind an app to a service instance, the binding typically includes the binding credentials required to access the service.

In VMware Tanzu Application Service for VMs, service brokers can store binding credentials as SSI credentials in Runtime CredHub and apps can retrieve these credentials from CredHub.

This secures service instance credential management by avoiding the following:

  • Leaking environment variables to logs, which increases risk of disclosure
  • Sending credentials between components, which increases risk of disclosure
  • Requiring users to rotate credentials through the environment, which requires container recreation

To store binding credentials in Runtime CredHub, your service tile should be able to:

  • Discover the location of Runtime CredHub.
  • Provide this CredHub location to the broker app. The service broker uses the provided location to store binding credentials in CredHub.
  • Select the SSI credentials option in the tile UI.

Difference between SSI and internal service credentials

You can use SSI credentials to grant apps access to services through service instances, which are distinct from the credentials that service tiles store in BOSH CredHub for internal use.

When a service uses SSI credentials, the service broker stores the binding credentials in Runtime CredHub. When TAS for VMs binds an app to an instance of the service, the broker retrieves the credentials from Runtime CredHub and delivers them to the Cloud Controller (CC) to activate the app to access the service.

These SSI credentials are different from credentials that the tile uses internally; for example, to give the service broker access to an internal database. TAS for VMs generates the internal tile credentials for a service when the service is first installed and stores them in BOSH CredHub, not Runtime CredHub.

For more information about the CredHub credential management component, see the CredHub topics in the TAS for VMs documentation.

See the following example implementation for adding SSI credentials capability to a service tile:

Step 1: Edit your BOSH release

To use Runtime CredHub, your service tile must retrieve the location of the CredHub server, which is published in the TAS for VMs tile, through a BOSH link.

If you are using the BOSH Links, you can have multiple jobs share deployment-time configuration properties. This helps to avoid redundant configurations in BOSH releases and deployment manifests.

Update spec file and templates

The location of Runtime CredHub is stored in the credhub.internal_url and credhub.port properties of the TAS for VMs tile. To activate your service tile to retrieve these CredHub-provided properties, add a consumes: section with the BOSH link from the TAS for VMs tile to the spec file of the BOSH job that uses them, and edit the job templates to access the values in the link:

For example:

    consumes:
    - {name: credhub, type: credhub}

For information about using BOSH links in the specifications file and templates of a job, and consuming shared properties provided by other jobs, see Links in spec files and Links in templates.

Save the Runtime CredHub location

To use the Runtime CredHub location retrieved from the TAS for VMs tile, you must write a post_deploy tile errand that saves the value and activates the service broker to access it.

Depending on how your tile deploys the service broker app, the service instance errand can save the CredHub location in different ways. If the tile pushes the broker as a Cloud Foundry app, the errand can store the location in an environment variable such as CREDHUB_URL for the service broker to call. If BOSH deploys the service broker outside of TAS for VMs, the errand can write the CredHub location to a templated configuration file that the service broker reads.

Update deployment manifest

In the BOSH release for your tile, edit the deployment manifest YAML file so that it contains the BOSH link to CredHub:

- name: broker
  release: my-broker-release
  consumes:
    credhub:
      from: credhub
      deployment: cf-XXXXXXXXX

For more information about using BOSH links in deployment manifests, see Links in deployments

Step 2: Activate your tile to find Runtime CredHub

To activate your service tile to discover Runtime CredHub, edit your product template so that it consumes the location of CredHub. See the following example:

job_types:
- name: JOB-NAME
  resource_label: LABEL-NAME
  templates:
  - name: TEMPLATE-NAME
    release: RELEASE-NAME
    consumes: |
      credhub: {from: credhub, deployment: "(( ..cf.deployment_name ))"}

You can also use the address from the BOSH link to verify that the CredHub server is available at that address during tile installation.

For example:

properties:
      aliases:
        (( dig credhub.service.cf.internal @169.254.0.2 )):
        - '*.credhub.(( ..cf.credhub.network )).(( ..cf.deployment_name )).bosh'

In the example, the Runtime CredHub instance is accessed at credhub.service.cf.internal. If your broker runs as an app, you can resolve this address with BOSH DNS. If your broker runs on a VM with a Consul agent, you can resolve the address with Consul. Alternatively, from a VM, you can resolve the address with dig credhub.service.cf.internal @169.254.0.2. This command uses the TAS for VMs BOSH DNS server to do the lookup.

Step 3: Provide operators with the choice to use CredHub

To provide the choice to select the SSI credentials option, edit your product template as shown in the following example:

form_types:
- name: FORM-NAME
  label: LABEL-NAME
  description: DESCRIPTION
  property_inputs:
  - reference: .JOB-NAME.secure_credentials
    label: Secure service instance credentials
    description: "When checked, service instance credentials are stored in CredHub. Activate only when you install with
    Tanzu Operations Manager and this feature is activated in the TAS for VMs tile."

property_blueprints:
  - name: hidden_credhub_selector
    type: selector
    configurable: false
    default: "default"
    option_templates:
      - name: default_option
        select_value: "default"
        named_manifests:
          - name: consumes_section_credhub_disabled
            manifest: |
              credhub: nil
          - name: consumes_section_credhub_enabled
            manifest: |
              credhub: {from: credhub, deployment: "(( ..cf.deployment_name ))"}

job_types:
- name: JOB-NAME
  resource_label: LABEL-NAME
  templates:
  - name: TEMPLATE-NAME
    release: RELEASE-NAME
    consumes: |
      "(( secure_credentials.value ? .properties.hidden_credhub_selector.selected_option.parsed_manifest(consumes_section_credhub_enabled) : .properties.hidden_credhub_selector.selected_option.parsed_manifest(consumes_section_credhub_disabled) ))"
  errand: true
  resource_definitions:
     ...
  property_blueprints:
  ...
  - name: secure_credentials
    type: boolean
    configurable: true
    default: false

Step 4: Store binding credentials in Runtime CredHub

When the Cloud Controller (CC) receives a request to bind a service instance to an app, it forwards the request to the service broker. The service broker returns the binding credentials that allow access to the service.

To activate your service broker to store binding credentials in Runtime CredHub and make them SSI credentials, do the following:

  1. In your service broker code, locate where your broker handles binding requests from the CC.

  2. Add code that authenticates your service broker to CredHub using OAuth2 tokens from UAA. Each call to the CredHub API must include an authorization header.

  3. Update your code to store your binding credentials in CredHub using the CredHub API endpoint for setting the json credential type with a user-provided value.

    See the following example for how to format your API call:

    curl "https://CREDHUB.INTERNAL_URL:CREDHUB.PORT/api/v1/data" \
-X PUT \
-d '{
    "name": "/c/CLIENT-IDENTIFIER/SERVICE-IDENTIFIER/BINDING-GUID/CREDENTIAL-NAME",
    "type": "json",
    "value": {
      "uri": "SERVICE-URL",
      "username": "USERNAME",
      "password": "PASSWORD"
    }
  }' \
-H 'Content-type: application/json'

    Where:

    • CREDHUB.INTERNAL_URL and CREDHUB.PORT are the address and port of CredHub.
    • CLIENT-IDENTIFIER is a value provided by the service broker to uniquely identify the broker.
    • SERVICE-IDENTIFIER is the name of the service offering as shown in the services catalog.
    • BINDING-GUID is the GUID created by the Cloud Controller and passed to the service broker in the service binding request.
    • CREDENTIAL-NAME is a value provided by the service broker to name the credential.
    • SERVICE-URL is the URL of your service.

    • USERNAME and PASSWORD are your binding credentials.

      See also Set CredHub Credentials in the TAS for VMs documentation.

  4. Grant your application permission to read the credential from CredHub:

    curl "https://CREDHUB.INTERNAL_URL:CREDHUB.PORT/api/v2/permissions" \
  -X POST \
  -d '
  {
    "path": "/c/CLIENT-IDENTIFIER/SERVICE-IDENTIFIER/BINDING-GUID/CREDENTIAL-NAME",
    "actor": "mtls-app:APP-GUID"
    "operations": ["read"]
  }' \
  -H "authorization: bearer [TOKEN]" \
  -H 'content-type: application/json'

    Where APP-GUID is the GUID of the CF application being used

  5. Edit your service broker so that it returns a reference to the stored credentials in response to the binding request from the CC. Return the credentials as a single key credhub-ref with thee value formatted as /c/CLIENT-IDENTIFIER/SERVICE-IDENTIFIER/BINDING-GUID/CREDENTIAL-NAME.

    For example, the binding response might look like the following:

    {
  "credentials": {
    "credhub-ref": "/c/example-service-broker/example-service/faa677f5-25cd-4f1e-8921-14a9d5ab48b8/credentials"
  }
}

Note If you are using the Java Virtual Machine (JVM), apps can use Spring CredHub to access the CredHub API.

check-circle-line exclamation-circle-line close-line
Scroll to top icon