Manage federated workload identities with AWS IAM and Vault Enterprise
Note
Using AWS identity providers requires a Vault Enterprise license.
In this tutorial, you will learn how to configure and use AWS IAM OIDC identity providers to securely connect your Vault plugin.
Challenge
Plugins like the AWS Secrets engine require static security credentials. The user supplies the long lived and highly privileged AWS credentials in the plugin configuration.
Some organizations have strict requirements and must use of short lived, ephemeral credentials. For such organizations, this configuration is not acceptable.
Vault provides root credential rotations API, but these still require an initial set of credentials that are long lived and highly privileged. There is still a possibility of mishandling credentials during configuration.
Solution
Creating up a trust relationship between Vault and a cloud identity provider ensures no use of static credentials.
With an identity provider (IdP), you can manage your user identities in Vault and give these temporary user identities permissions to use AWS resources.
This tutorial instructs the user how to set up this trust relationship between Vault Enterprise and a Vault plugin. Identity Provider provides a method to securely configure a Vault plugin. Through an IAM role, Vault has access to specific capabilities and provides temporary security credentials to access AWS.
Personas
The intended audience of this tutorial is an Vault or AWS system administrator with privileged access and the ability to create AWS IAM Identity Providers.
Prerequisites
This tutorial requires an administrator access to an AWS account, Terraform, Vault CLI and the example Terraform configuration to create a demonstration environment.
- Vault Enterprise version 1.16 or later with premium license.
- Vault CLI
- AWS CLI
- Optionally - the Terraform CLI can be used to create and configure the AWS OIDC identity provider.
- Amazon Web Services test account. This tutorial requires the creation of new cloud resources and but should incur minimal costs associated with the deployment and management of these resources. Your IAM user will need permission to create AWS IAM resources.
- An AWS IAM user with
AWS_ACCESS_KEY_ID
andAWS_SECRET_ACCESS_KEY
is required to create an AWS IAM Provider.
- An AWS IAM user with
- Git
- ngrok installed and configured with an auth token.
Set up Ngrok
Ngrok is a "reverse proxy". The set up in this tutorial. exposes your local Vault instance to the internet. Your local computer becomes a locally hosted server, anyone can access it through a subdomain of ngrok.com.
In this tutorial, Ngrok provides a forwarding address that your local instance of Vault that will be accessable from AWS.
Note
Be aware that using ngrok creates a publicly routable address for the the Vault dev instance. For more secure production configurations, see the Additional discussion section below
Open a terminal to run ngrok.
Follow the official instructions to download ngrok for your OS distribution and set up a free account: https://ngrok.com/download
After setting up your account and obtaining an authtoken, configure ngrok with the auth token:
Start ngrok.
Example output:
Copy the ngrok forwarding address, Vault needs it.
Vault setup
Open a second terminal and export an environment variable with a valid Vault Enterprise license.
For the Vault to access the AWS Account, set AWS Access Key and Secret Access Key environment variables for the user you created for this tutorial.
Start a Vault dev server with the literal string
root
as the root token value, and temporarily setting theVAULT_API_ADDR
to the ngrok forwarding address.The Vault dev server defaults to running at
127.0.0.1:8200
, but ngrok provided a forwarding address that makes it available publically. AWS IAM OIDC identity provider can access Vault on your local machine.Insecure operation
Do not run a Vault dev server in production. This approach starts a Vault server with an in-memory database and runs in an insecure way.The Vault server is ready.
Confirm ngrok configuration
Open a third terminal.
In the new terminal, export an environment variable for the vault CLI to the ngrok forwarding address.
Setting the
VAULT_ADDDR
to the ngrok forwarding address forces the Vault CLI to use ngrok and forward to your local instance of Vault.Export an environment variable for the
vault
CLI to authenticate with the Vault server.To vaildate the correct set up of ngrok and Vault, check the status of Vault.
A similar response confirms that ngrok is forwarding to your Vault instance.
Obtain thumbprint for intermediate certificate authority
Ths tutorial requires the thumbprint from your for the top intermediate certificate authority that signed the certificate used by the Vault identity provider. Follow the directions at Obtain the thumbprint for an OpenID Connect identity provider and copy down the thumbprint for use in this tutorial.
Create AWS OIDC Identity Provider
This tutorial provides two methods to set up the AWS open identity provider, AWS CLI and Terraform.
In a new terminal window, clone the repository at learn-vault-plugin-wif.
Move into the cloned repository.
For the Vault CLI to access the AWS Account, set AWS Access Key and Secret Access Key environment variables.
Using the ngrok forwarding address copied earlier, update the code block below and paste in your terminal.
Note: No not include the "https://" when setting this environment variable.
Using the fingerprint created during the prerequisites, create another
TF_VAR
environment variable.
Determine the AWS account ID and set an environment variable.
Setting the
TOKEN_AUDIENCE
to make some of the future commands easier.Create an file with an AWS assume role policy in
/policy
directory.Create the AWS IAM role that the identity provider uses, then put the ARN in an environment variable.
Create a document with an inline policy.
Attach an inline policy to
vault-secrets-engine-wif
.Create the identity provider.
Example output:
Set up AWS secrets engine
Using the ngrok forwarding adddress copied earlier, update the code block below and paste in your terminal.
Note: No not include the "https://" when setting this environment variable.
In a new terminal, set some Vault environment variables.
Configure the identity provider issuer.
Enable the AWS Secrets engine.
Configures the AWS secrets engine with a role allowing access to the AWS identity provider and the audience intended.
The AWS IAM user
my-role
with a policy document with to get the current user information.Example output:
Get AWS credentials from Vault.
This creates a temporary user with
my-role
attached to it. The policy attached allows the IAM user to identify itself.Use the
access_key
andsecrets_key
above to reset your AWS environment variables.Use the AWS CLI to check which user you are using the credentials of.
Set up AWS authentication method
In addition to using an identity provider to configure the AWS secrets engine, the AWS authentication method can use an identity provider instead of static credentials for set up.
The last section included the IAM policies needed to set up the AWS authentication method, but the Vault configuration for the AWS authentication method is still required.
In the same terminal used in the last section, write the OIDC configuration.
Example output:
Enable AWS authentication.
Configure the AWS authentication to use the identity provider.
Example output:
Attach
dev-role-iam
to the token provided by the AWS auth method.Example output:
Open a new terminal, and set the Vault environment variables.
For the Vault CLI to access the AWS Account, set AWS Access Key and Secret Access Key environment variables.
Authenticate with Vault using
dev-role-iam
.You have authenticated with Vault using the AWS auth method from an identity provider.
The output displays details associated with the Vault role.
Clean up
Delete the identity provider and the role in your AWS account.
In your AWS account find any users whose name starts with
vault-token-my-role-
and delete them.Delete the cloned repository named
learn-vault-plugin-wif
.
In the terminal with Vault, press Ctrl + C to stop the running Vault dev server.
In the terminal with ngrok, press Ctrl + C to stop the running server.
Close all open terminals.
Additional discussion
This tutorial used Ngrok as a reverse proxy to make the Vault dev instance publicly routable. However, this is undesirable for most production use-cases.
For production, we recommend using a proxy to enable access to only the API endpoints strictly necessary. In the case of workload identity federation, these are:
${VAULT_ADDR}/v1/${VAULT_NAMESPACE}/identity/oidc/plugins/.well-known/openid-configuration
${VAULT_ADDR}/v1/${VAULT_NAMESPACE}/identity/oidc/plugins/.well-known/keys
- This URL can be found in the
jwks_uri
field of the response from theopenid-configuration
API endpoint
- This URL can be found in the
Substitute in appropriate values for your VAULT_ADDR
and VAULT_NAMESPACE
.
Be sure to also update the issuer in identity/oidc/config
accordingly.
Where possible, consider restricting access to the proxy to only AWS.
Next steps
Many organizations have rules against the use of static credentials, and therefore can not use Vault plugins.
In this tutorial, you learned how to set up AWS OIDC identity provider and avoided any use of static credentials in the process. This was possible through a trust relationship between Vault and AWS OIDC identity provider. Vault will manage the identities on the cloud provider and give these temporary user identities permission to use AWS resources.