🔒 mfaws 🔒

AWS Multi-Factor Authentication manager

Installation

Install script (Linux & macOS)

Download the appropriate binary from the releases page, chmod +x, and drop it into your PATH.

Chocolatey (Windows)

choco install mfaws

Note: Make sure your hardware clock is correct! Especially if dual booting. If your time is out of sync, your MFA attempts will fail and the codes oathtool generates will be wrong (if you use it).

Usage

AWS Multi-Factor Authentication manager

Usage:
  mfaws [flags]
  mfaws [command]

Available Commands:
  help        Help about any command
  version     Prints mfaws version information

Flags:
  -a, --assume-role string         ARN of IAM role to assume [MFA_ASSUME_ROLE]
  -c, --credentials-file string    Path to AWS credentials file (default "~/.aws/credentials") [AWS_SHARED_CREDENTIALS_FILE]
  -d, --device string              ARN of MFA device to use [MFA_DEVICE]
  -l, --duration int               Duration in seconds for credentials to remain valid (default assume-role ? 3600 : 43200) [MFA_STS_DURATION]
  -e, --external-id string         Unique ID used by third parties to assume a role in their customers' accounts [AWS_EXTERNAL_ID]
  -f, --force                      Force credentials to refresh even if not expired
  -h, --help                       help for mfaws
      --long-term-suffix string    Suffix appended to long-term profiles (default "-long-term")
  -p, --profile string             Name of profile to use in AWS credentials file (default "default") [AWS_PROFILE]
  -s, --role-session-name string   Session name when assuming a role
      --short-term-suffix string   Suffix appended to short-term profiles (default "")
  -t, --token string               MFA token to use for authentication
  -v, --verbose                    Enable verbose output

Use "mfaws [command] --help" for more information about a command.

Examples

Using the default profile

Make sure you have the following in your $HOME/.aws/credentials file:

[default-long-term]
aws_access_key_id     = $YOUR_AWS_ACCESS_KEY_ID
aws_secret_access_key = $YOUR_AWS_SECRET_ACCESS_KEY
aws_mfa_device        = $YOUR_MFA_DEVICE_ARN

Then, simply run

mfaws

to fetch temporary credentials for your default AWS profile. More advanced configuration is possible (see Usage).

Combine mfaws with oathtool

Set an alias for generating your MFA token, then pipe it into mfaws:

alias otp-aws="oathtool --totp --base32 $YOUR_AWS_TOTP_KEY"

otp-aws | mfaws
# or
otp-aws | mfaws -p some-profile