HashiDays One conference. Three cities. Find a city near you
Boundary
Credential management

HCP Boundary Vault credential brokering quickstart

  • 20min
  • |
  • Vault
  • Boundary

This tutorial demonstrated integrating HCP Boundary and Vault to broker secrets to Boundary clients.

Background

Boundary integrates with Vault to broker Vault secrets to Boundary clients. Secrets are brokered using the command line or desktop clients to use Boundary sessions.

Boundary 0.11 adds support for brokering secrets from private Vault clusters.

This feature enables Boundary as a credential broker for infrastructure targets by binding credentials with user sessions, and surfacing those credentials during session initialization.

Boundary Vault Overview

This tutorial provides examples of integrating HCP Boundary and Vault, and then walks through the process of creating Boundary credentials stores and credential libraries for brokering of Vault secrets.

Tutorial Contents

  1. Setup Vault
  2. Deploy a demo database
  3. Setup Boundary
  4. Broker credentials for the database via Boundary

Prerequisites

  • A Boundary binary greater than 0.12.0 in your PATH

  • A Vault binary greater than 1.7.0 in your PATH

  • A psql binary greater than 13.0 in your PATH

  • Docker is installed OR an AWS account for deploying Postgres

  • Installing the Boundary Desktop App provides an optional workflow at the end of this tutorial. The 1.2.0 version or greater is required for Vault support, and installing the latest version is recommended.

This tutorial assumes prior foundational knowledge of using Vault, including running a development server and managing policies, roles and tokens.

If you are new to using Vault, consider completing the Getting Started with Vault quick start tutorials before integrating Vault with Boundary.

Note

If using a public HCP Vault Dedicated cluster and Docker to deploy Postgres, a free ngrok account will also be required to create a publicly routable address. Instructions for installing and configuring ngrok are provided later on.

Tutorial Scenario

Connecting to a networked service often requires credentials for authentication and authorization. For example, a financial analyst might require access to their company's sales database to create a monthly report. When the analyst wants to create the report, they will (hopefully) need database credentials which their reporting tool can use to connect to the sales database and run the report.

In this example, the analyst only needs credentials to the sales database once a month and only for a limited amount of time. If connection to the sales database was through Boundary, the credentials could be generated at the beginning of the session, returned to the analyst, and then revoked when the session is terminated.

This tutorial provides an example of enabling the analyst scenario by setting up a Vault integration with Boundary, and introduces the Boundary resources used for managing credentials.

Get setup

Three pieces must be setup for this tutorial:

  • A demo postgres database target
  • A Vault server with policies allowing connections from Boundary
  • Boundary credential resources for managing credential lifecycle

Open a terminal and navigate to a working directory, such as the home directory. Clone down the sample repository containing starter configuration files.

$ git clone https://github.com/hashicorp-education/learn-boundary-vault-quickstart

Navigate into the learn-boundary-vault-quickstart directory and list its contents.

$ ls -R1
LICENSE
README.md
analyst.sql.hcl
boundary-controller-policy.hcl
dba.sql.hcl
northwind-database-policy.hcl
northwind-database.sql
northwind-roles.sql
worker.hcl

The repository contains the following files:

Setup Vault

Vault needs to be configured to generate secrets for the database target. To set up Vault you need to:

  1. Start Vault
  2. Set up a Boundary controller policy
  3. Enable the database secrets engine
  4. Configure the postgres database plugin
  5. Create a database admin role to generate credentials
  6. Create an analyst role to generate credentials

Public or private Vault access is supported by HCP Boundary. Select one of the options for configuring Vault to continue.

The simplest method of testing Vault integration with HCP Boundary is using a public Vault address. This can be accomplished using HCP Vault Dedicated or Vault Enterprise, but this tutorial demonstrates Vault Dedicated using a public address.

Open the Vault Dedicated cluster Overview page and click Public under Cluster URLs. This will copy the URL to your clipboard.

Public Cluster URL

In a terminal, set the VAULT_ADDR environment variable to the copied address.

$ export VAULT_ADDR="https://vault-cluster-boundary.vault.11eb3a47-8920-4714-ba99-0242ac11000e.aws.hashicorp.cloud:8200"

Return to the Overview page and click Generate token under New admin token. Click Copy to copy the token into your clipboard.

Generate a Token

Return to the terminal and set the VAULT_TOKEN environment variable.

