HashiConf 2024 Now streaming live from Boston! Attend for free
Boundary
HCP quick start

Broker static credentials to your first target

  • 8min
  • |
  • HCP
  • Boundary

A credential store is a Boundary resource used to store, retrieve, and sometimes generate credentials. Credential stores are scoped under projects and observe the principle of least privilege to limit access. Credential stores may contain credential libraries.

In this tutorial, you will create credentials of type username_password and add them to a static credential store using Boundary. These concepts are foundational to learning about credential injection with HCP Boundary later on.

Prerequisites

  • Access to an HCP Boundary instance.
  • Boundary is installed.
  • Completed the previous quick start tutorials.
  • A publicly accessible Ubuntu instance.
  • A ssh key-pair for authenticating to the 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.

Lab setup

In the previous tutorial, the following Boundary resources were defined:

  • A project
  • A target of type TCP with an assigned address

The ubuntu host was created with an address assigned directly to the target. This allowed for boundary connect ssh to run the connection through Boundary with user-supplied SSH credentials.

Several environment variables were created to support the tutorial. These environment variables are used throughout the Getting Started series.

Check the environment variable values defined in the previous tutorial for $UBUNTU_USER, $UBUNTU_KEY,$PROJECT_ID, and $TARGET_ID are available.

$ echo "UBUNTU_USER=$UBUNTU_USER"; echo "UBUNTU_KEY=$UBUNTU_KEY"; echo "PROJECT_ID=$PROJECT_ID"; echo "TARGET_ID=$TARGET_ID"
UBUNTU_USER=ubuntu
UBUNTU_KEY=my_key_file.pem
PROJECT_ID=p_vM7cfGEgq8
TARGET_ID=ttcp_INY0BCD2VF

If any of these values are not defined, ensure that you have completed the Connect to Your First Target tutorial.

If these values were defined in an unavailable shell session, list the IDs for the resources and export them as environment variables.

For example, to find the TARGET_ID:

$ boundary targets list -scope-id $PROJECT_ID

Target information:
  ID:                    ttcp_KM3A26XXvG
    Version:             1
    Type:                tcp
    Name:                ubuntu-target
    Description:         ubuntu target
    Address:             192.168.100.253
    Authorized Actions:
      no-op
      read
      update
      delete
      add-host-sources
      set-host-sources
      remove-host-sources
      add-credential-sources
      set-credential-sources
      remove-credential-sources
      authorize-session

Then, export the environment variable.

$ export TARGET_ID=<my target ID>

Repeat this process for the other undefined variables.

Note

The use of environment variables is not required to use HCP Boundary. Environment variables are used throughout the tutorial for ease of following along and copying the required commands.

Set up a new user on the target

In the previous tutorial, boundary connect ssh was used with a user-supplied private key to proxy an SSH session through Boundary.

To demonstrate credential brokering, you will first configure your Ubuntu instance with a new user.

  1. Execute the boundary connect ssh command to log in the Ubuntu instance.

    $ boundary connect ssh -target-id=$TARGET_ID -- -l $UBUNTU_USER -i $UBUNTU_KEY

The authenticity of host 'ec2-198-52-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-32-88-177:~

    Your system prompt will be replaced with a prompt similar to ubuntu@ip-172-32-88-177:~.

    Note

    The prompt within this section is shown as $ but the commands are intended to be executed within this interactive shell on the Ubuntu machine.

  2. While logged in, create a new user account.

    $ sudo useradd ssh-user

  3. Define a password of passw0rd1234 for the new ssh-user.

    $ sudo passwd ssh-user

Changing password for user ssh-user.
New UNIX password:
Retype new UNIX password:
passwd: all authentication tokens updated successfully.

  4. Verify the new user was defined correctly by checking the /etc/passwd file contents.

    $ cat /etc/passwd | grep ssh-user
