HashiDays One conference. Three cities. Find a city near you
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=ubuntuUBUNTU_KEY=my_key_file.pemPROJECT_ID=p_vM7cfGEgq8TARGET_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_IDTarget 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_KEYThe 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)? yesubuntu@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-userChanging 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-userssh-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 authenticatePlease 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_1vUkf5fPs9The 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_KEYCredentials:  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-userWelcome 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 updateLast login: Mon Aug 29 22:00:40 2022 from 34.232.124.174ubuntu@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-userPassword:$ whoamissh-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