$ export VAULT_TOKEN=hvs.CAESIJm8BHiBBvJNaWW9Pqmjd8uOn3nrAJBpOcbsiPPMlQ5kGicKImh2cy5IMTBqUmt0end6RHNqVFJxQkk5bVZBVXIuQ2RYMGEQngI

Vault Dedicated also requires an exported VAULT_NAMESPACE variable. This tutorial demonstrates using the admin namespace.

Export the VAULT_NAMESPACE variable.

$ export VAULT_NAMESPACE=admin

Verify that you are able to connect to Vault:

$ vault status

Setup PostgreSQL Northwind demo database

The Postgres database target can either be deployed using AWS or Docker. Choose the workflow that best meets your needs.

While most deployments of Postgres will work with the following steps, this tutorial demonstrates configuring Postgres on an Ubuntu instance.

Note

Ubuntu is used in this tutorial for demonstration purposes only. You can follow this guide to create a publicly accessible EC2 instance to use for this tutorial.

Warning

For the purposes of this tutorial it is important that the security group policy for the AWS Ubuntu instance accepts inbound TCP connections on port 5432 to allow incoming connections to Postgres. Additionally, you will want to allow inbound SSH and outbound TCP. To learn more about creating this security group and attaching it to your instance, check the AWS EC2 security group documentation. The screenshot below shows an example of this security group policy.

AWS Postgres Security Group

Log in to the Ubuntu instance that will be configured to run Postgres.

For example, using SSH:

$ ssh ubuntu@198.51.100.1 -i /path/my-key-pair.pem
The authenticity of host 'ec2-198-51-100-1.compute-1.amazonaws.com (198-51-100-1)' can't be established.
ECDSA key fingerprint is l4UB/neBad9tvkgJf1QZWxheQmR59WgrgzEimCG6kZY.
Are you sure you want to continue connecting (yes/no)? yes

ubuntu@ip-172-31-88-177:~

Note

The above example is for demonstrative purposes. You will need to supply your Ubuntu instance's username, public IP address, and public key to connect. If using AWS EC2, check this article to learn more about connecting to a Linux instance using SSH.

Next, update the package manager and install PostgreSQL.

$ sudo apt update

$ sudo apt install postgresql-14

After confirming the installation, execute the following command to modify the postgresql.conf file to allow Postgres to listen on all ports.

$ sudo sed -ibak "s/#listen_addresses\ \=\ 'localhost'/listen_addresses = '*'/g" /etc/postgresql/14/main/postgresql.conf

Next, execute the following command to modify the pg_hba.conf file to allow connections from any address.

$ sudo sed -ibak 's/127.0.0.1\/32/0.0.0.0\/0/g' /etc/postgresql/14/main/pg_hba.conf

Now start the Postgres service.

$ sudo systemctl start postgresql.service

Ensure that Postgres is running:

$ sudo systemctl status postgresql
● postgresql.service - PostgreSQL RDBMS
     Loaded: loaded (/lib/systemd/system/postgresql.service; enabled; vendor preset: enabled)
     Active: active (exited) since Wed 2022-10-19 17:23:47 UTC; 44s ago
    Process: 6897 ExecStart=/bin/true (code=exited, status=0/SUCCESS)
   Main PID: 6897 (code=exited, status=0/SUCCESS)
        CPU: 1ms

Oct 19 17:23:47 ip-172-31-19-96 systemd[1]: Starting PostgreSQL RDBMS...
Oct 19 17:23:47 ip-172-31-19-96 systemd[1]: Finished PostgreSQL RDBMS.

Next, log in as the postgres user. Your prompt will change to postgres@.

$ sudo -i -u postgres
postgres@ip-172-31-19-96:~$

Download the lab environment repository for this tutorial to the Ubuntu instance:

$ git clone https://github.com/hashicorp-education/learn-boundary-vault-quickstart

Navigate into the ~/learn-boundary-vault-quickstart directory and list its contents.

$ cd learn-boundary-vault-quickstart/

$ ls -R1
README.md
analyst.sql.hcl
boundary-controller-policy.hcl
dba.sql.hcl
northwind-database-policy.hcl
northwind-database.sql
northwind-roles.sql
worker.hcl

Create the northwind database.

$ createdb northwind

Seed the database tables using the provided sql configuration.

