How to assume an IAM role using AWS CLI
Assuming an IAM role with AWS CLI is the standard way to work across AWS accounts or step into elevated permissions without storing another long-lived access key pair. The role session keeps privileged access temporary, ties activity to the target role, and reduces the risk of leaving production credentials active longer than necessary.
In AWS CLI, a role profile lives in ~/.aws/config and combines the target role_arn with a credential source that can request the session. When a command runs with that profile, the CLI calls STS AssumeRole automatically, stores the temporary credentials in ~/.aws/cli/cache, and signs later requests as the assumed role until the session expires.
The source identity still needs permission to call sts:AssumeRole, and the role trust policy must allow that identity to enter the role. Some roles also require MFA or an external_id, and if the source profile already assumes another role, AWS treats the result as role chaining and limits that session to one hour even when the target role allows a longer maximum duration.
Related: How to switch AWS CLI profiles
Related: How to configure credential_process in AWS CLI
Steps to assume an IAM role using AWS CLI:
- List the configured profiles and choose the source profile that already authenticates successfully and is allowed to call sts:AssumeRole.
$ aws configure list-profiles default source-user sso-admin
The source profile is the profile that already resolves working credentials. It can be backed by access keys, IAM Identity Center, or credential_process as long as that identity is trusted by the target role.
- Set the target role ARN on a new named profile that will represent the assumed session.
$ aws configure set role_arn arn:aws:iam::210987654321:role/CrossAccountAdmin --profile operations-admin
Use the IAM role ARN, not an STS assumed-role ARN copied from an earlier session.
- Set the source profile that AWS CLI should use when it requests the role session.
$ aws configure set source_profile source-user --profile operations-admin
A role profile must use either source_profile or credential_source. Do not set both in the same profile. Use credential_source only when the source credentials should come from Environment, Ec2InstanceMetadata, or EcsContainer instead of another named profile.
- Add the session options that the role policy or audit trail requires.
$ aws configure set role_session_name workstation-ops-admin --profile operations-admin $ aws configure set duration_seconds 3600 --profile operations-admin $ aws configure set mfa_serial arn:aws:iam::123456789012:mfa/source-user --profile operations-admin
Add external_id the same way only when the role trust policy requires it. duration_seconds can be between 900 and 43200 seconds up to the role's configured maximum, but a chained role session cannot exceed one hour.
- Inspect the saved role profile in ~/.aws/config and confirm the expected values were written under the correct profile name.
$ cat ~/.aws/config [profile operations-admin] role_arn = arn:aws:iam::210987654321:role/CrossAccountAdmin source_profile = source-user role_session_name = workstation-ops-admin duration_seconds = 3600 mfa_serial = arn:aws:iam::123456789012:mfa/source-user
Role profile settings live in the shared config file, while source access keys usually stay in ~/.aws/credentials.
Related: How to find the AWS CLI config file
- Run an STS identity call through the new profile and confirm the returned ARN is an assumed-role session for the target account.
$ aws sts get-caller-identity --profile operations-admin --query Arn --output text Enter MFA code for arn:aws:iam::123456789012:mfa/source-user: arn:aws:sts::210987654321:assumed-role/CrossAccountAdmin/workstation-ops-admin
The MFA prompt appears only when the role requires MFA or mfa_serial is configured. After the first successful call, AWS CLI reuses cached temporary credentials from ~/.aws/cli/cache until they expire or are replaced.