Broker static credentials to your first target

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.

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.

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:~
   

   Copy

   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
   

   Copy

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.
   

   Copy

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
   

   Copy

5. Log out of the ubuntu machine using exit.

   $ exit
   

   Copy

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
   

   Copy

   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.
   

   Copy

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"
   

   Copy

   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>
   

   Copy

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
   

   Copy

   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>
   

   Copy

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
   

   Copy

   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:~$
   

   Copy

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

   Secret:
         password:   passw0rd1234
         username:   ssh-user
   

   Copy

   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
   

   Copy

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.