$ psql -d northwind -f northwind-database.sql --quiet

Apply the database roles and permissions.

$ psql -d northwind -f northwind-roles.sql --quiet

And check that the database tables were written correctly:

$ psql -d northwind -c '\dt'
                 List of relations
 Schema |          Name          | Type  |  Owner
--------+------------------------+-------+----------
 public | categories             | table | postgres
 public | customer_customer_demo | table | postgres
 public | customer_demographics  | table | postgres
 public | customers              | table | postgres
 public | employee_territories   | table | postgres
 public | employees              | table | postgres
 public | order_details          | table | postgres
 public | orders                 | table | postgres
 public | products               | table | postgres
 public | region                 | table | postgres
 public | shippers               | table | postgres
 public | suppliers              | table | postgres
 public | territories            | table | postgres
 public | us_states              | table | postgres
(14 rows)

This information will be queried at the end of the tutorial after the credentials are successfully brokered via Vault.

Before logging out of the account, set a password for the postgres user to make it easy to test the initial connection from Boundary. This tutorial uses the password secret. Enter the password when prompted.

$ psql -c '\password'
Enter new password for user "postgres":
Enter it again:

When finished, log out of the postgres account using exit, and then log out of the Ubuntu instance using exit.

Create the boundary-controller policy

Boundary needs to lookup, renew, and revoke tokens and leases in order to broker credentials properly.

Examine the boundary-controller-policy.hcl policy file, which assigns the following:

  • read auth/token/lookup-self
  • update auth/token/renew-self
  • update auth/token/revoke-self
  • update sys/leases/renew
  • update sys/leases/revoke
  • update sys/capabilities-self

Create the boundary-controller policy.

$ vault policy write boundary-controller boundary-controller-policy.hcl
Success! Uploaded policy: boundary-controller

Configure the database secrets engine

Next, the database secrets engine must be enabled and configured with the postgresql plugin. Then a database admin (DBA) role and analyst role are created to enable credential generation.

  1. Enable the database secrets engine.

    $ vault secrets enable database
Success! Enabled the database secrets engine at: database/

  2. Configure Vault with the postgres-database-plugin, connection information and allowed roles of dba and analyst.

    Replace the 107.20.88.136 IP address example in the following command with your Postgres instance's public IP address.

    $ vault write database/config/northwind \
      plugin_name=postgresql-database-plugin \
      connection_url="postgresql://{{username}}:{{password}}@107.20.88.136:5432/postgres?sslmode=disable" \
      allowed_roles=dba,analyst \
      username="vault" \
      password="vault-password"

  3. Create the DBA role that creates credentials with dba.sql.hcl:

    $ vault write database/roles/dba \
      db_name=northwind \
      creation_statements=@dba.sql.hcl \
      default_ttl=3m \
      max_ttl=60m

    Request the DBA credentials from Vault to confirm.

    $ vault read database/creds/dba
Key                Value
---                -----
lease_id           database/creds/dba/mLuQEYJGTQbycgIDRe5Uig0G
lease_duration     3m
lease_renewable    true
password           0WDx5u6wSI5GE-RVT6LO
username           v-token-dba-nyI68lAMnqyqS2JdBhAp-1624918829

  4. Create the analyst role that creates credentials with analyst.sql.hcl:

    $ vault write database/roles/analyst \
      db_name=northwind \
      creation_statements=@analyst.sql.hcl \
      default_ttl=3m \
      max_ttl=60m

    Request the analyst credentials from Vault to confirm.

    $ vault read database/creds/analyst
Key                Value
---                -----
lease_id           database/creds/analyst/VBTw3MLVq8UYWXHaNBBpYzax
lease_duration     3m
lease_renewable    true
password           ZYjokywhm6U-0e01mrdA
username           v-token-analyst-CFmmvAtFKpkg5PcHP7Ni-1624918869

Create northwind-database policy

A policy needs to be created that grants read access for both the DBA and analyst roles.

Examine the northwind-database-policy.hcl policy file, which assigns the following:

  • read database/creds/analyst
  • read database/creds/dba
$ vault policy write northwind-database northwind-database-policy.hcl
Success! Uploaded policy: northwind-database

Create Vault token for Boundary

Lastly, a Vault token is needed to access the Boundary credential store that will be configured when setting up Boundary.