ssh-user:x:1000`:1000:ssh-user:/home/ssh-user:/bin/bash

  5. Log out of the ubuntu machine using exit.

    $ exit

  6. On your host machine, export the ssh-user password as the SSH_USER_PASS environment variable. This value will be passed to Boundary when creating the new credential.

    $ export SSH_USER_PASS=passw0rd1234

    Note

    If you used a unique password for the ssh-user, replace passw0rd1234 in the SSH_USER_PASS environment variable.

Create a static credential

  1. Log into your HCP Boundary instance. Enter the password you created when deploying the HCP Boundary instance at the Please enter the password (it will be hidden): prompt.

    $ 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_wxzojlKJLN
  Expiration Time: Mon, 13 Feb 2023 12:35:32 MST
  User ID:         u_1vUkf5fPs9
The token was successfully stored in the chosen keyring and is not displayed here.

  2. Create a new static credential store that will contain the new ssh-user login credentials.

    $ boundary credential-stores create static \
   -scope-id $PROJECT_ID \
   -name "login-credentials"

    Example output:

    Credential Store information:
  Created Time:        Mon, 29 Aug 2022 15:41:05 MDT
  ID:                  csst_O8utI0b3XC
  Name:                login-credentials
  Type:                static
  Updated Time:        Mon, 29 Aug 2022 15:41:05 MDT
  Version:             1

  Scope:
    ID:                p_vM7cfGEgq8
    Name:              quick-start-project
    Parent Scope ID:   o_XVoiuPfG1D
    Type:              project

  Authorized Actions:
    no-op
    read
    update
    delete

  Authorized Actions on Credential Store's Collections:
    credentials:
      create
      list

  3. Copy the ID of the new static credential store and export it as the CRED_STORE_ID environment variable.

    $ export CRED_STORE_ID=<actual-cred-store-id>

  4. Define a new username_password credential within the static credential store.

    Note

    Passwords can only be passed to the -password option using the env:// or file:// syntax to prevent credentials from being logged within the terminal.

    $ boundary credentials create username-password \
   -name ssh-user \
   -credential-store-id $CRED_STORE_ID\
   -username ssh-user \
   -password env://SSH_USER_PASS

    Example output:

    Credential information:
 Created Time:          Mon, 29 Aug 2022 15:53:02 MDT
 Credential Store ID:   csst_O8utI0b3XC
 ID:                    credup_bAPYr1NK1C
 Name:                  ssh-user
 Type:                  username_password
 Updated Time:          Mon, 29 Aug 2022 15:53:02 MDT
 Version:               1

 Scope:
   ID:                  p_vM7cfGEgq8
   Name:                quick-start-project
   Parent Scope ID:     o_XVoiuPfG1D
   Type:                project

 Authorized Actions:
   no-op
   read
   update
   delete

 Attributes:
   Password HMAC:       HrtC8JypKXjryr_GefweWGceMPOBrnVtX1CRJ4qiULc
   Username:            ssh-user

    Notice that only the Password HMAC is returned upon creating the new credential.

  5. Export the credential ID as the SSH_USER_CRED_ID environment variable.

    $ export SSH_USER_CRED_ID=<actual-credintial-id>

Attach the credential to a target

Now that the username_password credential exists within Boundary, it can be added to the ubuntu-target target.

  1. Associate the credential with the target.

    $ boundary targets add-credential-sources \
   -id $TARGET_ID \
   -brokered-credential-source $SSH_USER_CRED_ID

    Example output:

    Target information:
  Created Time:               Mon, 29 Aug 2022 15:32:24 MDT
  Description:                my first target
  ID:                         ttcp_INY0BCD2VF
  Name:                       quick-start-target
  Session Connection Limit:   -1
  Session Max Seconds:        28800
  Type:                       tcp
  Updated Time:               Mon, 29 Aug 2022 16:09:47 MDT
  Version:                    3

  Scope:
    ID:                       p_vM7cfGEgq8
    Name:                     quick-start-project
    Parent Scope ID:          o_XVoiuPfG1D
    Type:                     project

  Authorized Actions:
      no-op
      read
      update
      delete
      add-host-sources
      set-host-sources
      remove-host-sources
      add-credential-sources
      set-credential-sources
      remove-credential-sources
      authorize-session

  Host Sources:
    Host Catalog ID:          hcst_fp08VKJu1F
    ID:                       hsst_rtS9Smbqi8

  Brokered Credential Sources:
    Credential Store ID:      csst_O8utI0b3XC
    ID:                       credup_bAPYr1NK1C

  Attributes:
    Default Port:             22

    With the new credential attached to the ubuntu-target as a Brokered Credential Source, the credentials will be displayed to the user when Boundary authorizes a session.

Connect and broker credentials

  1. Connect to the target.

    $ boundary connect ssh -target-id=$TARGET_ID -- -l $UBUNTU_USER -i $UBUNTU_KEY

Credentials:
  Credential Source ID:   credup_bAPYr1NK1C
  Credential Source Name: ssh-user
  Credential Store ID:    csst_O8utI0b3XC
  Credential Store Type:  static
  Credential Type:        username_password
  Secret:
        password:   passw0rd1234
        username:   ssh-user

Welcome to Ubuntu 22.04 LTS (GNU/Linux 5.15.0-1011-aws x86_64)

 * Documentation:  https://help.ubuntu.com
 * Management:     https://landscape.canonical.com
 * Support:        https://ubuntu.com/advantage

  System information as of Mon Aug 29 22:13:44 UTC 2022

  System load:  0.0               Processes:             98
  Usage of /:   19.2% of 7.58GB   Users logged in:       0
  Memory usage: 21%               IPv4 address for eth0: 172.31.22.151
  Swap usage:   0%

0 updates can be applied immediately.

The list of available updates is more than a week old.
To check for new updates run: sudo apt update

Last login: Mon Aug 29 22:00:40 2022 from 34.232.124.174
ubuntu@ip-172-31-22-151:~$

    During the connection process, the brokered credentials are displayed to the client:

    Secret:
      password:   passw0rd1234
      username:   ssh-user

    Note that passw0rd1234 is the password supplied when setting up the ssh-user on the Ubuntu host, and defined when creating the username_password credential.

    With these brokered credentials, the user could log in as this user, or perform other tasks requiring these credentials:

    ubuntu@ip-172-31-22-151:~$ su ssh-user
Password:
$ whoami
ssh-user
$ exit

    This is a simple example of logging in as another system-level user, but other useful application credentials could also be provided to the client, such as credentials for a database running on the ubuntu host.

  2. Log out of the ssh-user account and then the ubuntu host using exit.

    $ exit

Next steps

In this tutorial you learned how to broker static credentials when connecting to a host. Next, you will learn how to install the Boundary Desktop app and connect to a host.

Previous

Connect to your first target

 Next

Install Boundary Desktop