Ashwin authenticates using
an MFA in order to access
AWS resources through the CLI

authenticate-mfa-cli-ashwin

How do I use an MFA token to authenticate access to my AWS resources through the AWS Command Line Interface (AWS CLI)?

It's a best practice to protect your account and its resources by using a multi-factor authentication device (MFA). If you plan to interact with your resources using the AWS CLI while using an MFA device, you must create a temporary session token instead. If you are using an MFA hardware device, the ARN value is similar to GAHT12345678. If you are using a virtual MFA, the value is similar to arn:aws:iam::123456789012:mfa/user. For more information, see Checking MFA Status.

After you install and configure the latest version of the AWS CLI, run the sts get-session-token AWS CLI command, replacing the variables with information from your account, resources, and MFA device:

$ aws sts get-session-token --serial-number arn-of-the-mfa-device --token-code code-from-token

You'll receive output with temporary credentials and an expiration time for those temporary credentials (by default, 12 hours), in a format similar as follows:

{
"Credentials": {
    "SecretAccessKey": "secret-access-key",
    "SessionToken": "temporary-session-token",
    "Expiration": "expiration-date-time",
    "AccessKeyId": "access-key-id"
    }
}

Note: You can specify an expiration duration (in seconds) using the --duration-seconds option in the same command, where the value can range from 900 seconds (15 minutes) to 129600 seconds (36 hours). If you are using root user credentials, the range is between 900 seconds (15 minutes) and 3600 seconds (1 hour).

Using temporary credentials with environment variables

You can use temporary credentials by exporting their values to environment variables using these commands.

Linux:

$ export AWS_ACCESS_KEY_ID=<Access-Key-as-in-Previous-Output>
$ export AWS_SECRET_ACCESS_KEY=<Secret-Access-Key-as-in-Previous-Output>
$ export AWS_SESSION_TOKEN=<Session-Token-as-in-Previous-Output>

Windows:

> set AWS_ACCESS_KEY_ID=<Access-Key-as-in-Previous-Output>
> set AWS_SECRET_ACCESS_KEY=<Secret-Access-Key-as-in-Previous-Output>
> set AWS_SESSION_TOKEN=<Session-Token-as-in-Previous-Output>

If you set the environment variables, be sure that you unset them before making the get-session-token call again using these commands.  

> unset AWS_ACCESS_KEY_ID
> unset AWS_SECRET_ACCESS_KEY
> unset AWS_SESSION_TOKEN

Using temporary credentials with named profiles

You can also use named profiles to specify which commands require MFA authentication. To do so, edit the credentials file in the .aws folder in the home directory of the user to add a new profile configuration for issuing MFA-authenticated commands. Here's an example profile configuration:

[mfa]
output = json
region = us-east-1
aws_access_key_id = <Access-key-as-in-returned-output>
aws_secret_access_key = <Secret-access-key-as-in-returned-output>
aws_session_token = <Session-Token-as-in-returned-output>

After the credentials expire, execute the get-session-token command again, and then export the returned values to the environment variables or to the profile configuration. Consider running a script or a cron job in the background that checks for expiration, and then prompts for re-authentication.

If the AWS CLI is configured using the aws configure command, there is a default configuration with permanent credentials of an IAM user, which is used for commands that don't require MFA authentication. You could also include the MFA device ARN as a variable in the named profile configuration.

Sample configuration:

.aws/credentials

[default]
aws_access_key_id = <Access-Key-for-an-IAM-User>
aws_secret_access_key = <Secret-Access-Key-for-IAM-User>

.aws/config

[profile mfa]
source_profile = default
mfa_serial = arn:aws:iam::AcctNumber:mfa/UserName

Note: If you use profiles to authenticate commands using AWS CLI, specify the --profile option followed by the profile name to be sure that the calls are authenticated using MFA.

For example, this command uses the default profile credentials and won't be authenticated with MFA.  

$ aws s3 ls

This command prompts for entering the MFA token-code, and then the Amazon Simple Storage Service (Amazon S3) API call is authenticated using MFA. It is also important to understand the Credential Precedence so that you can be sure that correct credentials are used when making API calls.

$ aws s3 ls --profile mfa

You can also require that a user be authenticated using an MFA to perform particular API actions by using the aws:MultiFactorAuthPresent or aws:MultiFactorAuthAge conditions in an IAM policy.


Did this page help you? Yes | No

Back to the AWS Support Knowledge Center

Need help? Visit the AWS Support Center

Published: 2017-01-10

Updated: 2018-06-29