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

Last updated: 2020-08-21

How do I use an MFA token to authenticate access to my AWS resources with 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 (MFA) device. If you plan to interact with your resources using the AWS CLI when using an MFA device, then you must create a temporary session. If you're using an MFA hardware device, the ARN value is similar to GAHT12345678. If you're using a virtual MFA, the value is similar to arn:aws:iam::123456789012:mfa/user. For more information, see Checking MFA status.


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 receive an output with temporary credentials and an expiration time (by default, 12 hours) similar to the following:

    "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 sts get-session-token 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 from 900 seconds (15 minutes) to 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.


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


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

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


Using temporary credentials with named profiles

You can also use named profiles to specify the commands that 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:

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, execute the get-session-token command again, and then export the returned values to the environment variables or to the profile configuration.

Tip: Consider running a script or a cron job in the background that checks for "expiration" from the output of get-session-token command, and then prompts for re-authentication.

If the AWS CLI is configured using the configure command, there's a default configuration with permanent AWS Identity and Access Management (IAM) user credentials. This IAM user can use commands that don't require MFA authentication.

Example configuration:


aws_access_key_id = example-access-Key-for-an-IAM-user
aws_secret_access_key = example-secret-access-key-for-IAM-user

Note: You can't use the mfa_serial parameter with permanent IAM credentials.

If you use profiles to authenticate commands using the AWS CLI, specify the --profile option followed by the profile name to verify that the calls authenticate using MFA.

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

$ aws s3 ls

Important: Be sure that you understand the credential precedence so that you can verify that correct credentials are used when making API calls.

$ aws s3 ls --profile mfa

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

Did this article help?

Do you need billing or technical support?