Repository files navigation

AWS multi-factor authentication manager

AWS Multi-Factor Authentication Manager
Usage:  mfaws [flags]  mfaws [command]
Available Commands:  completion  Generate the autocompletion script for the specified shell  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.

mfaws works by looking for AWS credentials and an MFA device ARN in profiles suffixed with-long-term. It uses those credentials as well as a TOTP code supplied by the user to make anAssumeRole call. The outcome of this is another set of short-lived credentials scoped to the role session. These short lived credentials are stored in a separate profile in the credentials file without the-long-term suffix.

For example, your~/.aws/credentials file should look similar to this. Here we are using the profiledefault-long-term:

[default-long-term]aws_access_key_id     = $YOUR_AWS_ACCESS_KEY_IDaws_secret_access_key = $YOUR_AWS_SECRET_ACCESS_KEYaws_mfa_device        = $YOUR_MFA_DEVICE_ARN

Then, simply run the following, and enter the MFA token when prompted:

$ mfaws

If that is sucessful, it will create a another profile in the credentials file calleddefault that contains the session-scoped creds:

 [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+[default]+aws_access_key_id     = ...+aws_secret_access_key = ...+aws_session_token     = ...

In this example we useddefault because it is what tools such as the AWS SDK andaws CLI load by default when no profile is specified. Using other profiles is also like so:mfaws -p myprofile, which will result in the following:

 [myprofile-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+[myprofile]+aws_access_key_id     = ...+aws_secret_access_key = ...+aws_session_token     = ...

You can useoathtool to get TOTP codes directly in the CLI without having to copy them from elsewhere.mfaws can receive a TOTP code piped from stdin:

oathtool --totp --base32$YOUR_AWS_TOTP_KEY| mfaws

You can get TOTP codes from MFA keys that you've saved in your 1Password account. This has the advantage of not leaking the secret to disk. In this example, we're requesting a TOTP code from an item calledAWS in our 1Password account and piping it intomfaws:

op item get AWS --otp| mfaws

Similar to the above examples, you can request a TOTP code from HashiCorp Vault. In this example, we've enabled the TOTP secret engine and previously saved our MFA secret as an item calledmy-aws-totp-secret. Simply use the Vault CLI to read just thecode field from that secret:

vault read -field=code totp/code/my-aws-totp-secret | mfaws