Quick Guide: Setting up AWS CLI with MFA / Cross-Account Roles

In this quick guide we will go through many of the most used aws cli commands to configure and enter you access credentials. We will also take a look at how to configure your profiles from cross account access with MFA enabled.

If you do not have MFA enabled (you should) then you can ignore the mfa_serial.

AWS CLI Configure (Default)

aws configure
>> AWS Access Key ID [****************SIPA]:
>> AWS Secret Access Key [****************1a5q]:
>> Default region name [us-east-1]:
>> Default output format [None]:

AWS CLI Configure with Profiles

aws configure --profile profileName                                              
>> AWS Access Key ID [****************M57Q]:
>> AWS Secret Access Key [****************SS4d]:
>> Default region name [us-west-2]:
>> Default output format [None]:


aws configure set profile.profile-name.role_arn arn:aws:iam::xxxxxxxxx:role/role-name

AWS CLI Source Profile

aws configure set profile.profile-name.source_profile parent-profile

AWS CLI Region

aws configure set region us-west-2 --profile profile-name


Apply this to the source_profile (parent-profile) as well as the profile you are going to be rolling into if they both require MFA.

aws configure set profile.profile-name.mfa_serial arn:aws:iam::xxxxxxxxx:mfa/username

Cross-Account Role Access Example

In the example below we are trying to use the CLI to role from a global authentication account holding users and groups into a logging account using the admin role. We are expecting the admin role and MFA device to be setup in this scenario.

The role_arn in the example comes from the logging account.

The mfa_serial in the example comes from the global auth account.

aws configure set profile.logging.role_arn arn:aws:iam::12345678:role/admin

aws configure set profile.logging.source_profile globalauth

aws configure set region us-west-2 --profile logging

aws configure set profile.logging.mfa_serial arn:aws:iam::443322111:mfa/myusername

Testing it out

Let’s test out our new profiles and check if they are working correctly.

Run a basic command to list out the buckets within the logging account

aws s3 ls --profile logging

If you have MFA enabled you will be prompted to enter your MFA code.

Enter MFA code for arn:aws:iam::xxxxxxxxxxx:mfa/username:

After the MFA code is entered your commands should now work. Your original command will now list out your buckets.

2018-11-13 11:08:38 bucket-1
2019-02-04 10:14:29 bucket-2
2019-02-04 10:16:04 bucket-3
2018-08-29 13:17:57 bucket-4
2018-09-08 10:46:26 bucket-5

AWS Documentation:

  • https://aws.amazon.com/premiumsupport/knowledge-center/iam-assume-role-cli/
  • https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-cli.html
  • https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html
1 like
Prev post: GuardDuty in a multi-account organization with Terraform

Related posts


Leave a Reply

Your email address will not be published. Required fields are marked *