It's very important that the token is:

  • periodic
  • orphan
  • renewable

Boundary may not be able to broker credentials unless the Vault token has these properties.

Create the token with the boundary-controller and northwind-database policies.

$ vault token create \
  -no-default-policy=true \
  -policy="boundary-controller" \
  -policy="northwind-database" \
  -orphan=true \
  -period=20m \
  -renewable=true \
  -field=token

Example output:

hvs.CAESIAEzd9SuNo84gRvPRnxmck05fJBC5hcbgbMHBlDvR_EqGh4KHGh2cy5YWFp4WUQ4YUtVRDU0amJoOElzcHVkSDU

Export the Vault Boundary token and a the CRED_STORE_TOKEN environment variable. This will be used to set up a Vault credential store later on.

$ export CRED_STORE_TOKEN=hvs.CAESIAEzd9SuNo84gRvPRnxmck05fJBC5hcbgbMHBlDvR_EqGh4KHGh2cy5YWFp4WUQ4YUtVRDU0amJoOElzcHVkSDU

Note

Copy and store the generated token for setting up Boundary later on in case the environment variable is lost. In this example the token value is:

hvs.CAESIAEzd9SuNo84gRvPR...snip...2cy5YWFp4WUQ4YUtVRDU0amJoOElzcHVkSDU.

Set up Boundary

Next the Boundary targets, host sets, and credential libraries will be configured for the database targets and credentials.

First, ensure that you are logged in to HCP Boundary.

Enter the username and password for your Boundary admin user.

Configure database targets

Two targets need to be created in Boundary's default project scope, one for the DBA and another for the analyst. The default host set will then be assigned to both targets.

  1. Create a new scope for the DB targets.

    Open the Orgs page and click New.

    Name the new org db-org and click Save.

  2. Create a new project within db-org.

    Open the Projects page and click New.

    Name the new project db-project and click Save.

  3. Create a new host catalog named db-catalog.

    Open the Host Catalogs page and click New.

    Fill out the following details:

    • Name: db-catalog
    • Type: static

    Click Save.

  4. Create a new host set named db-host-set.

    Within the new host catalog page, click on the Host Sets tab.

    Click New and name the host set db-host-set. Click Save.

  5. Create a new host named postgres-host.

    From the Host Set page, click on the Manage dropdown and click Create and Add Host.

    Fill out the following details:

    • Name: postgres-host
    • Address: 107.20.88.136

    Replace the 107.20.88.136 IP address example in the following command with your Postgres instance's public IP address.

    Click Save.

  6. Create a target for the DBA.

    Navigate to the Targets page and click New.

    Fill out the form details for the new TCP DBA Database target:

    • Name: Northwind DBA Database
    • Type: tcp
    • Maximum Duration (in seconds): 28800
    • Maximum Connections: -1
    • Default Port: 5432

    Click Save.

  7. Create a target for the analyst.

    Navigate to the Targets tab and click New.

    Fill out the form details for the new TCP Analyst Database target:

    1. Name: Northwind Analyst Database
    2. Type: tcp
    3. Maximum Duration (in seconds): 28800
    4. Maximum Connections: -1
    5. Default Port: 5432

    Click Save.

  1. Add the default host set to both targets.

    1. Add host set to the DBA target:

      Click on the Northwind DBA Database target to view its details. Click on the Host Sources tab and select Add Host Sources.

      Check the box beside the db-host-set Host Set, then click Add Host Sources.

      Add Host Sources

      The db-host-set should now be displayed under the Host Sources tab.

    2. Add host set to the analyst target:

      Repeat the steps above for adding the db-host-set to the Northwind Analysts Database target.

      When finished, the db-host-set should be listed under the Host Sources tab for the Northwind Analyst Database target.

Test connection to the sample database

Verify that Boundary can connect to the database target directly, without having a credential brokered from Vault. This is to ensure the target container is accessible to Boundary before attempting to broker credentials via Vault.

Authenticate to Boundary as the admin user. Ensure you have exported the BOUNDARY_AUTH_METHOD_ID and BOUNDARY_ADDR environment variables.

$ boundary authenticate
Please enter the login name (it will be hidden):
Please enter the password (it will be hidden):
Authentication information:
  Account ID:      acctpw_VOeNSFX8pQ
  Auth Method ID:  ampw_ZbB6UXpW3B
  Expiration Time: Mon, 13 Feb 2023 12:35:32 MST
  User ID:         u_ogz79sV4sT
