Setting Up and Deploying CredHub with BOSH

This topic provides details about how to deploy a BOSH Director with CredHub so that you can use credential variables in your deployment manifests.

If you use bosh-deployment, include the file credhub.yml to enable CredHub on the BOSH Director VM.

How It Works

CredHub exists co-located on a virtual machine (VM) with the Director, UAA, and other high-level components. A deployment manifest configured with CredHub calls credential information from CredHub and passes it to the appropriate components.

Once configured, any variable in a BOSH deployment manifest with the syntax ((variable-name)) causes the Director to retrieve the variable value from CredHub at deploy time. You can tell your manifest already uses CredHub if fields with secure data have ((variables)) formatted with double parentheses.

Setup Before Deployment

  1. Set up BOSH Director.

    The following configuration steps assume that you have an existing BOSH Director. If you do not have a Director, read the initialization guide for more details.

  2. Configure UAA on your Director.

    CredHub uses UAA for user and client authentication. You need a UAA server configured on the Director to enable CredHub. For more information about provisioning UAA on the Director, read the BOSH documentation.

  3. (Optional) Configure an external database.

    To optimize fault tolerance, store CredHub data in an external database. To do so, you must create a database and user on your database server before deployment. You can use the internal Director database to store CredHub data, but take care to avoid data loss when you provision or update the Director VM.

  4. (Optional) Configure a Luna HSM.

    If you use an external Hardware Security Module (HSM) to perform cryptographic operations:

    • Configure the HSM to allow access from the deployed CredHub instance, and
    • Grant the operator all of the required permissions to use the HSM.

      For more information about the required HSM values and how to configure an HSM, read about configuring a Luna HSM.

Configuring the Director

  1. Update the deployment manifest to include the CredHub release. Download the latest CredHub release from bosh.io.
  2.     releases:
        - name: bosh
          url: https://bosh.io/d/github.com/cloudfoundry/bosh?v=261.2
          version: 261.2
          sha1: d4635b4b82b0dc5fd083b83eb7e7405832f6654b
        # ...
        - name: credhub # <---
          url: https://bosh.io/d/github.com/pivotal-cf/credhub-release?v=0.6.1
          version: 0.6.1
          sha1: 5ab4c4ef3d67f8ea07d78b1a87707e7520a97ab7
    
  3. Add the CredHub job to the Director instance.
  4.     instance_groups:
        - name: bosh
          instances: 1
          jobs:
          - {name: nats, release: bosh}
          - {name: redis, release: bosh}
          - {name: postgres, release: bosh}
          - {name: blobstore, release: bosh}
          - {name: director, release: bosh}
          - {name: health_monitor, release: bosh}
          - {name: uaa, release: uaa-release}
          - {name: credhub, release: credhub} # <---
          resource_pool: default
          # ...
    
  5. (Optional) Add variable generation specifications for CredHub properties.

    You can generate values that CredHub requires automatically with the BOSH v2 CLI. To enable generation, add the variable specifications to the manifest as shown below. You can adjust or remove these if you prefer to provide your own values.
  6.     variables: 
        - name: credhub-ca
          type: certificate
          options: 
            is_ca: true 
            common_name: 'CredHub CA'
        - name: credhub-tls
          type: certificate
          options: 
            ca: credhub-ca 
            common_name: credhub.example.com
            alternative_names: 
            - 10.0.0.10
            - 127.0.0.1
        - name: credhub-encryption-password
          type: password
    
  7. Add CredHub properties to the deployment manifest.
        properties:
          credhub:
            port: 8844
            log_level: info
            tls:
              certificate: ((credhub-tls.certificate))
              private_key: ((credhub-tls.private_key))
            data_storage:
              type: mysql
              host: mysql.EXAMPLE.com
              port: 3306
              database: credhub
              username: user
              password: EXAMPLE-PASSWORD
              require_tls: true
              tls_ca: |
                -----BEGIN CERTIFICATE-----
                ...
                -----END CERTIFICATE-----
            authentication:
              uaa:
                url: "https://uaa.example.com:8443"
                verification_key: |
                  -----BEGIN PUBLIC KEY-----
                  ...
                  -----END PUBLIC KEY-----
              mutual_tls: 
                trusted_cas: 
                - |
                  -----BEGIN CERTIFICATE-----
                  ...
                  -----END CERTIFICATE-----
            encryption: 
              keys: 
              - provider_name: corp-hsm
                encryption_key_name: KEY-NAME
                active: true
              providers:
              - name: corp-hsm
                type: hsm
                partition: PARTITION-NAME
                partition_password: PARTITION-PASSWORD
                client_certificate: |
                  -----BEGIN CERTIFICATE-----
                  ...
                  -----END CERTIFICATE-----
                client_key: |
                  -----BEGIN RSA PRIVATE KEY-----
                  ...
                  -----END RSA PRIVATE KEY-----
                servers: 
                - host: hsm.example.com
                  port: 1792
                  partition_serial_number: 123456
                  certificate: |
                    -----BEGIN CERTIFICATE-----
                    ...
                    -----END CERTIFICATE-----
    
    The example above includes a configuration to use a hardware security module (HSM) for encryption. Alternatively, you can use the internal software-based encryption provider with the configuration below.

    This method derives a 256-bit key from the provided encryption password and utilized AES256-GCM encryption.
        ...
          encryption:
            providers: 
            - name: main
              type: internal
            keys: 
            - provider_name: main
              encryption_password: ((credhub-encryption-password))
              active: true
        ...
    
    For the full list of CredHub properties and default values, read the job spec properties.
  8. Add CredHub CLI and Director/CredHub UAA clients.
  9.     properties:
          uaa:
            clients:
              credhub_cli:
                override: true
                authorized-grant-types: password,refresh_token
                scope: credhub.read,credhub.write 
                authorities: uaa.none
                access-token-validity: 120 
                refresh-token-validity: 1800
                secret: "" # <--- CLI expects this secret to be empty
              director_to_credhub:
                override: true
                authorized-grant-types: client_credentials
                scope: uaa.none
                authorities: credhub.read,credhub.write
                access-token-validity: 43200
                secret: EXAMPLE-SECRET # <--- Replace with custom client secret
    
  10. Enable the config server on the Director and configure it to utilize CredHub.
  11.     properties:
          director:
            address: bosh.EXAMPLE.com
            name: director-name
            config_server:
              enabled: true
              
              # URL must contain /api/ path with trailing slash
              url: "https://127.0.0.1:8844/api/"
              
              ca_cert: |
                -----BEGIN CERTIFICATE-----
                ...
                -----END CERTIFICATE-----
              uaa:
                url: "https://127.0.0.1:8443"
                client_id: director_to_credhub
                client_secret: EXAMPLE-SECRET
                ca_cert: |
                  -----BEGIN CERTIFICATE-----
                  ...
                  -----END CERTIFICATE-----
    
  12. (Optional) Configure the Director Postgres server with additional database named credhub. If you are using the internal Director database, you must provision an additional database for the CredHub data. If you use an external database, you must create the database on your database server before deploying.
  13.     properties:
          postgres: &db
            host: 127.0.0.1
            port: 5432
            user: postgres
            password: POSTGRES-PASSWORD
            database: bosh
            additional_databases: [credhub]
            adapter: postgres
    
  14. (Optional) Seed initial CredHub users to UAA.
  15.     properties:
          uaa:
            scim:
              users:
              - name: CREDHUB-USER
                password: USER-PASSWORD
                groups:
                # Users must have both credhub.read and credhub.write access
                - credhub.read             # <---
                - credhub.write            # <---
              - name: OTHER-CREDHUB-USER
                password: OTHER-USER-PASSWORD
                groups:
                - credhub.read
                - credhub.write
    
  16. Deploy.

