How to assume an IAM role using AWS CLI

Assuming an IAM role with AWS CLI lets one saved profile borrow temporary permissions from another AWS account or admin role without storing separate long-lived keys for the target account. Use it when the next command needs cross-account access, short-lived elevated access, or a role-specific audit trail.

The role profile lives in ~/.aws/config. A working profile needs the target role_arn plus either source_profile or credential_source, and the CLI calls STS AssumeRole automatically the first time a command uses that profile. The temporary credentials are cached and reused until they expire.

The source identity can be an IAM user, an IAM Identity Center session, or another supported credential source, but it still needs permission to call sts:AssumeRole and the target role trust policy must allow it. AWS does not let the account root user assume roles this way, and a chained role session cannot last longer than one hour even if the target role allows more.

1. Confirm the source profile already resolves the identity that is allowed to assume the target role.

   $ aws sts get-caller-identity --profile source-user --query Arn --output text
   arn:aws:iam::123456789012:user/source-user

   The source profile can use access keys, IAM Identity Center, or credential_process as long as it already signs AWS CLI requests successfully.
   Related: How to configure multiple AWS CLI profiles
   Related: How to log in to AWS CLI with IAM Identity Center

2. Save the target role ARN into a new named profile.

   $ aws configure set role_arn arn:aws:iam::210987654321:role/CrossAccountAdmin --profile production-admin

   Use a profile name that matches the role or environment so later --profile selections stay readable.

3. Point the role profile at the source profile that should make the STS request.

   $ aws configure set source_profile source-user --profile production-admin

   Use credential_source instead of source_profile only when the source credentials should come from Environment, Ec2InstanceMetadata, or EcsContainer.

4. Set a readable role session name so the assumed session is easy to identify in the returned ARN and in CloudTrail.

   $ aws configure set role_session_name workstation-prod-admin --profile production-admin

   The final segment of the assumed-role ARN becomes this session name, so keep it short and operator-specific.

5. Save the default Region that this role profile should use.

   $ aws configure set region us-west-2 --profile production-admin

   This affects commands that do not pass an explicit --region override.

6. Add extra role settings only when the target role requires them.

   $ aws configure set mfa_serial arn:aws:iam::123456789012:mfa/source-user --profile production-admin

   Add mfa_serial only when the trust policy requires MFA, add external_id only for third-party cross-account access, and set duration_seconds only when the role allows a longer or shorter session than the default.

   If the source profile is already using temporary role credentials, this becomes role chaining and duration_seconds cannot be set above 3600 seconds.

7. Read the saved profile back from the shared config file and confirm the expected settings are under the right profile name.

   $ cat ~/.aws/config
   [profile source-user]
   region = us-west-2
   [profile production-admin]
   role_arn = arn:aws:iam::210987654321:role/CrossAccountAdmin
   source_profile = source-user
   role_session_name = workstation-prod-admin
   mfa_serial = arn:aws:iam::123456789012:mfa/source-user
   region = us-west-2

   Role settings are stored in ~/.aws/config even when the source profile credentials live in ~/.aws/credentials.
   Related: How to find the AWS CLI config file location

8. Run a low-risk identity call through the new profile and confirm the returned ARN shows an assumed-role session for the target account.

   $ aws sts get-caller-identity --profile production-admin --query Arn --output text
   Enter MFA code for arn:aws:iam::123456789012:mfa/source-user:
   arn:aws:sts::210987654321:assumed-role/CrossAccountAdmin/workstation-prod-admin

   The AWS CLI reuses the cached temporary credentials until they expire, then requests a fresh session the next time the profile is used.

   If this command returns the original user or the wrong role, clear exported credential variables such as AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN before testing again because environment credentials override file-backed profiles.
   Related: How to use AWS CLI environment variables