The token was successfully stored in the chosen keyring and is not displayed here.

Execute boundary connect postgres to verify the connection to the analyst target. When prompted, enter the password secret to connect.

$ boundary connect postgres -target-id $ANALYST_TARGET_ID -username postgres
Password for user postgres:
psql (13.2)
Type "help" for help.

postgres=#

Note

If you followed the Admin Console workflow and did not export the ANALYST_TARGET_ID environment variable, supply it directly instead. In this example the analyst target ID is ttcp_1r9XGCXdwE.

After successfully testing the connection, terminate the session by executing \q.

If unable to connect to the target, revisit the section on deploying the demo database at the beginning of the tutorial, and ensure the instance was configured properly.

Credential stores

A credential store belongs to a scope and must support the principle of least privilege by providing mechanisms to limit the credentials it can access to the minimum necessary for the scope it is in.

A credential store:

  • is a Boundary resource
  • belongs to one and only one scope
  • owns zero or more credentials
  • owns zero or more credential libraries
  • is deleted when the scope it belongs to is deleted

In this example the credential store is created to manage HashiCorp Vault secrets. Configuring a Vault credential store requires:

  • A Vault token with appropriate permissions to allow Boundary to access Vault secrets
  • One or more credential libraries and credentials that specify the paths where Boundary should access Vault credentials

Create vault credential store

When setting up an HCP worker, it's important to create a worker filter for the credential store. A worker filter will identify workers that should be used as proxies for the new credential store, and ensure these credentials are brokered from the private Vault.

Recall the filters defined in the worker.hcl file earlier:

worker {
  auth_storage_path = "./hcp-worker1"
  tags {
    type = ["worker", "vault"]
  }
}

The Tags or Name of the worker (hcp-worker1) can be used to create a worker filter for the target.

The example below adds a worker tag filter that searches for workers with the worker tag. Boundary will consider any worker with this tag assigned to it an acceptable proxy for the new credential store.

Create a credential store resource in the default project scope. Supply the token created when setting up Vault.

Navigate to the Credential Stores tab and click New.

Fill out the following required fields for the vault credential type.

  • Address: https://vault-cluster-boundary.vault.11eb3a47-8920-4714-ba99-0242ac11000e.aws.hashicorp.cloud:8200 Recplace with your own public Vault address
  • Token: hvs.CAESIAEzd9SuNo84gRvPRnxmck05fJBC5hcbgbMHBlDvR_EqGh4KHGh2cy5YWFp4WUQ4YUtVRDU0amJoOElzcHVkSDU Replace with the Vault token
  • Namespace: admin Replace with your Vault namespace

Ensure that the Token field matches the token generated by running vault token create in the Create Vault token for Boundary section.

Click Save when finished.

New Credential Store

After the credential store has been created, copy the cred store ID (such as csvlt_ytzGHsfp3r) from its Details page.

Note

If you experience any issues creating the credential store, try regenerating the vault credential store token you created earlier. If the token is not renewed by Boundary within a timely fashion, it may be rejected when you attempt to create the credential store. After creating a new token, retry setting up the credential store.

Credential libraries

A credential library provides credentials for sessions. All credentials returned by a library must be equivalent from an access control perspective. A credential library is responsible for managing the lifecycle of the credentials it returns. For dynamic secrets, this includes creation, renewal, and revocation. For rotating credentials, this includes check-out, check-in, and rotation of secrets. The system retrieves credentials from a library for a session and notifies the library when the session has been terminated. A credential library belongs to a single credential store.

Vault credential libraries are the Boundary resource that maps to Vault secrets engines. A single credential store may have multiple types of credential libraries. For example, Vault credential store might include separate credential libraries corresponding to each of the Vault secret engine backends.

A credential library:

  • is a Boundary resource
  • belongs to one and only one credential store
  • can be associated with zero or more targets
  • can contain zero or more credentials
  • is deleted when the credential store it belongs to is deleted

Create credential libraries

While there is only a single database target, two separate credential libraries should be created for the DBA and analyst roles within the credential store.

