AWS MFA Secure
Surprisingly, the aws cli does not yet support MFA for normal IAM users. See: boto/botocore/pull/1399 The aws-mfa-secure tool decorates the AWS CLI or API to handle MFA authentication. The MFA prompt only activates if
mfa_serial is configured.
An advantage of the aws-mfa-secure is that it caches the temporary credentials
~/.aws/aws-mfa-secure-sessions and reuses them until they expire. The expiration is 8 hours by default. This means that when you open a new terminal tab, you won’t have to re-enter the MFA code.
gem install aws-mfa-secure
Prerequisite: The AWS CLI is required. You can install the AWS CLI via pip.
pip install awscli --upgrade --user
- Set up bash alias
- Use aws cli like you normally would
Configure ~/.aws/credentials with mfa_serial
mfa_serial in credentials file for the profile section that requires it. Example:
[mfa] aws_access_key_id = BKCAXZ6ODJLQ1EXAMPLE aws_secret_access_key = ABCDl4hXikfOHTvNqFAnb2Ea62bUuu/eUEXAMPLE mfa_serial = arn:aws:iam::112233445566:mfa/MFAUser
Note: AWS already supports
mfa_serial for assumed roles: AWS Configuration and Credential File Settings. The aws-mfa-secure tool does not decorate for assumed roles and lets the AWS CLI or SDK handle it. The aws-mfa-secure tool adds support for standard IAM users, which is not currently supported. See: boto/botocore/pull/1399
Set up bash alias
alias aws="aws-mfa-secure session"
The alias allows us to intercept the normal aws cli command and decorate it. The
aws-mfa-secure session only activates if
mfa_serial is configured in your
~/.aws/credentials file. Otherwise, it will pass the command through to the normal aws cli. You may want to add the alias to your
~/.bash_profile do you don't have to alias it every time you open a new terminal.
Autocompletion still works with the alias.
Use aws cli like usual
aws command like you usually would:
aws s3 ls
Example with Output
$ export AWS_PROFILE=mfa $ aws s3 ls Please provide your MFA code: 751888 2019-09-21 15:53:34 my-example-test-bucket $ aws s3 ls 2019-09-21 15:53:34 my-example-test-bucket $
Expiration: You get prompted for the MFA token once, and the MFA secure session lasts for 12 hours. You can override the default expiration time with
AWS_MFA_TTL. For example,
AWS_MFA_TTL=3600 means the session expires in 1 hour instead.
You can also call
aws-mfa-secure session directly.
aws-mfa-secure session --version aws-mfa-secure session s3 ls
The arguments of
aws-mfa-secure session are delegated to the
aws command. So:
aws-mfa-secure session s3 ls
Is the same as:
aws s3 ls
aws-mfa-secure session will use the temporary session environment
AWS_* variables values.
You can also generate an exports script. The exports technique is useful for tools that do not yet support MFA. Using
AWS_* env variables for credentials should allow those tools to work. Though, it may depend on the tool as they sometimes hardcode a credentials configuration. Example:
$ aws-mfa-secure exports Please provide your MFA code: 147280 export AWS_ACCESS_KEY_ID=ASIAXZ6ODJLBCEXAMPLE export AWS_SECRET_ACCESS_KEY=HgYHvNxacSsFSwls1FO9RoF5+tvYCFIABEXAMPLE export AWS_SESSION_TOKEN=IQoJb3JpZ2luX2VjEJ3//////////wEaCXVzLWVhc3QtMSJGMEQCIGnuGzUr8aszNWMFlFXQvFVhIA6aGdx3DskqY1JaIZWVAiANfE3xA79vIMVTqLnds4F2LpDy/qUeNRr7e9g9VQoS9SqyAQi2//////////8BEAEaDDUzNjc2NjI3MDE3NyIMgDgauwgJ4FIOMRV+KoYBRKR/MnKFB9/Q0Isc6D8gpG404xGJWqStNfGS0sHNsB5vVP/ccaAj4MG54p0Pl+V0LuIMXy345ua/bxxQFDWqhG0ORsXFEOo3iD1IQ+YA/yougAUl/0hbyvK3Jnf3NEHDejdL95iFCluJhoR0zFlDv7GwwBSXLUxS9K96/vgA0MmgK9a7kaAwoYiZ7gU63wHVDNYa1myqIP16Mi6KZ2zm9inMofixNN1ea3JMyRW+chWW8kdjjW4R3MFecpwoIayE7g3QLanmjE3jzrlxjIJWnl8tiipV+jassiSdlxLL2j1IIFH2pNEqrn4hkHG5t7OG+qZCTl8AnQ4W5wusmBoSIavr5w0dOdyx2mdsBMFtO82ZXvHSryY1gbIM9JyUd7dJ9h/mkfGL2p0n0R/lya8s9j8P8/8if+2uQcF+/BGDxojJ67kYXgstgfLjM5j8pZgyYj6YUFyTpyiOkllbPk/AjyxJY1svxW25wbNO+c13 $
You can eval it to set the environment variables in one go. Note, the MFA code prompt is written to standard error so it won't affect the eval.
$ eval `aws-mfa-secure exports`
If you're using the
aws-mfa-secure exports command, the
aws-mfa-secure unsets command is useful to unset the
AWS_* env variables quickly. For more info:
aws-mfa-secure unsets -h.
Ruby AWS SDK Extension
You can also use
aws-mfa-secure to add MFA support to Ruby libraries. Do so by requiring the
require "aws_mfa_secure/ext/aws" # add MFA support
This patches the aws-sdk-ruby library and adds MFA support.
Setting MFA Info with Env Variables
You can also set the MFA info with env variables. They take the highest precedence and override what's in
AWS_MFA_TOKEN=112233 AWS_MFA_SERIAL=arn:aws:iam::112233445566:mfa/MFAUser aws s3 ls
How It Works
Docs: How It Works
This tool only supports Linux. For Windows, you'll have to set the
AWS_* env variables manually. Refer to these resources:
- Switching to an IAM Role (Tools for Windows PowerShell)
- How do I use an MFA token to authenticate access to my AWS resources through the AWS CLI?
You may also be interested in tongueroo/aws-rotate. It's an easy way to rotate all your AWS keys in your
- Fork it
- Create your feature branch (
git checkout -b my-new-feature)
- Commit your changes (
git commit -am "Add some feature")
- Push to the branch (
git push origin my-new-feature)
- Create new Pull Request