aws-vault

README

AWS Vault

Securely store and access credentials for AWS. 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.

Currently the supported backends are:

• macOS Keychain
• KWallet
• freedesktop.org Secret Service
• Encrypted file

Check out the announcement blog post for more details.

Installing

Download the latest release.

On macOS, you may instead use homebrew cask to install:

$ brew cask install aws-vault

The macOS release is code-signed, and you can verify this with codesign:

$ codesign -dvv $(which aws-vault) 2>&1 | grep Authority
Authority=Developer ID Application: 99designs Inc (NRM9HVJ62Z)
Authority=Developer ID Certification Authority
Authority=Apple Root CA

Usage

See the USAGE document for more help and tips.

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

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

# Inspect the environment
$ aws-vault exec home -- env | grep AWS
AWS_VAULT=work
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=%%%

Backends

You can choose among different pluggable secret storage backends. By default, Linux uses an encrypted file. You can use your system keyring by choosing the secret-service backend which abstracts over Gnome/KDE.

See the USAGE document for more help and tips.

Security

Notice in the above environment how a session token gets written out. This is because 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.

The credentials are exposed to the subprocess in one of two ways:

• Environment variables are written to the sub-process.

• 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.

MFA Tokens

If you have an MFA device attached to your account, the STS service will generate session tokens that are invalid unless you provide an MFA code. To enable MFA for a profile, specify the MFA serial in ~/.aws/config:

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

You can retrieve the MFA's serial (ARN) in the web console, or you can usually derive it pretty easily using the format arn:aws:iam::[account-id]:mfa/[your-iam-username].

Note that if you have an account with an MFA associated, but you don't provide the IAM, you are unable to call IAM services, even if you have the correct permissions to do so.

Assuming Roles

Best-practice is to have a read-only account that you use on a day-to-day basis, and then use IAM roles to assume temporary admin privileges along with an MFA.

First you'll need to setup an MFA token in the AWS Console and create a role with admin access.

Edit your ~/.aws/config to add the role_arn and MFA serial number into a new profile:

[profile read-only]
region=us-east-1

[profile admin]
mfa_serial = arn:aws:iam::123456789012:mfa/jonsmith
source_profile = read-only
role_arn = arn:aws:iam::123456789012:role/admin-access

Then when you use the admin profile, aws-vault will look in the read-only profile's keychain for credentials and then use those credentials to assume the admin role. This assumed role is stored as a short duration session in your keychain so you will only have to enter MFA once per session.

Note: When assuming roles, mfa_serial will not be inherited from the profile designated in source_profile -- you must include a reference to mfa_serial in every profile you wish to use it with.

Rotating Credentials

Regularly rotating your access keys is a critical part of credential management. You can do this with the aws-vault rotate <profile> command as often as you like.

The minimal IAM policy required to rotate your own credentials is:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iam:CreateAccessKey",
                "iam:DeleteAccessKey",
                "iam:GetUser"
            ],
            "Resource": [
                "arn:aws:iam::*:user/${aws:username}"
            ]
        }
    ]
}

Removing stored sessions

If you want to remove sessions managed by aws-vault before they expire, you can do this with the --session-only flag.

aws-vault remove <profile> --sessions-only

Development

Developed with golang, to install run:

go get github.com/99designs/aws-vault

Self-signing your binary

Binaries that call Keychain need to be signed, otherwise they always show the "allow access" prompt. Releases are signed by 99designs certificates, but if you are actively developing and want to mimic the behaviour of a signed release you can generate a self-signed code signing certificate.

Check out Apple's guide on it here, or find it in Keychain Access > Certificate Assistant > Create Certificate > Code Signing Certificate.

You can then sign your binary like this:

make build
codesign -s "Name of my certificate" ./aws-vault

References and Inspiration

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