How to assume an IAM role using AWS CLI

Topic: Accounts access

Assume an IAM role from the AWS CLI to get temporary credentials: use assume-role (or assume-role-with-saml/web-identity), set the returned credentials in the environment or profile, and run commands as the role. Use this for cross-account or delegated access without long-lived keys for the role.

Intent: How-to

Quick answer

  • Call sts assume-role with the role ARN and optional role session name; the response contains AccessKeyId, SecretAccessKey, and SessionToken.
  • Export the credentials as AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN (or add to a named profile) and run CLI commands; they run with the role's permissions.
  • Your identity must be allowed to assume the role (trust policy); for MFA, use get-session-token first or include SerialNumber and TokenCode in assume-role.

Prerequisites

Steps

  1. Ensure your identity can assume the role

    The role's trust policy must allow your principal (IAM user, role, or root) to sts:AssumeRole; for cross-account, the role must be in the target account and trust your account/role.

  2. Call AssumeRole

    Run aws sts assume-role --role-arn arn:aws:iam::ACCOUNT:role/ROLE_NAME --role-session-name SESSION; optionally pass --serial-number and --token-code for MFA if the trust policy requires it.

  3. Set the returned credentials

    From the response, set Credentials.AccessKeyId, Credentials.SecretAccessKey, and Credentials.SessionToken as environment variables or in a profile (aws configure profile ROLE_PROFILE with the three values).

  4. Run CLI commands as the role

    With the environment or profile set, run aws CLI commands; they use the temporary credentials and are subject to the role's permissions and session duration.

Summary

You will assume an IAM role from the CLI using STS AssumeRole, set the temporary credentials in the environment or a profile, and run commands as that role. Use this for cross-account access, delegated access, or testing role permissions without storing role credentials.

Prerequisites

  • An IAM role whose trust policy allows your principal (IAM user or role) to assume it (iam:AssumeRole).
  • AWS CLI configured with credentials that can call sts:AssumeRole (your user or role must be in the role’s trust policy).

Steps

Step 1: Ensure your identity can assume the role

The role’s trust policy must include your principal. Example for same-account IAM user:

{
  "Effect": "Allow",
  "Principal": {"AWS": "arn:aws:iam::123456789012:user/myuser"},
  "Action": "sts:AssumeRole"
}

For cross-account, the role is in the target account and Principal is your account ID or a role ARN. Verify with the role’s trust policy in IAM.

Step 2: Call AssumeRole

aws sts assume-role \
  --role-arn arn:aws:iam::123456789012:role/MyRole \
  --role-session-name my-session

If the trust policy requires MFA, add:

--serial-number arn:aws:iam::123456789012:mfa/myuser \
--token-code 123456

The response includes Credentials: AccessKeyId, SecretAccessKey, SessionToken, and Expiration.

Step 3: Set the returned credentials

Environment variables (Linux/macOS):

eval $(aws sts assume-role --role-arn arn:aws:iam::123456789012:role/MyRole --role-session-name s --query 'Credentials' --output text | awk '{print "export AWS_ACCESS_KEY_ID="$2"\nexport AWS_SECRET_ACCESS_KEY="$4"\nexport AWS_SESSION_TOKEN="$5}')

Or manually:

export AWS_ACCESS_KEY_ID=ASIA...
export AWS_SECRET_ACCESS_KEY=...
export AWS_SESSION_TOKEN=...

Named profile: Add to ~/.aws/credentials under a profile with aws_access_key_id, aws_secret_access_key, and aws_session_token from the AssumeRole response. Use --profile ROLE_PROFILE when running the CLI.

Step 4: Run CLI commands as the role

With the credentials set:

aws sts get-caller-identity

The returned ARN should be the role ARN and the role’s session. All subsequent CLI calls use the role’s permissions until the session expires.

Verification

  • aws sts get-caller-identity returns the role ARN (and assumed-role session).
  • Commands that the role is allowed to run succeed; commands that the role is denied fail with AccessDenied.
  • After the session expires, the same credentials fail; assume the role again to get new credentials.

Troubleshooting

Access denied to AssumeRole — Your principal is not in the role’s trust policy, or the trust policy has a Condition (e.g. MFA) that is not satisfied. Add your principal to the trust policy or provide MFA (—serial-number and —token-code).

Session token expired — Temporary credentials from AssumeRole expire (default up to 1 hour; max 12 hours if role max session duration is set). Re-run assume-role to get a new set.

Cross-account assume fails — Ensure the role is in the target account and the trust policy Principal is your account ID or role ARN. Your identity must have sts:AssumeRole permission; the role trust must allow it.

Next steps

Continue to