Playing Around with AWS-Vault for Fun & Profit

Ohav Almog writer profile image
By Ohav Almog

Updated March 5, 2024.

a diagram with the words playing around with aws - vault for fun and profits


AWS-Vault is an excellent open-source tool by 99Designs that enables developers to store AWS credentials in their machine keystore securely. After using it for a while at Jit, I decided to dig deeper into how it works and learned a lot along the way. In this article, I will summarize and simplify the information I learned to help others with their aws-vault adoption and lower the barrier to usage.

I will start with a basic explanation of AWS access keys, the Session Token Service, and its helpful API calls. Then I will show how aws-vault uses it to provide a secure way to access AWS resources, reducing the risk of exposing AWS credentials. In addition, I will represent a typical AWS account pattern, and again we'll see how aws-vault works perfectly with it.

AWS Access Keys

AWS makes it possible to create a set of access keys for a specific user (those are called aws_access_key_id and aws_secret_access_key). Together with these keys, it's possible to authenticate to AWS and perform actions on behalf of the user.

When using Python, for example, it's possible to use the boto3 library, which is the AWS Software Development Kit for Python, to authenticate to AWS:

With the AWS CLI, a configuration file can be used to store the access keys, which can then be used in the future to authenticate to AWS as follows:

With such a configuration file, long-lived credentials are stored in plain text on the user's machine. That's a security risk, as anyone with access to the device or the file can steal the credentials to perform actions on behalf of the user.

That is why developers and teams have moved on to more secure authentication practices, such as using session tokens.

Session Tokens

Sessions are a more secure approach, allowing the user to create valid temporary credentials for a specific period. Thus, if stolen, the keys might already be expired or will only limit the time the attacker can leverage them.

Below is a code example for how to generate temporary credentials using the AWS CLI:

But hang on a minute, as this example uses the long-lived credentials to authenticate to STS and get the temporary credentials. So, how could this possibly solve the problem of having unencrypted long-lived credentials on a user's machine?

That is where aws-vault comes in. But just before diving into aws-vault, let's first look at popular STS API calls.


STS, which stands for AWS Security Token Service, is a web service that enables you to request temporary, limited-privilege credentials for AWS IAM users or IAM roles. All temporary credentials consist of an access key ID, a secret access key, and a session token. These three credentials are then used to sign requests to any AWS service.


GetSessionToken is an API call that fetches temporary credentials for an IAM user. The simplest example is when a user uses its long-lived credentials to request temporary credentials (for any reason), where a widespread use case for this API call is when a user wants to authenticate to AWS using MFA. If MFA is used, the received credentials can be used to access APIs requiring MFA authentication.


Another method used to get temporary credentials, this time for an IAM role, is AssumeRole. Like GetSessionToken, it returns an access key, a secret access key, and a session token. It's possible to authenticate with an MFA device when assuming a role, and moreover, it's possible to protect an IAM role, requiring it to be assumed with MFA.

GetSessionToken and AssumeRole Comparison

AWS Vault

Now let's see where AWS Vault comes in to add a layer of security, preventing the storage of long-lived credentials in regular system files.

Copied from the project’s README:

AWS Vault stores IAM credentials in your operating system's secure keystore and then generates temporary credentials from those to expose to your shell and applications.

What this means for the end user is that instead of storing the credentials as clear text in a configuration file, they are stored in the OS's secure keystore. That is a safer approach, as the credentials are encrypted and can only be decrypted by the user who created them.

Not only does aws-vault store the credentials in the OS's secure keystore, but it also generates temporary credentials from those to expose to the shell and applications. That means that even if the credentials are stolen from the environment or an application, they are only valid for a specific period.

How Does It Work?

First, aws-vault stores the long-lived credentials in the OS's secure keystore. To do it, the `aws-vault add` command should be used:

For instance, in macOS, the credentials are stored encrypted in the Keychain Access app and can be viewed under 'Custom Keychains.'

Then, when requesting to use that profile, aws-vault will generate temporary credentials from the long-lived credentials using GetSessionToken. These temporary credentials are then exposed to the shell and applications using environment variables.

The session credentials are also stored in the same keychain to be used until they expire.

A typical user management pattern and recommended security practice is having a single AWS management account with only IAM users grouped into IAM groups (like developers and admins). Then, in addition to that account, there can be multiple AWS accounts (tagged dev, staging, and prod) with IAM roles that are assumed by the users in the developers and admins groups.

This pattern has many advantages, and the biggest of them all is resource isolation. Having each environment resource in a different AWS account makes it very unlikely that resources from a dev account will interact, interfere, or be included in the same list of resources in the production environment. In addition, in terms of security, this separation makes it harder to access prod resources or data (which are usually the most valuable) from a development or a staging account.

Not only that, but separating accounts also helps by viewing and monitoring cost and usage. With that, setting specific alerts and budgets for each environment is possible.

A developer in such an organization will probably have an AWS configuration file that looks like this:

This is where the beauty of aws-vault, together with this pattern, comes in. At first glance, it's possible to think that aws-vault would ask for a session token for each environment (as it's in a different profile and AWS account). But, if you remember the previous section, GetSessionToken requests credentials for an IAM user, not for an IAM role. And in this case, the developer only has one user, which exists in the management account.

Thus, the developer will store only a single pair of long-lived keys of the management account in the OS’ secure keystore, as can be seen in the following output:

AWS-Vault identifies the `source_profile` and `role_arn` attributes in the config file and understands it needs to assume each environment role with the same session from the management account's developer profile.

By leveraging the `source_profile` property in the `~/.aws/config` file, aws-vault will use the credentials from the `source_profile` to assume the role in the `role_arn` property. That allows aws-vault to ask for MFA only once and then use the temporary credentials to assume the roles in the other accounts.

Usually, these roles will have a condition requiring MFA to be assumed. So, why isn't the MFA being asked for each time the developer switches between environments? That's thanks to the fact that a session token that was created using MFA can be used to assume a role that requires MFA, and aws-vault is smart enough to know that both roles use the same MFA device.

With this pattern and configuration, developers can easily switch between different environments without a hassle:

Wrap Up

AWS-Vault is a powerful open-source tool to help add a layer of much-needed essential security for AWS users and developers. It is also built on top of the classic AWS config file, helping to avoid extra configuration and pains of usage.

I hope the examples provided will help you ramp up aws-vault more quickly and unleash the security capabilities this tool offers AWS users.