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

4 minute read
2

I want to use an MFA token to authenticate access to my AWS resources with the AWS Command Line Interface (AWS CLI).

Resolution

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, then the value is similar to GAHT12345678. If you're using a virtual MFA, then the value can be found by viewing the Security credentials. It looks similar to arn:aws:iam::123456789012:mfa/user. For more information, see Checking MFA status.

Important:

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. The value can range from 900 seconds (15 minutes) to 129600 seconds (36 hours). If you are using root user credentials, then 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.

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

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

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=

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. In the credentials file, add a new profile configuration for issuing MFA-authenticated commands. Here's an 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 to the profile configuration.

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

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/credentials

[default]
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. This is done 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. This can be done by using the GetCallerIdentity command.

$ aws s3 ls --profile mfa

You can require a user to authenticate using an MFA to perform particular API actions. Use either the aws:MultiFactorAuthPresent or aws:MultiFactorAuthAge conditions in an IAM policy to accomplish this.


Related information

Activating MFA devices for users in AWS

Lost or unusable multi-factor authentication (MFA) device

2 Comments

To run "aws sts get-session-token" command, I need to provide the AWS profile. To provide the AWS profile I need to store the "aws_access_key_id" and "aws_secret_access_key" under the credential file on my local machine. Then what is the point of using temporary credential with MFA from the same machine where information for Access key is already stored!!. How does this makes it more secure?

I don't see an option to create Access Key with limited permission where only "sts get-session-token" is allowed, in which case I can use that Access Key on my machine to first get temporary credentials and then use those temporary creds to access other resources.

I found the answer to my confusion when looking at https://repost.aws/knowledge-center/mfa-iam-user-aws-cli

replied 8 months ago

Thank you for your comment. We'll review and update the Knowledge Center article as needed.

profile pictureAWS
MODERATOR
replied 8 months ago