aws-mfa-session

A command line utility to generate temporary AWS credentials using virtual MFA devices. Credentials can be exported to environment variables, used in a new shell session, or saved to AWS credentials file.

Features

• Supports MFA authentication with virtual MFA devices (hardware MFA devices supported, but FIDO security keys are not supported)
• Interactive MFA code prompting - if no code is provided, you'll be prompted to enter it
• Select any profile from AWS credentials file
• Automatic MFA device selection - reads mfa_serial from AWS profile configuration (~/.aws/config or ~/.aws/credentials), with fallback to automatic device detection
• Generate temporary credentials using AWS STS
• Enhanced error reporting with detailed error messages
• Atomic credentials file updates - prevents file corruption during concurrent access
• Multiple output options:
  • Export as environment variables
  • Launch new shell with credentials
  • Update/create profiles in AWS credentials file

Release page distributions

GitHub Release page provides binaries for:

• Windows
• Linux
• macOS

Configuration

MFA Device Configuration

The tool can automatically select your MFA device by reading the mfa_serial setting from your AWS profile configuration. This eliminates the need to specify the --arn parameter each time.

Adding mfa_serial to ~/.aws/config (Recommended)

[profile dev]
region = us-west-2
mfa_serial = arn:aws:iam::123456789012:mfa/username

[profile prod]
region = eu-west-1
mfa_serial = arn:aws:iam::123456789012:mfa/prod-user

Adding mfa_serial to ~/.aws/credentials (Alternative)

[default]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
mfa_serial = arn:aws:iam::123456789012:mfa/username

[dev]
aws_access_key_id = AKIAI44QH8DHBEXAMPLE
aws_secret_access_key = je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY
mfa_serial = GAHT12345678

Supported mfa_serial formats:

• Virtual MFA devices: arn:aws:iam::123456789012:mfa/username
• Hardware MFA devices: GAHT12345678 (serial number)

Precedence: Config file (/.aws/config) takes precedence over credentials file (/.aws/credentials).

Examples

Interactive MFA Code Entry

If you don't provide the --code argument, you'll be prompted to enter it interactively:

# Interactive mode - you'll be prompted for the MFA code
aws-mfa-session --export
Enter MFA code: 123456

Automatic MFA Device Selection

When you have mfa_serial configured in your AWS profile, the tool automatically selects the MFA device:

# Uses mfa_serial from the default profile configuration
aws-mfa-session --code 123456 --export

# Uses mfa_serial from the dev profile configuration  
aws-mfa-session --profile dev --code 123456 --export

Basic Usage

Generate session credentials with default profile, and print the credentials as exported environment variables:

aws-mfa-session --code 123456 --export

Could be used to inject variables into the current shell:

eval $(aws-mfa-session --code 464899 --export)

Advanced Usage

Generate session credentials with default profile and MFA ARN:

aws-mfa-session --arn arn:aws:iam::012345678910:mfa/username --code 123456 --export

Generate session credentials with default profile and non-default region:

aws-mfa-session --region us-east-2 --code 123456 --export

Generate session credentials with default profile, and run a new shell with exported environment variables:

aws-mfa-session --code 123456 --shell

Generate session credentials with default profile, and create or update a new profile:

aws-mfa-session --update-profile mfa-session --code 123456

Generate session credentials with defined profile, and create or update a new profile:

aws-mfa-session --profile dev --update-profile mfa-session --code 123456

Generate session credentials with defined profile and non-default credential file, and create or update a new profile:

aws-mfa-session --credentials-file ~/.aws/credentials2 --profile dev --update-profile mfa-session --code 123456

Generate session credentials with custom duration (2 hours):

aws-mfa-session --code 123456 --duration 7200 --export

Generate session credentials with maximum duration (just under 36 hours):

aws-mfa-session --code 123456 --duration 129599 --export

Using with AWS Assume Role

This tool works well with AWS assume role profiles. A common pattern is to use MFA-authenticated credentials as the source for assuming roles in other AWS accounts.

Basic Setup

1. Base profile (~/.aws/credentials) - contains your IAM user credentials:

[mycompany]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

2. Profile configuration (~/.aws/config) - defines MFA device and session profile:

[profile mycompany]
region = us-west-2
mfa_serial = arn:aws:iam::111111111111:mfa/username

[profile mycompany-session]
region = us-west-2

3. Generate MFA session credentials:

aws-mfa-session --profile mycompany --update-profile mycompany-session --code 123456

Assume Role Profiles

Now you can create assume role profiles that use the MFA-authenticated session as their source:

[profile dev-account]
region = us-west-2
output = json
source_profile = mycompany-session
role_arn = arn:aws:iam::222222222222:role/AdminRole

[profile prod-account]
region = us-west-2
output = json
source_profile = mycompany-session
role_arn = arn:aws:iam::333333333333:role/AdminRole

Use the profiles:

# After running aws-mfa-session to populate mycompany-session
aws s3 ls --profile dev-account
aws ec2 describe-instances --profile prod-account

Readonly Assume Role Profiles

AWS CLI supports session policies that restrict permissions when assuming a role. This is useful for creating "readonly" variants of your profiles that limit what actions can be performed, even if the underlying role has broader permissions.

Use role_session_policy_arns to attach AWS managed policies:

[profile dev-account-readonly]
region = us-west-2
output = json
source_profile = mycompany-session
role_arn = arn:aws:iam::222222222222:role/AdminRole
role_session_policy_arns = arn:aws:iam::aws:policy/ReadOnlyAccess

