April 15, 2023

aws-vault – Secure Access To Multiple AWS accounts

Share this

By Andrei Maksimov

February 4, 2021

aws-vault, awscli, iam, security, sts

Enjoy what I do? Consider buying me a coffee ☕️

  • Home
  • AWS
  • aws-vault – Secure Access To Multiple AWS accounts

Protecting your AWS account access keys is essential for safeguarding your organization’s cloud infrastructure. However, managing multiple accounts can be difficult and time-consuming. aws-vault provides a secure way to store and manage access keys for multiple AWS accounts.

With aws-vault, you can quickly and easily access the accounts you need without having to remember multiple passwords or AWS access credentials. This blog post will show you how to securely use aws-vault to access multiple AWS accounts. We will also provide some benefits of using aws-vault for managing account access.

What is AWS-vault?

The aws-vault is a tool that allows you to store and manage your AWS credentials securely. With aws-vault, you can easily create an individual profile for each AWS account and switch between them. You can also specify which profile to use when running AWS CLI commands so that you don’t have to remember which account each profile is associated with. To use aws-vault, you’ll need to install it on your computer (you can find instructions below).

Once installed, you can create a new profile by running the aws-vault add command. This will prompt you for your AWS credentials, encrypt them and store them in a safe location. You can run the aws-vault exec command to switch to a different profile. This will prompt you for the password for the profile you want to switch to. The aws-vault is a powerful tool to help you securely manage your AWS credentials.

The aws-vault tool uses Amazon’s STS service to generate temporary credentials via the GetSessionToken or AssumeRole API calls. These temporary credentials expire in a short period of time, so the risk of leaking credentials is reduced.

The problem

I always was not a big fan of ~/.aws/credentials file, because every time I came to a new customer, I had to open this file for the edit to add a new AWS Access Key and AWS Secret Access Key provided by the customer. As a result, I constantly had a feeling that I displayed all my existing credentials to all security cameras in the office. God bless the inventor of the privacy screens!

The second problem with credentials is that they need to be renewed occasionally. The more accounts you have, the more effort you spend on credentials rotation.

And the third problem – is assuming roles in terminal sessions and working in several different environments simultaneously.


As a solution for the first two problems, not too far ago, I started using:

As a solution for the last two problems, I found that the following tooling stack suits most of my needs:

  • zsh and oh-my-zsh – terminal.
  • zsh-aws-vault – AWS environment highlighting for the terminal session.

Managing AWS credentials

Here’s a quick getting started guide.


I’m assuming here that you already have zsh and oh-my-zsh installed.

Let’s install aws-vault. Here’s the complete list of installation steps for the most available platforms.

We’ll be doing everything for OS X (macOS):

# aws-vault install on OS X
brew cask install aws-vault

Choosing aws-vault backend

The aws-vault supports several backends to store your credentials:

I prefer an encrypted file because it is easy to back it up to the S3 bucket but you may configure the operating system’s secure Keystore if you’d like.

If you decide to repeat my setup, you need to add the following variable to your ~/.zshrc:

export AWS_VAULT_BACKEND="file"

Moving credentials to aws-vault

Now open your ~/.aws/credentials file. For every existing profile, add credentials to aws-vault.

cat ~/.aws/credentials
aws-vault add profile_1
aws-vault add profile_2

Now, aws-vault has AWS_VAULT_FILE_PASSPHRASE variable, which can be used to stop aws-vault from asking for your vault password repeatedly. There’re two ways to use it:

Not secure way

Add the following variable to your ~/.zshrc or ~/.bashrc file, to prevent aws-vault from asking for your password every single time:

export AWS_VAULT_FILE_PASSPHRASE="my_strong_password"

Secure way

Instead of storing AWS_VAULT_FILE_PASSPHRASE variable in .*rc files, you may create AWS Systems Manager Parameter Store SecureString parameter, which contains your aws-vault password:

aws ssm put-parameter \
  --name '/laptop/aws-vault/password' \
  --description 'aws-vault password on my laptop' \
  --value 'my_super_secret_password' \
  --type SecureString

Let’s create a wrapper script, which will call aws-vault call aws-vault and set up AWS_VAULT_FILE_PASSPHRASE with a necessary value from AWS Systems Manager Parameter Store:

mkdir -p $HOME/bin
cat > $HOME/bin/call-aws-vault.sh <<- EOF
#!/usr/bin/env bash
export PROFILE=$1
export AWS_VAULT_FILE_PASSPHRASE=$(aws ssm get-parameters --profile default --names '/laptop/aws-vault/password' --with-decryption --query 'Parameters[0].Value' --output text)
aws-vault exec -j $PROFILE
chmod +x $HOME/bin/call-aws-vault.sh

Now you may use this wrapper at ~/.aws/config like that:

[profile my_new_profile]
credential_process = ~/bin/call-aws-vault.sh my_new_profile

You may rename ~/.aws/credentials and, later on, completely delete them as soon as you test everything.

Switching AWS Profiles

To list all your AWS profiles, just type:

aws-vault list

