Chapter 10
9 min read

AWS Vault: Tutorial, Best Practices & Limitations

Learn how to securely manage and store your Amazon Web Services credentials in development environments using the open-source tool AWS Vault.

Feb 11, 2024
AWS Vault: Tutorial, Best Practices & Limitations

AWS Vault: Tutorial, Best Practices & Limitations

Using AWS Vault limits the risk of malicious applications or dependencies gaining unauthorized access to your AWS account through engineering credentials. In addition, the likelihood of accidentally storing IAM credentials in version control (GitHub, Bitbucket, etc.) reduces significantly.

Summary of Key AWS Vault concepts

The table below summarizes the key concepts we cover in this article.

AWS credentials overview

To access the vast majority of the services provided by AWS, you must supply IAM credentials. In the simplest case, these credentials consist of an Access Key, which allows AWS to associate these credentials with an AWS account, and a Secret Key, which acts like a password for the Access Key.

Applications that need access to AWS can have these IAM credentials exposed to them in a lot of ways - but the two most common are:

  1. Environment variables sourced from a .env file somewhere on the filesystem or
  2. A file managed by the AWS CLI located at ~/.aws/config.

In both cases, the credentials are stored in plaintext, and in the case of the AWS CLI, they are stored in a well-known location. Because these credentials are stored in plaintext, the risk of exposure or theft of these valuable credentials is higher than if they were encrypted.

Because these IAM credentials give an attacker direct access to your AWS account and company data, it’s crucial that you securely store, manage, and rotate them on a schedule. You must take precautions to expose credentials only to applications and individuals needing them. Keep them out of version control repositories like GitHub that are not designed to store credentials. This can be challenging to get right for development environments used by engineers who may not be security experts.

This is where a tool like AWS Vault can help. With AWS Vault in use, that same Access Key and Secret Key are encrypted in the OS Keychain. When an application needs credentials, AWS Vault uses an AWS service called STS to create credentials that only last for 60 minutes by default and supplies those credentials instead of your valuable IAM credentials. If these temporary credentials are exposed or stolen, an attacker’s likelihood of using them reduces significantly. Administrators can also set up a multifactor authentication requirement for additional security.

How to set up and use AWS Vault

AWS Vault is written in Go and packaged as a standalone binary for Linux, macOS, and Windows. You can download the latest release from Github or use the provided instructions for your package manager. If downloading directly from GitHub, remember to make the binary executable. For example, on amd64 architecture on Linux:

1$ wget
4Saving to: ‘aws-vault-linux-amd64’
6$ chmod +x aws-vault-linux-amd64
1$ sudo mv aws-vault-linux-amd64 /usr/local/bin/aws-vault

Check out this Stack Exchange answer for more information on why you might choose to put a non-core program executable in /usr/local/bin on Linux.

In the rest of this article, the code examples assume the executable is named aws-vault and available to your chosen shell. Go ahead and validate that now by printing the version you have installed:

1$ aws-vault --version

Getting your AWS IAM credentials

If you already have an Access Key and Secret Key you’d like to use with AWS Vault, you can skip this section and use them in the next with your first profile. Otherwise, you have some options.

Most AWS users will create IAM credentials for themselves in the AWS Management Console using a link labeled Security Credentials, available in the right-hand drop-down menu underneath your username:

Once there, scroll about halfway down the page to find a button labeled Create Access Key, at the top of a section labeled Access Keys:

The above example has an existing key, but your section will likely be empty if this is a new AWS account or your first access key. The console sends you through a multi-step workflow for creating your keys. The first step is a page reminding you of the weighty responsibility of keeping the key safe.

Your selection here doesn’t make any material difference in the created key. The linked document on best practices is full of good points, but for now, I recommend you select Other, click Next, and move on.

Your next stop is a page where you add a Description tag to the key you’re about to generate. The tag will help you later when trying to remember what this key is for, where it might be used, and what could break if you delete it. We recommend naming it after the development environment where you plan to use it. Click Create Access Key after coming up with the tag value. If needed, this is a real AWS resource tag that you can query later through the API.