The DBA credential library is responsible for brokering credentials at the database/creds/dba vault path, while the analyst credential library brokers credentials at database/creds/analyst. Using two credential libraries allows for separation of privileges, and enables distinct lifecycle management for the different database roles.

  1. Create a credential library for DBA credentials. Supply the credential store ID copied above.

    Navigate to the Credential Stores tab and select the ID of the new credential store (csvlt_W6MP2X0OfP in this example).

    Select the Credential Libraries tab. Click New.

    Fill in the Name and Vault Path for the DBA credential as follows:

    • Name: northwind dba
    • Vault Path: database/creds/dba

    Leave the HTTP Method set as Get. Click Save when finished.

    New Credential Library Details

    Note the DBA credential library ID. In this example the DBA credential library ID is clvlt_ahqypiUJnK.

  2. Create a credential library for analyst credentials. From the Credential Stores tab, select the Manage dropdown and click New Credential Library.

    New Credential Library

    Fill in the Name and Vault Path for the analyst credential as follows:

    • Name: northwind analyst
    • Vault Path: database/creds/analyst

    Leave the HTTP Method set as Get. Click Save when finished.

    Note the analyst credential library ID. In this example the analyst credential library ID is clvlt_ejPFjL3Djf.

    Admin Console Credential Libraries

Credentials and targets

A credential is a data structure containing one or more secrets that binds an identity to a set of permissions or capabilities. Static credential and dynamic credential are two additional base types derived from the credential base type.

A credential:

  • may be a Boundary resource
  • belongs to one and only one credential store
  • can be associated with zero or more targets directly if it is a resource
  • can be associated with zero or more libraries directly if it is a resource
  • is deleted when the credential store or credential library it belongs to is deleted

A target can have multiple credentials or credential libraries associated with it:

  • one for the connection from a user to a worker (ingress)
  • one for the connection from a worker to an endpoint (egress)
  • multiple for application credentials (like username and password)

Application credentials are returned to the user from the controller. Ingress and egress credentials are only given to a worker from a controller, and users never have direct access to them.

Add credential libraries to targets

With the credential libraries created, assign them to the appropriate targets. You will need the target ID and credential library ID for the respective targets.

Navigate to the Targets tab.

  1. Add a credential library to the DBA target.

    Select the Northwind DBA Database target.

    Under the Brokered Credentials tab, select Add Brokered Credentials.

    Add Credential Sources

    Select the checkbox next to the ID of the credential library associated with the northwind dba target.

    Click Add Brokered Credentials when finished.

    Select Credential Source

  2. Add a credential library to the analyst target.

    Navigate back to the Targets tab and select the Northwind Analyst Database target.

    Under the Brokered Credentials tab, select Add Brokered Credentials.

    Select the checkbox next to the ID of the credential library associated with the northwind analyst target.

    Click Add Brokered Credentials when finished.

Broker credentials via Vault

With their respective credential libraries assigned added to the targets, sessions can be authorized using credentials brokered by Vault.

Use Boundary to connect to the northwind demo database

A session can be authorized directly using the boundary targets authorize-session command.

Authenticate to Boundary as the admin user. Ensure you have exported the BOUNDARY_AUTH_METHOD_ID and BOUNDARY_ADDR environment variables.

$ boundary authenticate
Please enter the login name (it will be hidden):
Please enter the password (it will be hidden):
Authentication information:
  Account ID:      acctpw_VOeNSFX8pQ
  Auth Method ID:  ampw_ZbB6UXpW3B
  Expiration Time: Mon, 13 Feb 2023 12:35:32 MST
  User ID:         u_ogz79sV4sT
The token was successfully stored in the chosen keyring and is not displayed here.

Authorize a session to the analyst target, supplying its target ID.

Note

If you followed the Admin Console workflow and did not export the ANALYST_TARGET_ID environment variable, copy it from the web UI and supply it directly instead. In this example the analyst target ID is ttcp_1r9XGCXdwE.

$ boundary targets authorize-session -id $ANALYST_TARGET_ID