Great, now you can easily switch your environment and see where you’re working:

aws-vault exec --duration 8h default

Here’s what it finally looks like:


You can now use AWS CLI tools, Terraform, AWS CDK, and other tools interacting with AWS services using multiple aws-vault shell sessions.

Role-based approach

We just moved all our AWS credentials to a secure vault and configured our terminal to display our current aws-vault session. Now it’s time to discuss how we can improve the solution.

Multi-account organization

One of the best practices for organizing AWS users’ access to different AWS accounts – is managing all IAM users in one AWS account and providing access to other accounts by allowing them to consume roles (sts:AssumeRole API call) from that account.

Here’s a typical AWS Organization example:


AWS provided a great explanation of How to Use a Single IAM User to Easily Access All Your Accounts by Using the AWS CLI in their blog post, describing the role-consuming process and awscli configuration. I’ll not copy-paste them. Instead, we’ll concentrate on the aws-vault configuration to do something similar, but without ~/.aws/credentials file.

Assuming you already have all the necessary grants and permissions between your accounts. If not, here’s a great article on that topic – Tutorial: Delegate Access Across AWS Accounts Using IAM Roles.

Default profile setup

You should already have your default profile set up. Probably, it looks something like that:

[profile default]
region = us-east-1

Let’s configure aws-vault as a credential source for our default profile:

[profile default]
region = us-east-1
credential_process = /usr/local/bin/aws-vault exec -j default

Now, if you grant permissions to your user or role from the default profile to assume an AWS role from another account, you’ll be able to specify new profiles configuration like that:

[profile default]
region = us-east-1
credential_process = /usr/local/bin/aws-vault exec -j default
mfa_serial = arn:aws:iam:::mfa/admin
[profile default]
region = us-east-1
credential_process = /usr/local/bin/aws-vault exec -j default
mfa_serial = arn:aws:iam:::mfa/admin
[profile account_1_role_admin]
region = us-east-1
role_arn = arn:aws:iam:::role/admin
source_profile = default
[profile account_2_role_qa]
region = us-east-1
role_arn = arn:aws:iam:::role/qa
source_profile = default

source_profile configuration option will tell awscli which account to use to grab a role for any given profile.



The fastest way to test that you’re able to assume the role is to call:

aws sts get-caller-identify

You should see something similar for your default profile:

    "Account": "01234567890",
    "Arn": "arn:aws:iam::01234567890:user/admin"

To test any other profile, call:

aws sts get-caller-identity --profile account_1_role_admin

You should see output similar to the following:

    "UserId": "AROALKJHGFGDFV3IR2VSI:botocore-session-1584897134",
    "Account": "012345678901",
    "Arn": "arn:aws:sts::012345678901:assumed-role/admin/botocore-session-1584897134"

Assuming the AWS account role

To assume the role from any AWS account which you have in your aws-vault, execute the following commands:

aws-vault ls
aws-vault exec --duration 8h default

Here, we’re assuming a role associated with the default profile for 8 hours.

AWS Single Sign-On (AWS SSO) support

AWS Single Sign-On, commonly known as AWS SSO, is a streamlined identity management service that helps simplify access to multiple applications across the Amazon Web Services (AWS) platform. Designed specifically to work with aws-vault, a popular tool for securely managing credentials on the AWS platform, AWS SSO provides an easy way to remain secure while accessing your critical cloud resources.

With aws-vault SSO support and the credential information defined by AWS SSO CLI v2, you can quickly gain access to your cloud environments without compromising security. The aws-vault SSO support allows you to store AWS credentials in the secure vault and use AWS SSO for those environments where it is required.

Passwordless AWS Web console login

As a small bonus to those of you, who came to an end, here’s how to login to the AWS web console for every given profile:

aws-vault ls
aws-vault login --duration 8h default

How to log out from the aws-vault session

When you are finished working with aws-vault, it is important to log out of any active sessions. This will ensure your information is kept secure and limit the risk of unauthorized access to your aws-vault protected account. There’s no aws-vault logout command, and the assumed by aws-vault AWS STS session will keep active till its timeout. So, you need to exit the aws-vault shell session by pressing Ctrl+D.


Using zshaws-vault, and AWS sts:AssumeRole feature together can significantly simplify and make more secure management of multiple AWS accounts and their credentials.

If you like the article, please, feel free to spread it to the world. And, of course, if you have any questions, suggestions, or comments, feel free to provide them in the comments section below.

Andrei Maksimov

I’m a passionate Cloud Infrastructure Architect with more than 20 years of experience in IT. In addition to the tech, I'm covering Personal Finance topics at https://amaksimov.com.

Any of my posts represent my personal experience and opinion about the topic.

{"email":"Email address invalid","url":"Website address invalid","required":"Required field missing"}

Related Posts

Comprehensive Guide to Install Boto3 Python
Python Boto3 Session: A Comprehensive Guide

Andrei Maksimov


Ultimate Guide to Amazon Bedrock

Ultimate Guide to Amazon Bedrock
AWS Proxies: Enhancing Data Collection and Security

Subscribe now to get the latest updates!