sandraliu88/boundary-demo

Boundary Demo

Demo Environment

This terraform code builds an HCP Boundary enviroment that inclues connectivity to HCP Vault for credential brokering and injection, Okta integration for OIDC authentication and managed groups, and a number of AWS resources that are used as workers and Boundary targets.

Features

• SSH with Vault generated SSH Certificates and username templating
• RDP Target with brokered AD credentials from Vault LDAP Secrets Engine
• Okta integration using managed groups with different targets for each group
• Session Recording
• K8s target with brokered credentials from Vault K8s Secrets Engine
• Database target with brokered credentials from Vault DB Secrets Engine
• Multi-hop using HCP ingress worker and private egress worker

Boundary Organization Structure

Demo Environment Diagram

Components

Component	Purpose
HCP Boundary	Boundary Control Plane
HCP Vault	Boundary Credential Store
Boundary Worker	Boundary EC2 Worker
Okta	OIDC Authentication
EC2 Linux Instance	SSH Cert Auth Target, Postgres Target, K8s Target
EC2 Windows Instance	RDP Target

Setup

This video walks through setting up most of the pre-requisites and building the environment: https://www.youtube.com/watch?v=k1ioZtfEXkk

Prerequisites

HCP Account

You will need an account on the Hashicorp Cloud Platform to create the Boundary and Vault clusters. Sign up for an HCP account here: https://www.hashicorp.com/cloud. You will also need to create a Service Principal and Service Principal keys. The documentation for creating a Service Principal is here: https://developer.hashicorp.com/hcp/docs/hcp/admin/iam/service-principals.

Okta Developer Account

You will need an Okta developer account to fully utilize this demo. You can sign up for an account here: https://developer.okta.com/signup/ Once logged in you will need to create an API token. The process for creating an API token is here: https://developer.okta.com/docs/guides/create-an-api-token/main/#create-the-token. Be sure to save the token as you will need it later.

A Variable Set with AWS credentials

You will need a pre-existing variable set with AWS credentials that have appropriate permissions to deploy the various resources. If you are a Hashicorp employee with an SE demo account then you can use doormat to generate these credentials and push them into the appropriate variable set. Documentation on using doormat can be found here: https://hashicorp.atlassian.net/wiki/spaces/SE/pages/1617101761/Doormat.

An SSH Key Pair

You will need an SSH key pair to set up authentication to the SSH target using user provided credentials. You may already have a public and private key pair (generally id_rsa.pub and id_rsa) in the .ssh folder of your home directory if you are using Mac or Windows. To create a new key pair you can use Putty or OpenSSL. OpenSSL directions are here: https://wiki.osuosl.org/howtos/ssh_key_tutorial.html

You will use the public key as an environment variable and the private key will be used to authenticate to the SSH target later.

Workspaces and Variables

This repo was built to run on Terraform Cloud or Enterprise. It uses the tfe_outputs data source to pass parameters between the boundary_demo_init workspace and other workspaces. If you want to run this locally you will need to modify the code to use cross state sharing to populate those values.

The providers.tf file in each workspace includes a cloud block that targets a TFC/TFE organization. You will need to update this block to reflect your TFC/TFE org name.

This repo consists of four modules:

boundary-demo-tfc-build - This module is run using local terraform execution and build the boundary-demo-init and boundary-demo-targets workspaces in TFC/TFE

boundary-demo-init - This workspace builds an HCP Boundary cluster and HCP Vault cluster along with an associated HVN for the Vault cluster.

boundary-demo-targets - This workspace does the bulk of the work, building out all of the Boundary and Vault configuration as well as the AWS components used as workers and targets.

boundary-demo-ad-secrets - This workspace configures the Vault LDAP secrets engine to generate dynamic AD credentials on the windows target and brokers those credentials to the it-rdp-target-admin Boundary target.

The following variables need to be set in the boundary-demo-tfc-build module. These variables will be propogated into the TFC/TFE workspaces built by that module.

Variable	Type	Sensitive	Purpose
organization	terraform	No	The TFC/TFE Organization Name
boundary_user	terraform	No	The username the default admin user created in the HCP Boundary Cluster
boundary_password	terraform	Yes	The password of the default admin user created in the HCP Boundary Cluster
region	terraform	No	The AWS region into which to deploy the Hashicorp Virtual Network and AWS resources
okta_baseurl	terraform	No	The base url of the Okta organization to use for OIDC integration. Usually okta.com
okta_org_name	terraform	No	The organization name of hte OKta organization to use for OIDC integration i.e dev-32201783
okta_user_password	terraform	Yes	The password to set on the Okta users created and added to the Boundary application
admin_pass	terraform	Yes	The password to set for the Administrator account on the Windows target
public_key	terraform	No	The SSH public key to set on the AWS EC2 instances as the default login
aws_varset	terraform	No	The name of a pre-existing Variable Set that contains AWS credentials set as environment variables
OKTA_API_TOKEN	environment	Yes	The API token used to authenticate the Okta provider
HCP_CLIENT_ID	environment	Yes	The Client ID used to authenticate the HCP provider
HCP_CLIENT_SECRET	environment	Yes	The Secret Key used to authenticate the HCP provider

It is recommended that you pass any variables marked sensitive as environment variables or through CLI flags.

To Build

