Set up AWS auth method for HCP Vault Dedicated
This tutorial will walk you through the basic steps to enable and configure the Amazon Web Services (AWS) auth method for HCP Vault Dedicated.
You will learn how to set up the necessary resources in your AWS account and Vault Dedicated cluster.
- Create a AWS IAM policy to allow Vault Dedicated to validate the identity of AWS services.
- Create a AWS IAM user to allow Vault Dedicated to access your AWS resources.
- Create AWS IAM role which will be assigned to AWS services and trusted by Vault Dedicated.
- Enable the AWS auth method for Vault Dedicated.
- Assign the AWS IAM user credentials to the AWS auth method configuration.
- Configure a Vault Dedicated role to authenticate AWS services with a trusted AWS IAM role.
- Validate the configuration using a EC2 instance and the Vault binary.
Note
Deploying and configuring the items in this tutorial may lead to additional charges in your AWS or HCP account.
Personas
The end-to-end scenario described in this tutorial involves two personas:
admin
with privileged permissions to configure an auth methodapp
is the consumer of secrets stored in Vault
Prerequisites
To complete this tutorial you should have familiarity with, and access to the HashiCorp Cloud Platform (HCP), Vault Dedicated, and AWS.
Visit the Getting Started with HCP Vault Dedicated tutorials for a refresher on how to deploy and configure Vault Dedicated.
Note
This tutorial will use the naming conventions from the Getting Started with HCP Vault Dedicated tutorials when referencing HCP resources.
Please verify all prerequisites have been met for Vault Dedicated, AWS, and your local workstation.
HCP Vault Dedicated
The following items be must be deployed in the HCP Portal to complete this tutorial.
HashiCorp Virtual Network (HVN) created.
A Vault cluster with public address. (Refer to the Create a Vault Cluster on HCP tutorial.)
Warning
Making the HCP Vault Dedicated cluster publicly accessible is not recommended, however for ease of completing this tutorial we suggest you have it enabled.
Note
You can learn how to connect to a private HCP Vault Dedicated cluster in the Connect an Amazon Transit Gateway to your HashiCorp Virtual Network or Peering an AWS VPC with HashiCorp Cloud Platform (HCP) tutorials.
AWS
During this tutorial, you will create several Identity and Access Management (IAM) resources, create an Amazon Linux2 instance and connect via SSH to demonstrate authentication with Vault Dedicated.
Access to an AWS account with a Virtual Private Cloud (VPC), attached Internet Gateway (IGW), routing tables, and public subnet.
User credentials that have permissions to create Identity and Access Management (IAM) users, policies, and roles.
User credentials that have permission to create Elastic Compute (EC2) instances, security groups, attach IAM roles, and access to or ability to create key pairs to connect to the EC2 instance.
Workstation
This tutorial was developed and tested using OSX, however you can complete this tutorial by making the necessary changes to support your preferred Operating System (OS).
HashiCorp Vault binary installed. Please see the Install Vault tutorial for more information.
Access to a terminal/command line interface and ability to create SSH sessions.
Lab setup
Note
If you do not have access to an HCP Vault Dedicated cluster, visit the Create a Vault Cluster on HCP tutorial.
Launch the HCP Portal and login.
Click Vault in the left navigation pane.
In the Vault clusters pane, click vault-cluster.
Under Cluster URLs, click Public Cluster URL.
In a terminal, set the
VAULT_ADDR
environment variable to the copied address.Return to the Overview page and click Generate token.
Within a few moments, a new token will be generated.
Copy the Admin Token.
Return to the terminal and set the
VAULT_TOKEN
environment variable.Set the
VAULT_NAMESPACE
environment variable toadmin
.Type
vault status
to verify your connectivity to the Vault cluster.With the environment variables set, you can now explore your Vault cluster. Type
vault auth list
to view the list of available auth methods.All new Vault clusters will have the
token
auth method enabled.
Create AWS resources
(Persona: admin)
Before you configure the Vault Dedicated AWS auth method, you must create the necessary resources in AWS. The AWS auth method will require an IAM policy that permits the appropriate access for the auth method, an IAM user with programmatic access, and one or more roles that you will assign to other AWS services that require authentication to Vault.
Create AWS IAM policy for HCP Vault Dedicated auth method
Launch the AWS Console and log in with a user that has permission to create IAM users, policies, and roles such as the AWS accounts root user.
Open the IAM dashboard and click Policies in the left navigation pane.
Click the blue Create Policy button.
Click the JSON tab.
Clear all existing content in the IAM policy editor.
Copy and paste the sample IAM policy into the IAM policy editor.
Click the blue Next: Tags button.
Click the blue Next: Review button.
In the Name* field enter
aws-iampolicy-for-vault-authmethod
.Click the blue Create policy button.
Create AWS IAM user for HCP Vault Dedicated auth method
Open the IAM dashboard and click Users in the left navigation pane.
Click the blue Add users button.
In the User name* field enter
aws-iamuser-for-vault-authmethod
.Click the Access key - Programmatic access checkbox.
Click the blue Next: Permissions button.
Click the Attach existing policies directly button.
Search for, then click the checkbox for
aws-iampolicy-for-vault-authmethod
.Click the blue Next: Tags button.
Click the blue Next: Review button.
Click the blue Create user button.
On the Add user Success page, copy the Access key ID.
Return to the terminal and create an environment variable named
TMP_VAULT_ACCESS_KEY
.Replace
<ActualAccessKeyID>
the the Access key ID provided by the AWS Add user wizard.Return to AWS Console Add user Success page.
Click the Show link and copy the Secret access key.
Return to the terminal and create an environment variable named
TMP_VAULT_SECRET_KEY
.Replace
<ActualSecretAccessKey>
the the Secret access key provided by the AWS Add user wizard.Return to the AWS Console Add user Success page and click the Close button.
Create AWS role for HCP Vault Dedicated auth method
Open the IAM dashboard and click Roles in the left navigation pane.
Click the blue Create role button.
Click the AWS service radio button.
Click the EC2 radio button.
Click the blue Next button.
Do not attach a policy.
When you configure the AWS auth method, you specify an AWS IAM role that Vault will trust during the authentication process. There are no special permissions required by Vault beyond knowing which AWS IAM roles to trust.
Click the blue Next button.
In the Role name* field enter
aws-ec2role-for-vault-authmethod
.Click the blue Create role button.
Repeat the steps in the Create AWS Role for Vault Dedicated Auth Method section. Select Lambda as the service and enter
aws-lambdarole-for-vault-authmethod
for the Role name.
Configure Vault auth method
(Persona: admin)
Now that you have created the necessary resources in AWS, you can configure Vault Dedicated with the KV secret engine, a policy to allow read access to secrets, and the AWS auth method.
Return to the terminal and enable the KV v2 secret engine at the default path.
Store
api-key
with a value ofABCDEFG9876
at the pathkv/test/ec2
.Create a Vault policy named
vault-policy-for-aws-ec2role
that allows read at the pathkv/test/ec2
.Successful output example:
View the list of policies.
The
default
andhcp-root
policies are created with all new HCP Vault clusters.Enable the AWS auth method at the default path.
Type
vault auth list
to view the list of available auth methods.In addition to the
token
auth method that is enabled with all new Vault Clusters, you now have theaws
auth method enabled.Configure the
aws
auth method with access to your AWS account using the Access key ID and Secret Access Key previously created and stored atTMP_VAULT_ACCESS_KEY
andTMP_VAULT_SECRET_KEY
.Configure the
aws
auth method to trust the AWS IAM role previously created and attach thevault-policy-for-aws-ec2role
to the token provided by theaws
auth method. ReplaceYourAWSAccountID
with the actual account ID for your AWS account.Successful output example:
Thus far you have created several resources in AWS, and configured several settings to support the Vault AWS auth method. Take moment to review the command to better understand each part, and where they were configured.
If there are multiple AWS IAM roles that Vault should trust, you can create additional Vault roles by replacing the Vault role name. In the Create AWS Role for Vault Dedicated Auth Method section you created an additional AWS IAM role called called
aws-lambdarole-for-vault-authmethod
. To configure Vault to trust this role, in addition to theaws-ec2role-for-vault-authmethod
run:Successful output example:
View the roles created for the
aws
auth method.View the configuration of a specific role.
You have now configured the necessary resources in AWS and Vault Dedicated. In the next section, you will deploy an Amazon EC2 instance and test authentication with Vault.
Authenticate with HCP Vault Dedicated
(Persona: app)
This section demonstrates how to authenticate with Vault from an Amazon EC2 instance. To simulate an application running on your EC2 instance, you will install the Vault binary and authenticate to your Vault Dedicated instance.
Return to AWS Console and log in with a user that can create Amazon EC2 instances.
Open the EC2 dashboard and click Instances in the left navigation pane.
Click the orange Launch Instances button.
Launch an Amazon Linux 2 AMI with a family/size of t2.micro, in a public subnet or subnet you can SSH to, a security group that will allow SSH access, and a new or existing key pair you have access to. Do not attach a role at this time.
Note
If you used any sensitive information instead of the sample data provided in this tutorial you should encrypt the EBS volume.
SSH to the new EC2 instance. Replace
<mykey.pem>
and<public_ip_address>
with the values for your Amazon EC2 instance.Install
yum-utils
.Add the HashiCorp Linux repository
Install Vault.
Verify Vault was installed properly by executing
vault
.Return to the HCP Portal and click the Public link in the Quick actions page to copy the public URL for your Vault cluster.
Return to the SSH session for your Amazon EC2 instance.
In the terminal, set the
VAULT_ADDR
environment variable to the copied address.Set the
VAULT_NAMESPACE
environment variable toadmin
.Try to authenticate to Vault using the
aws
auth method.Recall that when you created the new Amazon EC2 instance you did not specify an IAM role. With no IAM role attached, Vault does not trust the EC2 instance.
Return the the AWS Console and access the EC2 >> Instances dashboard.
Click the check box for the EC2 instance.
Click the Actions pull down menu and navigate to Security >> Modify IAM role.
In the Choose IAM role pull down menu select aws-ec2role-for-vault-authmethod.
Click the orange Save button.
Return to the SSH session for your EC2 instance.
Try to authenticate to Vault using the
aws
auth method again.
You were able to successfully authenticate to Vault Dedicated by attaching the trusted AWS IAM role to your EC2 instance.
The output displays details about your token such as the token
, token_accessor
,
whether the token is renewable, and the token_policies
which you created
and associated to the Vault role.
Cleanup
To avoid any unnecessary charges to your AWS or HCP account, you should destroyed any resources that are no longer needed.
The following is a list of resources created in AWS for this tutorial
- EC2 instance for testing Vault authentication.
- AWS IAM roles
aws-ec2role-for-vault-authmethod
andaws-lambdarole-for-vault-authmethod
. - AWS IAM policy
aws-iampolicy-for-vault-authmethod
. - AWS IAM user
aws-iamuser-for-vault-authmethod
IAM user. - Any EC2 key pairs created specifically for this tutorial.
Next steps
You learned how to set up and configure the AWS auth method to allow an EC2 instance to authenticate with Vault Dedicated so that it can read secrets. Refer to the Vault documentation for the code example that uses the AWS auth method to authenticate with Vault.
In practice, you can reduce the amount of custom coding by delegating the authentication to Vault Agent. To learn more about Vault Agent, see the Vault Agent with AWS tutorial.