On the next page, you will see the Access Key and Secret Key you created. Copy and paste these somewhere safe, using both icons with the two squares, and have them handy for the next section where you will add them to AWS Vault.

Creating your first profile

It’s time to create your first profile. Enter your Access Key and Secret Key as prompted.

1$ aws-vault add first-profile
3Enter Access Key ID: AKIA****************
4Enter Secret Access Key: ****************************************
5Added credentials to profile "first-profile" in vault

Now, try it out for a spin. Behind the scenes, this command pulls your keys from the profile, authenticates to AWS, and creates temporary credentials that are injected into the environment and passed to the AWS CLI. If you don’t have the AWS CLI, installation instructions can be found here. The get-caller-identity command returns information about the current user. You can think of it as the AWS equivalent of whoami.

1$ aws-vault exec first-profile -- aws sts get-caller-identity
4    "UserId": "AIDA****************",
5    "Account": "************",
6    "Arn": "arn:aws:iam::************:user/cam-admin"

You might notice the AIDA prefix on the user ID. It is the value proposition of AWS Vault in action - it has created a temporary key with the permissions and account of the key stored in the profile you just created, but the key is useless in a matter of minutes and doesn’t expose any information about your AWS account or give any access after expiry.

Now that your first profile is working, you can start using AWS Vault in your day-to-day development work. Supplying a different command to aws-vault exec will do the trick. Here’s a NodeJS example:

1$ aws-vault exec first-profile -- npm start

Any software project that uses the AWS SDK or looks for the same environment variables as the official SDK should work without any code changes.

If you prefer to have an interactive terminal session to work with instead of typing that whole prefix for every command, try exec without a command:

1$ aws-vault exec first-profile
3Starting subshell /bin/bash, use `exit` to exit the subshell
5$ npm start

Limitations of AWS Vault key management

AWS Vault is a significant upgrade in your handling of cloud credentials in development environments and protect against malicious dependencies and other threats. Still, there are limitations that you should consider before deployment.

As a part of any secret management strategy, it’s essential to use purpose-built tools to handle the whole lifecycle of secrets, from creation through rotation and expiry. AWS Vault isn’t a secret management tool in this sense. It only helps you limit direct exposure of IAM credentials and leaves essential details, like creating those credentials in the first place and ensuring rotation and expiry, to end users.

As the project’s name might imply, AWS Vault doesn’t help you secure credentials to other public clouds. Projects that span more than one cloud provider can still be vulnerable.

AWS Vault is also expressly designed for developer machines and other environments engineers use in day-to-day work. OS keychains typically require a password prompt or similar interactive authentication measures. Their use doesn’t translate easily to credentials for staging or production environments. Also, AWS Vault doesn’t automatically rotate the long-lived credentials that it encrypts in the OS keychain and leaves this task to individual developers.

In addition, most applications have many secrets that need to be protected, like database credentials, API keys for external systems, or client authentication keys. AWS Vault is only a solution for AWS IAM credentials.

Even for the credentials it is designed to handle, AWS Vault relies on the access control mechanisms built into AWS to manage different roles and access levels. Configuring this correctly is possible, but with the official list of best practices for IAM sitting at 15+ items, it can be a complex task.

For enterprise users, audit logging of developer activity may be a requirement. Using AWS CloudTrail for this purpose involves significant additional complexity and cost and presents security risks if best practices are not followed.


AWS Vault is a significant step up from sharing plaintext and long-lived IAM credentials between developers. It can protect your cloud environment in the case of a supply-chain attack on your application’s credentials, among other threats. However, as many software development teams move towards deploying their products on multiple cloud providers and need to work with secrets beyond AWS IAM credentials, there are problems with developer secret management that AWS Vault can’t address by itself.

Addressing those limitations, like access control, audit logging, and automatic secret rotation, takes significant engineering time and expertise to get right. Check out Doppler for a product with built-in access control, logging, and automatic rotation. You can securely manage all types of credentials without spending engineer hours to build them yourself.