Target information:
  Authorization Token:
  Gy89BTaB1gYeMyWFH19eVSz5wX8fZwPvHmuK6NNdjHZKKdyTL2Pmz6s4BZzsVDDTBH9U3mFkPHukKqev65bJkvLt8w5xwdUj2dvNuCBZ6hS5Y4x2m9qKBfLaD23DprCcrTY7F37tEZmW3qVhrJpr63uSM4BtWPDoSApTTXumKPHJiFGx15TTmggHTexx5C7gWeDLu4yVwpZoFV28FbPiyrY4H5zukzBruGVCGhaKQ5orYJfbjwQe3YfBkVarpMwC2ABj2DrJCM3cmA9UturejmD7XApAvqrG3tqBmh2FYoC1oWPu88FT73vZNdF8jJB1dtGCekzRKmsvZ9SHnQ9gMeBppAw6ME1kaQrSzKaSBqRuhEF86FJ47pAB8V7metTmXXyhPh6DWhpow7PneXMTsvy93sb94fJeBrCifAgUzSWbEF4VftybUVamEkVVHywnfH1So3qQU9YyvZ7LmUuSYXk3UEfZwpsxt6GFCs14WS4QpJHpeWqArpPCSm9MPmZLf4En3A4hN11PPr9aWch7kRP1VGrmJrZyj7RnaLE1FnKhmbUSyt71vpf9kBUHDWbpYrmS5umYQHM6L9qciZytsJ7PCHb2NZeRrAXPUf315E8gxU38PPtpEN5oa3tTWcFtvwxY7bVeKgpPHdFhrAjaWxqEZY4jMbNb5cty45tXQkLNpNRNv1CBFUW39bnjC1NC2QEKEHz3NFmeHhZ8dzXVVdoJ2YGGDEr7NhKUpnKdKPELK1HDk7HN4nzegDa8FZLw1nS1f
  Created Time:          Fri, 30 Sep 2022 11:57:54 MDT
  Endpoint:              tcp://127.0.0.1:16001
  Host ID:               hst_xGokAphK8a
  Scope ID:              p_JUo2oXfQ8V
  Session ID:            s_Sk15Ra9QLk
  Target ID:             ttcp_WnvTBiDkXT
  Type:                  tcp
  User ID:               u_XXupFxmcJn

  Credentials:
    Credential Store ID:           csvlt_W6MP2X0OfP
    Credential Source ID:          clvlt_ejPFjL3Djf
    Credential Source Type:        vault
    Credential Source Name:        northwind analyst
    Secret:
      {
        "password": "vTyCeBD-ZYEUCBcTU50L",
        "username": "v-token-analyst-TCqh52mi6basivp9z5LZ-1664560674"
      }

Notice the Credentials: section of the output, which displays the base64 credentials.

If desired, jq can be used to parse the output and display the decoded credentials.

$ boundary targets authorize-session -id $ANALYST_TARGET_ID -format json | jq .
{
  "status_code": 200,
  "item": {
    "session_id": "s_fCkIVFsRoG",
    "target_id": "ttcp_WnvTBiDkXT",
    "scope": {
      "id": "p_JUo2oXfQ8V",
      "type": "project",
      "name": "db-project",
      "parent_scope_id": "o_gqU7PutJyJ"
    },
    "created_time": "2022-09-30T17:58:22.826896Z",
    "user_id": "u_XXupFxmcJn",
    "host_set_id": "hsst_SCw3foI32I",
    "host_id": "hst_xGokAphK8a",
    "type": "tcp",
    "authorization_token": "Gy89BU8gNJ1RdmLfn31KzBme8eLHmL1QgC2nu2oGu8bmjpKeGa2gF8zZuyV5taoAkE8KFdPmNYLzoTX5zJHZGs2foX94q8rkcCFFpnCM6RGRP6gYEw8PGbdnTdXN3UzvcPKnyC8UAQW2DnWSZg6VFn3DMjgJNjYZh8A55dZn2CkNhx4ki9zPonMHe3bLrSw5bifpGnwnqDXiWdRg4hf3LRMH69obpHYcbAucxoiMQr3vL48GRQpeEt6VsRavroNCmDo77YGKrxWuDsCA6EwQgZ3UrxsENeuccfMAHUiTLAcfaBatJhypLqWDSkMdxWf1tfVNY5TmAEq9XLxJfNJX8obim8torU3qRuKxenhXi1pKZx6okYH46nNfcY7F7QFK51ZytaKuH1D8tfJqqgzwUHhERhCW1QQvVMw6sJmiTDJHFUZ8JrF9rXMchfSskyjvxg4HsQTTS91s3YgQCKF1iKmpMfbs9hnmRFbP4DzYm8VswPVE638nwd6U7mdD7RmWbvEKoPAoEbtP1fTcw1pzfThHcYmMshPKCdbqg8hXL7bHvLwCKAswHfXhbgTq8UDu2MEbLJE49PkLequV3zrvHphKCx6Vzc1D7a7sxWhPgb2VdQTEKQBCWwXDaszAbsj8Cn3tEQcbnYMbTUPsVqzV1mpz5Vj23ps8SxJ7diRUVAuCjc4s1xAuph9UtSHqWFmK86SqWvVga3GB4GnofCeaNV8Tx4oR8azx66QEG1wt1dMinjAxF9sMnmPNiu2VTmse76hN9",
    "endpoint": "tcp://127.0.0.1:16001",
    "credentials": [
      {
        "credential_source": {
          "id": "clvlt_ejPFjL3Djf",
          "name": "northwind analyst",
          "credential_store_id": "csvlt_W6MP2X0OfP",
          "type": "vault"
        },
        "secret": {
          "raw": "eyJwYXNzd29yZCI6IlZJaG01V0hMT0hKS2VGY0stNVVpIiwidXNlcm5hbWUiOiJ2LXRva2VuLWFuYWx5c3QtWW9pa0pVRDA2RUcyRVZvazN4eTgtMTY2NDU2MDcwMiJ9",
          "decoded": {
            "password": "VIhm5WHLOHJKeFcK-5Ui",
            "username": "v-token-analyst-YoikJUD06EG2EVok3xy8-1664560702"
          }
        }
      }
    ]
  }
}

