How do I use the AWS CLI to authenticate access to AWS resources with an MFA token?

Short description

You can activate up to eight MFA devices for each AWS Identity and Access Management (IAM) user.

Note: MFA activation for the root user affects only the root user credentials. Each IAM identity in your AWS account has its own MFA configuration.

To activate MFA, see Secure your root user sign-in with multi-factor authentication (MFA) and AWS multi-factor authentication in IAM.

Resolution

If you receive errors when you run AWS CLI commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

To use the AWS CLI to authenticate to AWS resources, use the API action GetSessionToken to get temporary credentials. Temporary credentials are valid for 12 hours by default. Use the duration-seconds parameter to configure the temporary credential duration for any time between 15 minutes and 36 hours.

Note: The user needs appropriate IAM permissions to use the GetSessionToken. For more information, see How do I enforce MFA authentication for IAM users that use the AWS Management Console and the AWS CLI?

MFA device ARN

To get the MFA device's Amazon Resource Name (ARN), complete these steps:

1. Open the IAM console.
2. In the navigation pane, choose Users, and then select your IAM user.
3. On the Summary page, choose the Security credentials tab.
4. In Assigned MFA device, copy the MFA device's ARN.

Use the AWS CLI to get temporary credentials

Run the get-session-token command:

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

Example output:

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

Important: Make sure that the MFA device's serial number, token, and ARN are correct. If they aren't, then you might receive an error message that's similar to the following:

"An error occurred (AccessDenied) when calling the GetSessionToken operation: MultiFactorAuthentication failed, unable to validate MFA code. Please verify your MFA serial number is valid and associated with this user."

To authenticate your MFA hardware device, the serial number is usually on the back of the device and is similar to GAHT12345678. To authenticate your MFA virtual device, the value is similar to arn:aws:iam::123456789012:mfa/user.

Note: The AWS CLI supports MFA authentication only with a virtual or hardware MFA device. The AWS CLI doesn't support MFA authentication with the FIDO security key.

For more information, see Assign MFA devices in the AWS CLI or AWS API.

Use temporary credentials to export their values to environment variables

Run the following commands for your operating system (OS):

Linux

export AWS_ACCESS_KEY_ID=example-access-key-as-in-previous-outputexport AWS_SECRET_ACCESS_KEY=example-secret-access-key-as-in-previous-output  
export AWS_SESSION_TOKEN=example-session-token-as-in-previous-output

Windows

set AWS_ACCESS_KEY_ID=example-access-key-as-in-previous-outputset AWS_SECRET_ACCESS_KEY=example-secret-access-key-as-in-previous-output  
set AWS_SESSION_TOKEN=example-session-Token-as-in-previous-output

Before you run the get-session-token command again, run the following commands to unset the environment variables:

Linux

unset AWS_ACCESS_KEY_IDunset AWS_SECRET_ACCESS_KEY  
unset AWS_SESSION_TOKEN

Windows

set AWS_ACCESS_KEY_ID=set AWS_SECRET_ACCESS_KEY=  
set AWS_SESSION_TOKEN=

Use temporary credentials with named profiles

You can also use named profiles to specify the commands that require MFA authentication. In the credentials file that's in the .aws folder of the user's home directory, add a new profile configuration to issue authenticated commands.
Example profile configuration:

[mfa]aws_access_key_id = example-access-key-as-in-returned-outputaws_secret_access_key = example-secret-access-key-as-in-returned-output  
aws_session_token = example-session-token-as-in-returned-output

After the credentials expire, run the get-session-token command again. Then, export the returned values to the environment variables or the profile configuration.

It's a best practice to run a script or a cron job in the background that checks for the expiration from the get-session-token command's output. If the MFA token is expired, then make sure that the script or cron job prompts for reauthentication.

When you use named profiles to authenticate, specify the profile option followed by the profile name. This verifies that the API calls use MFA to authenticate.

Related information

How do I reset a lost or broken MFA device for my IAM user or AWS account root user?

How do I enforce MFA authentication for IAM users that use the AWS Management Console and the AWS CLI?