• Push credentials from doormat to your AWS variable set

  • doormat aws tf-push variable-set --id <variable set id> --account <aws_account_name>

• Set the non-sensitive variables for the boundary-demo-tfc-build module in a terraform.tfvars file.

• Set the sensitive variables as environment variables.

  • For example:

  • export TF_VAR_HCP_CLIENT_SECRET=123456789

• Update the cloud block in the providers.tf file in the boundary-demo-init and boundary-demo-targets workspaces to reflect your TFE/TFC organization name.

• Once all variables have been set, perform a terraform init and apply on the boundary-demo-tfc-build module.

  • boundary-demo-tfc-build % terraform init

  • boundary-demo-tfc-build % terraform apply -auto-approve

  • This will create two workspaces in your TFC environment: boundary-demo-init and boundary-demo-targets.

• Run the boundary-demo-init workspace first.

  • boundary-demo-init % terraform init

  • boundary-demo-init % terraform apply -auto-approve

• Run build the boundary-demo-targets workspace

  • boundary-demo-targets % terraform init

  • boundary-demo-targets % terraform apply -auto-approve

• Wait about 10 minutes after building the boundary-demo-targets workspace for the rdp-target EC2 instance to finish running it's cloudinit script which requires two reboots. The boundary-demo-ad-secrets workspace run will fail if the cloudinit has not completely finished.

• Run the boundary-demo-ad-secrets workspace

  • boundary-demo-ad-secrets % terraform init

  • boundary-demo-ad-secrets % terraform apply -auto-approve

Important Notes

• If you do not wish to use the Okta integration you can delete or comment out the okta.tf file from the boundary-demo-targets folder in the repo. You will also need to comment out the references to the Okta provider in the providers.tf file in the boundary-demo-targets folder. The pie-ssh-cert-target target will not work if you do not have Okta integration.

• The Vault token generated by the boundary-demo-init workspace expires after 6 hours. If you get Vault errors when attemtping to rerun other workspaces then first run a fresh apply on the boundary-demo-init workspace to create a new Vault token.

• The Dynamic Host Set setup uses an IAM role and User configuration that is specific to Hashicorp Employee AWS sandbox accounts. If used in account without restrictions on the ability to create IAM users and policies then you will want to modify the configuration at the top of the boundary.tf config file to create the required IAM user and policy directly.

• The terraform code is generally stable and completes in a single run but if you experience issues a second run is usually enough to correct them.

• If the self-managed worker does not come up properly or dies for some reason you can rebuild it by tainting the boundary_worker and aws_instance resources in the created in the worker.tf file and then rerunning the terraform apply on the boundary-demo-eks workspace.

  • terraform taint boundary_worker.hcp_pki_worker

  • terraform taint aws_instance.worker

To Destroy

Destroy the workspaces in the reverse order that you created them. Run a terraform destroy first on the boundary-demo-ad-secrets workspace, then on the boundary-demo-targets workspace, then on the boundary-demo-init workspace and finally on the boundary-demo-tfc-build module.

The TF code creates a Session Recording Bucket object in the global scope. Boundary does not currently support deleting Session Recording Buckets so when attempting to run terraform destroy on the boundary-demo-targets workspace TF will throw an error. Currently the workaround is remove the boundary_storage_bucket resource from state and then run the destroy.

• terraform state rm boundary_storage_bucket.pie_session_recording_bucket

Connecting to Targets

Okta Users

When using the Okta integration four users are created in your directory.

Passwords - All Okta users have the same password which is the value of the okta_user_password terraform variable that you set in the boundary-demo-tfc-build workspace.

User	Okta Group	Boundary Org	Description
[email protected]	All	All	Has rights to connect to all targets in all orgs
[email protected]	pie_users	pie_org	Has rights to connect to all targets in PIE org
[email protected]	dev_users	dev_org	Has rights to connect to all targets in DEV org
[email protected]	it_users	it_org	Has rights to connect to all targets in IT org

Available Targets

Target	Org\Project	Credentials	Description
pie-ssh-cert-target	pie_org\pie_aws_project	Injected using Vault SSH Cert Secrets Engine	Connects to the SSH target as the logged in username. Only usable when logged in via Okta as pie_user or global_user
pie-ssh-cert-target-admin	pie_org\pie_aws_project	Injected using Vault SSH Cert Secrets Engine	Connects to the SSH target as ec2-user
pie-ssh-tcp-target	pie_org\pie_aws_project	User supplied ssh key	Connect using user supplied SSH key
pie-k8s-target	pie_org\pie_aws_project	Brokered SA token from Vault K8s Secrets Engine	Connect using the k8s-connect script in the scripts folder of the repo. See video below for more info
dev-db-target	dev_org\dev_aws_project	Brokered from Vault DB Secrets Engine	Connects using credentials brokered from Vault
it-rdp-target	it_org\it_aws_project	User supplied username and password	Connect using [email protected] user and password set in admin_pass TF variable
it-rdp-target-admin	it_org\it_aws_project	Brokered from Vault LDAP Secrets Engine	Connect using username (be sure to add @boundary.lab to the end) and password provided by Vault in connection info

Connecting to Targets

This video walks through connecting to the various targets that are created in the demo environment. The .14 version of the Boundary Desktop client has an integrated shell that can be used to automatically connect to SSH targets with brokered or injected credentials.

https://www.youtube.com/watch?v=K_eBdgqwx9k