The decoded_credentials key displays the credentials without the base64 encryption.

Next, establish a connection to the analyst target using the boundary connect postgres command. This will automatically pass the brokered credentials for the target and establish a psql session to the northwind database.

$ boundary connect postgres -target-id ttcp_1r9XGCXdwE -dbname northwind

psql (13.2)
Type "help" for help.

northwind=>

A psql connection to the northwind database should open. Query the available schema.

$ \d
                 List of relations
 Schema |          Name          | Type  |  Owner
--------+------------------------+-------+----------
 public | categories             | table | postgres
 public | customer_customer_demo | table | postgres
 public | customer_demographics  | table | postgres
 public | customers              | table | postgres
 public | employee_territories   | table | postgres
 public | employees              | table | postgres
 public | order_details          | table | postgres
 public | orders                 | table | postgres
 public | products               | table | postgres
 public | region                 | table | postgres
 public | shippers               | table | postgres
 public | suppliers              | table | postgres
 public | territories            | table | postgres
 public | us_states              | table | postgres
(14 rows)

When finished, run \q to close the connection.

Connections can also be monitored using the Admin Console or the Boundary Desktop app in the Sessions tab in the Generated project scope.

Desktop App Sessions

Connect using the Desktop App

Credentials can also be brokered using the Boundary Desktop App.

Launch the Desktop app and authenticate to your HCP Boundary cluster by entering the BOUNDARY_ADDR (such as https://c3a7a20a-f663-40f3-a8e3-1b2f69b36254.boundary.hashicorp.cloud) and your admin credentials.

Boundary Desktop Login

Navigate to the Targets view, locate the Northwind Analyst Database target and click Connect.

Desktop App Connect

The credentials can be copied directly from this view. Depending on the target type other credentials may be available, such as the certificate and private key. The Desktop App's connect interface can be used instead of generating the credentials on the command-line.

Desktop App Credentials

The password, username and raw API output can also be displayed within the UI.

Desktop App Credentials

Cleanup and teardown

  1. Locate the terminal session used to start the vault server command, and execute ctrl+c to stop Vault.

  2. Unset the environment variables used in any active terminal windows for this tutorial.

    $ unset VAULT_ADDR; unset VAULT_TOKEN

  3. Destroy the northwind postgres container created for the tutorial.

    $ docker rm -f northwind

    Check your work with a quick docker ps and ensure there are no more postgres containers from the tutorial leftover. If unexpected containers still exist, execute docker rm -f <CONTAINER_ID> against each to remove them.

  4. Cleanup the db-org org and associated test resources in your HCP Boundary cluster.

    Open the Orgs page and select the db-org.

    Navigate to the Org Settings page and click the Manage dropdown.

    Click Delete Org and confirm the deletion.

    Delete Org

Help and reference

Collection Overview

Credential management

 Next

SSH certificate injection with HCP Boundary