[profile prod-account-readonly]
region = us-west-2
output = json
source_profile = mycompany-session
role_arn = arn:aws:iam::333333333333:role/AdminRole
role_session_policy_arns = arn:aws:iam::aws:policy/ReadOnlyAccess

The session policy acts as an intersection with the role's permissions - you can only restrict permissions, not expand them beyond what the role allows.

Other useful AWS managed policies for session restrictions:

Policy ARN	Description
arn:aws:iam::aws:policy/ReadOnlyAccess	Read-only access to all AWS services
arn:aws:iam::aws:policy/SecurityAudit	Security audit access
arn:aws:iam::aws:policy/ViewOnlyAccess	View-only access (more restrictive than ReadOnly)
arn:aws:iam::aws:policy/job-function/ViewOnlyAccess	Job function view-only access

Custom Inline Session Policies

For more granular control, use role_session_policy with an inline JSON policy:

[profile dev-account-s3-readonly]
region = us-west-2
source_profile = mycompany-session
role_arn = arn:aws:iam::222222222222:role/AdminRole
role_session_policy = {"Version":"2012-10-17","Statement":[{"Effect":"Allow","Action":["s3:Get*","s3:List*"],"Resource":"*"}]}

Note: role_session_policy_arns requires AWS CLI v2.15.0 or later.

Shell-Specific Output Examples

The tool automatically detects your shell and formats output appropriately:

Bash/Zsh/Sh output:

export AWS_ACCESS_KEY_ID='AKIAIOSFODNN7EXAMPLE'
export AWS_SECRET_ACCESS_KEY='wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY'
export AWS_SESSION_TOKEN='AQoEXAMPLE...'
export PS1='AWS:user@123456789012 \$ '

Fish shell output:

set -x AWS_ACCESS_KEY_ID "AKIAIOSFODNN7EXAMPLE"
set -x AWS_SECRET_ACCESS_KEY "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
set -x AWS_SESSION_TOKEN "AQoEXAMPLE..."
set -x PS1 "AWS:user@123456789012 \$ "

CMD output:

set "AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE"
set "AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
set "AWS_SESSION_TOKEN=AQoEXAMPLE..."
set "PROMPT=AWS:user@123456789012 \$ "

PowerShell output:

Set-Variable -Name "AWS_ACCESS_KEY_ID" -Value "AKIAIOSFODNN7EXAMPLE"
Set-Variable -Name "AWS_SECRET_ACCESS_KEY" -Value "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
Set-Variable -Name "AWS_SESSION_TOKEN" -Value "AQoEXAMPLE..."
function prompt { "AWS:user@123456789012 \$ " }

Installation

Pre-built Binaries

Download pre-built binaries from the GitHub Releases page for:

• Windows
• Linux
• macOS

Build from Source

Requirements: Rust and Cargo

# Install latest from crates.io
cargo install aws-mfa-session

# Install latest from git
cargo install --git https://github.com/AnderEnder/aws-mfa-session

# Build from local source
git clone https://github.com/AnderEnder/aws-mfa-session
cd aws-mfa-session
cargo build --release

# Install from local source
cargo install --path .

Usage

Usage: aws-mfa-session [OPTIONS]

Options:
  -p, --profile <PROFILE>
          AWS credential profile to use. AWS_PROFILE is used by default
  -f, --credentials-file <CREDENTIALS_FILE>
          AWS credentials file location to use. AWS_SHARED_CREDENTIALS_FILE is used if not defined
  -r, --region <REGION>
          AWS region. AWS_REGION is used if not defined
  -c, --code <CODE>
          MFA code from MFA resource
  -a, --arn <ARN>
          MFA device ARN from user profile. It could be detected automatically
  -d, --duration <DURATION>
          Session duration in seconds (900-129600) [default: 3600]
  -s, --shell
          Run shell with AWS credentials as environment variables
  -e, --export
          Print(export) AWS credentials as environment variables
  -u, --update-profile <SESSION_PROFILE>
          Update AWS credential profile with temporary session credentials
  -h, --help
          Print help

Security Features

• Input validation: MFA codes must be exactly 6 digits
• Duration validation: Session duration is validated to be within AWS limits (15 minutes to 36 hours)
• Atomic file operations: Credentials file updates are atomic to prevent corruption
• Permission preservation: Original file permissions are maintained when updating credentials
• Shell injection protection: All shell output is properly escaped for security
• Multi-shell support: Supports Bash, Zsh, Fish, Sh, CMD, and PowerShell with proper prompt setting

Shell Support

The application automatically detects your shell and formats output accordingly:

• Unix/Linux shells: Bash, Zsh, Sh, Fish
  • Sets AWS_* environment variables and PS1 prompt
  • Proper quote escaping for special characters
• Windows shells: CMD, PowerShell
  • CMD: Uses set commands and PROMPT variable
  • PowerShell: Uses Set-Variable and custom prompt function
  • Case-insensitive shell detection

Error Handling

The application provides detailed error messages with enhanced reporting using miette:

• Input validation errors: Invalid MFA codes, duration out of bounds
• AWS service errors: Authentication failures, missing MFA devices, STS token errors
• File operation errors: Permission issues, file corruption prevention
• Network errors: Connectivity issues, timeout handling
• Interactive errors: TTY detection for MFA code prompting

All errors include helpful context and suggestions for resolution.