ssi-creds-tiledev.html.md.erb

---
title: Securing your service credentials with Runtime CredHub
owner: Services
---

You can develop your <%= vars.platform_name %> service tile to support secure service instance (SSI)
credentials using Runtime CredHub.

For more information about Runtime CredHub, see [Runtime CredHub](https://docs.cloudfoundry.org/credhub/).

## <a id="background"></a> Background required for securing your service credentials

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

In <%= vars.app_runtime_full %>, 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 support the following:

* 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.
* You can select the SSI credentials option in the tile UI.

### <a id="ssi-vs-internal"></a> Difference between SSI and internal service credentials

You can use SSI credentials to grant apps access services through service instances,
which are distinct from the credentials that service tiles store in [BOSH CredHub](./credhub.html) for their own internal use.

When a service uses SSI credentials, the service broker stores the binding credentials in runtime CredHub.
When <%= vars.app_runtime_abbr %> 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. <%= vars.app_runtime_abbr %> 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 documentation](https://docs.cloudfoundry.org/credhub/index.html).

See the following example implementation of how to add SSI credentials capability to a service tile:

## <a id="step1"></a> 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 <%= vars.app_runtime_abbr %> tile, through a BOSH link.

<p class="note">
<span class="note__title">Note</span>
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.
</p>

### <a id="spec"></a> Update specification file and templates

The location of Runtime CredHub is stored in the `credhub.internal_url` and `credhub.port` properties of
the <%= vars.app_runtime_abbr %> tile. To activate your service tile to retrieve these CredHub-provided
properties, add a `consumes:` section with the BOSH link from the <%= vars.app_runtime_abbr %>  tile to the
spec file of the BOSH job that uses them and edit the job's templates to access the values in the link:

```
    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](https://docs.vmware.com/en/Tile-Developer-Guide/3.0/tile-dev-guide/ssi-creds-tiledev.html) and
[Links in Templates](https://bosh.io/docs/job-templates/).

### <a id="errand"></a> Save the Runtime CredHub location

To use the Runtime CredHub location retrieved from the <%= vars.app_runtime_abbr %> tile, you must
write a `post_deploy` [tile errand](tile-structure.html#errands) that saves the value out 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 <%= vars.app_runtime_abbr %>, the errand can write
the CredHub location out to a templated configuration file that the service broker reads.

### <a id="manifest"></a> Update deployment manifest

In the BOSH release for your tile, edit the deployment manifest `.yml` 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](https://tiewei.github.io/posts/bosh-terms-and-working-steps)

## <a id="step2"></a> 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.

See the following 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  <%= vars.app_runtime_abbr %> BOSH DNS server to do lookup.

## <a id="step3"></a> Step 3: Provide operators with the choice to use CredHub

To provide operators with the choice to select the SSI credentials option, edit your product template. See
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 installing with
    Ops Manager and this feature is activated in the <%= vars.app_runtime_abbr %> 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
```

## <a id="step4"></a> 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.

1. 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. For more information about
CredHub authentication, see the [Authentication](https://docs.cloudfoundry.org/api/credhub/version/2.9/#_authentication) section of the CredHub API documentation.

<p class="note">
<span class="note__title">Note</span>
Each credential type supports distinct parameters for customizing how credentials are generated.
These include minimum password lengths, required characters, and certificate fields.
Credentials have a maximum size of 64 KB.
</p>


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

  For further reference, see the [Set Credentials](https://docs.vmware.com/en/VMware-Tanzu-Application-Service/4.0/tas-for-vms/secure-si-creds.html) section of the CredHub API documentation.

1. 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 Cloud Foundry application being used

2. 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"
      }
    }
    ```

<p class="note">
<span class="note__title">Note</span>
If you are using the Java Virtual Machine (JVM), apps can
use <a href="https://projects.spring.io/spring-credhub">Spring CredHub</a> to access the CredHub API.
</p>