Using CredHub

  1. Create CredHub users in UAA.

    To authenticate with CredHub to manage credentials, you must have a UAA user account with the scopes credhub.read and credhub.write. You can create users in UAA as described in the UAA documentation. Alternatively, you can configure UAA with an external LDAP provider.

    The example below shows how to create two users in UAA.
  2. $ uaac token client get admin -s example-password
      Successfully fetched token via client credentials grant.
      Target: https://uaa.EXAMPLE.com:8443
      Context: admin, from client admin
    $ uaac user add EXAMPLE-USER --emails email@example.com Password: ******** Verify password: ******** user account successfully added
    $ uaac user add OTHER-EXAMPLE-USER --emails email@example.com Password: ******** Verify password: ******** user account successfully added
    $ uaac member add credhub.read EXAMPLE-USER OTHER-EXAMPLE-USER success
    $ uaac member add credhub.write EXAMPLE-USER OTHER-EXAMPLE-USER success

  3. Install the CredHub CLI.


    The CredHub CLI offers a simple, scriptable interface to manage stored credentials. You can download the latest release from the GitHub repository.


  4. Place or generate credentials in CredHub using the CLI.
  5. $ credhub set --type ssh --name /static/ssh_key --public ~/ssh.pub --private ~/ssh.key
    $ credhub generate --type ssh --name /static/ssh_key
    

  6. Update BOSH deployment manifests.

    Once you have a Director that integrates with CredHub, you can update your deployment manifests to use it. The example below is of a deployment manifest using two credentials; one stored in Credhub, and one generated by CredHub.

    Define credentials that you want to be generated automatically in the variables section.

  7.  
        name: Sample-Manifest
    releases: - name: shell url: https://bosh.io/d/github.com/cloudfoundry-community/shell-boshrelease?v=3.2.0 sha1: 893b10af531a7519da99bb8656cc07b8277d1692
    #...
    variables: - name: generated/ssh_key type: ssh
    jobs: - name: shell instances: 1 persistent_disk: 0 resource_pool: vms networks: - name: private static_ips: 10.0.0.100 default: [dns, gateway] templates: - name: shell release: shell properties: shell: users: - name: shell ssh_keys: - ((/static/ssh_key)) - ((generated/ssh_key))

    Create a pull request or raise an issue on the source for this page in GitHub