aws-vault

README

AWS Vault

AWS Vault is a tool to securely store and access AWS credentials in a development environment.

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. It's designed to be complementary to the AWS CLI tools, and is aware of your profiles and configuration in ~/.aws/config.

Check out the announcement blog post for more details.

Installing

You can install AWS Vault:

• by downloading the latest release
• on macOS with Homebrew Cask: brew cask install aws-vault
• on Windows with Chocolatey: choco install aws-vault
• on Windows with Scoop: scoop install aws-vault
• on Linux with Homebrew on Linux: brew install aws-vault
• on Arch Linux with the AUR: yay -S aws-vault
• on FreeBSD with pkg install aws-vault
• with Nix: nix-env -i aws-vault

Vaulting Backends

The supported vaulting backends are:

• macOS Keychain
• Windows Credential Manager
• Secret Service (Gnome Keyring, KWallet)
• KWallet
• Pass
• Encrypted file

Use the --backend flag or AWS_VAULT_BACKEND environment variable to specify.

Basic Usage

# Store AWS credentials for the "jonsmith" profile
$ aws-vault add jonsmith
Enter Access Key Id: ABDCDEFDASDASF
Enter Secret Key: %%%

# Execute a command (using temporary credentials)
$ aws-vault exec jonsmith -- aws s3 ls
bucket_1
bucket_2

# open a browser window and login to the AWS Console
$ aws-vault login jonsmith

# List credentials
$ aws-vault list
Profile                  Credentials              Sessions
=======                  ===========              ========
jonsmith                 jonsmith                 -

See the USAGE document for more help and tips.

How it works

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

AWS Vault then exposes the temporary credentials to the sub-process in one of two ways

1. Environment variables are written to the sub-process. Notice in the below example how the AWS credentials get written out

   $ aws-vault exec jonsmith -- env | grep AWS
   AWS_VAULT=jonsmith
   AWS_DEFAULT_REGION=us-east-1
   AWS_REGION=us-east-1
   AWS_ACCESS_KEY_ID=%%%
   AWS_SECRET_ACCESS_KEY=%%%
   AWS_SESSION_TOKEN=%%%
   AWS_SECURITY_TOKEN=%%%
   AWS_SESSION_EXPIRATION=2020-04-16T11:16:27Z
   

2. Local EC2 Instance Metadata server is started. This approach has the advantage that anything that uses Amazon's SDKs will automatically refresh credentials as needed, so session times can be as short as possible. The downside is that only one can run per host and because it binds to 169.254.169.254:80, your sudo password is required.

The default is to use environment variables, but you can opt-in to the local instance metadata server with the --server flag on the exec command.

Roles and MFA

Best-practice is to create Roles to delegate permissions. For security, you should also require that users provide a one-time key generated from a multi-factor authentication (MFA) device.

First you'll need to create the users and roles in IAM, as well as setup an MFA device. You can then set up IAM roles to enforce MFA.

Here's an example configuration using roles and MFA:

[default]
region = us-east-1

[profile jonsmith]
mfa_serial = arn:aws:iam::111111111111:mfa/jonsmith

[profile foo-readonly]
source_profile = jonsmith
role_arn = arn:aws:iam::22222222222:role/ReadOnly

[profile foo-admin]
source_profile = jonsmith
role_arn = arn:aws:iam::22222222222:role/Administrator
mfa_serial = arn:aws:iam::111111111111:mfa/jonsmith

[profile bar-role1]
source_profile = jonsmith
role_arn = arn:aws:iam::333333333333:role/Role1
mfa_serial = arn:aws:iam::111111111111:mfa/jonsmith

[profile bar-role2]
source_profile = bar-role1
role_arn = arn:aws:iam::333333333333:role/Role2
mfa_serial = arn:aws:iam::111111111111:mfa/jonsmith

Here's what you can expect from aws-vault

Command	Credentials	Cached	MFA
aws-vault exec jonsmith --no-session	Long-term credentials	No	No
aws-vault exec jonsmith	session-token	session-token	Yes
aws-vault exec foo-readonly	role	No	No
aws-vault exec foo-admin	session-token + role	session-token	Yes
aws-vault exec foo-admin --duration=2h	role	role	Yes
aws-vault exec bar-role2	session-token + role + role	session-token	Yes
aws-vault exec bar-role2 --no-session	role + role	role	Yes

AWS SSO integration

If your organization uses AWS Single Sign-On (AWS SSO), AWS Vault provides a method for using the credential information defined by AWS SSO CLI v2. The integration supports caching of the temporary credentials for each profile, and will automatically refresh the credentials using an SSO Access Token (with a life-time that is specific to your integration). For more information about AWS SSO, please see this blog post from AWS.

The AWS CLI v2 provides a wizard to generate the required profile configuration, but it's also possible to directly input this information in your ~/.aws/config file.

Here's an example configuration using AWS SSO:

[profile Administrator-123456789012]
sso_start_url=https://aws-sso-portal.awsapps.com/start
sso_region=eu-west-1
sso_account_id=123456789012
sso_role_name=Administrator

This profile should work expected with AWS Vault commands, e.g. exec and login. See Basic Usage for more information.

Development

The macOS release builds are code-signed to avoid extra prompts in Keychain. You can verify this with:

$ codesign --verify --verbose $(which aws-vault)

If you are developing or compiling the aws-vault binary yourself, you can generate a self-signed certificate by accessing Keychain Access > Certificate Assistant > Create Certificate > Code Signing Certificate. You can then sign your binary with:

$ go build .
$ codesign --sign "Name of my certificate" ./aws-vault

References and Inspiration

• https://github.com/pda/aws-keychain
• https://docs.aws.amazon.com/IAM/latest/UserGuide/MFAProtectedAPI.html
• https://docs.aws.amazon.com/IAM/latest/UserGuide/IAMBestPractices.html#create-iam-users
• https://github.com/makethunder/awsudo
• https://github.com/AdRoll/hologram
• https://github.com/realestate-com-au/credulous
• https://github.com/dump247/aws-mock-metadata
• https://boto.readthedocs.org/en/latest/boto_config_tut.html