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 MFA and MFA in IAM.

Resolution

To use the AWS CLI to authenticate to AWS resources, use the API action GetSessionToken to get temporary credentials.

Note: 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.

MFA device ARN

To get the MFA device's ARN, complete these steps:

1. Open the IAM console.
2. In the navigation pane, choose Users, and then choose 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, or 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 the value 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-output
export 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-output
set 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_ID
unset 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 MFA-authenticated commands.

Example profile configuration:

[mfa]aws_access_key_id = example-access-key-as-in-returned-output
aws_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, and 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 to verify 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?