aws-vault — Securely Store and Access AWS Credentials

Introduction

aws-vault is a tool for securely storing and accessing AWS credentials in development environments. Instead of keeping long-lived access keys in plaintext files like ~/.aws/credentials, aws-vault stores them in your OS keychain (macOS Keychain, Windows Credential Manager, or Linux secret-service) and generates temporary STS credentials on the fly.

What aws-vault Does

• Stores IAM access keys in the operating system's native secure keystore
• Generates temporary session credentials using AWS STS AssumeRole or GetSessionToken
• Injects credentials into shell sessions, subprocesses, or environment variables
• Supports MFA token prompting during credential generation
• Provides a local credential server for tools that don't support environment variables

Architecture Overview

aws-vault reads your ~/.aws/config to understand profiles, role chains, and MFA requirements. When you run aws-vault exec profile -- command, it retrieves the master credentials from the OS keychain, calls STS to generate short-lived session tokens, and passes them as environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN) to the subprocess. A built-in credential server can also serve credentials via the EC2 instance metadata endpoint for compatibility with SDKs that expect that interface.

Self-Hosting & Configuration

• Install via Homebrew (macOS/Linux), Chocolatey (Windows), or download the binary from GitHub releases
• Run aws-vault add <profile> to store access keys in the keychain
• Configure role_arn and source_profile in ~/.aws/config for cross-account access
• Set mfa_serial in the config to enable MFA prompting
• Use --duration flag to control session credential lifetime (default: 1 hour)

Key Features

• Never stores credentials in plaintext on disk
• Cross-platform: macOS Keychain, Windows Credential Manager, GNOME Keyring, KWallet
• Supports IAM role chaining and cross-account assume-role workflows
• MFA integration with automatic prompting
• Login command generates a pre-signed AWS Console URL for browser-based access

Comparison with Similar Tools

• ~/.aws/credentials — The default plaintext file; aws-vault replaces it with keychain-backed storage
• aws-sso — AWS's built-in SSO credential flow; aws-vault predates it and supports non-SSO setups
• saml2aws — Focused on SAML-based federation; aws-vault handles IAM key + STS workflows
• granted — Newer alternative with a similar approach plus a browser-based SSO flow

FAQ

Q: Can I use aws-vault with AWS SSO? A: Yes. Configure SSO profiles in ~/.aws/config and aws-vault will handle the SSO login flow and credential caching.

Q: Where are my credentials actually stored? A: In your OS keychain (macOS Keychain, Windows Credential Manager, or a Linux keyring like GNOME Keyring). Never in plaintext files.

Q: Does it work with Terraform and other IaC tools? A: Yes. Use aws-vault exec profile -- terraform plan to inject credentials into any subprocess.

Q: What license does aws-vault use? A: MIT License.

Sources

• https://github.com/99designs/aws-vault
• https://99designs.com.au/blog/engineering/aws-vault