AWS Role Assumption Explained: Cross-Account Access, STS and CLI

Simple explanation

That is role assumption in one sentence: you temporarily become a different identity, with different permissions, using credentials that expire on their own.

Why role assumption matters

Long-lived access keys are the most common cause of AWS security incidents. They get committed to Git, pasted into Slack, or left in old servers. Role assumption eliminates this risk by issuing short-lived credentials that expire on their own.

• No permanent secrets. Temporary credentials expire, so a leaked credential has a bounded damage window.
• Least privilege by design. Each role carries only the permissions it needs. Different workloads get different roles.
• Safer cross-account access. Instead of sharing access keys between teams, you share a role ARN. The target account controls exactly who can assume the role and what they can do.
• Better auditability. Every AssumeRole call is logged in CloudTrail with the caller identity, session name, and source IP.

How role assumption works

When a principal (user, role, or service) wants to assume a role, AWS runs through these steps:

1. The caller calls sts:AssumeRole with the target role’s ARN.
2. AWS evaluates the target role’s trust policy to confirm the caller is an allowed principal.
3. AWS checks that the caller’s own identity policy allows sts:AssumeRole on the target role ARN (required for cross-account assumption and same-account assumption when the trust policy trusts the account root).
4. If both checks pass, STS returns temporary credentials: access key ID, secret access key, and session token.
5. The caller uses these credentials for API calls. Those calls are authorized against the role’s permissions policy, not the caller’s original permissions.

Trust policy vs permissions policy

This distinction trips up most beginners. A single IAM role has two separate policy attachments that serve completely different purposes.

Trust policy example: allow an AWS service

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "Service": "ec2.amazonaws.com" },
      "Action": "sts:AssumeRole"
    }
  ]
}

Trust policy example: allow a specific IAM user

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::123456789012:user/alice"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Trust policy example: require MFA

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::123456789012:user/alice"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "Bool": {
          "aws:MultiFactorAuthPresent": "true"
        }
      }
    }
  ]
}

This pattern is common for sensitive roles like production admin or billing access. The caller must authenticate with MFA before AWS will issue the temporary credentials.

When to use role assumption

Role assumption is not just for cross-account access. It is the default way workloads authenticate to AWS.

• EC2 instance profiles. An EC2 instance assumes a role automatically through the instance metadata service. Your application calls the AWS SDK and gets temporary credentials without any configuration.
• Lambda execution roles. Every Lambda function has an execution role. When the function runs, it assumes that role to access other AWS services.
• Cross-account admin or deployment access. A developer in Account A assumes a role in Account B to manage resources there, without needing a separate set of credentials in Account B.
• CI/CD pipelines. GitHub Actions, CodeBuild, or Jenkins assume a deployment role to push code to production without storing long-lived secrets in the pipeline.
• Third-party vendor access with ExternalId. A SaaS product assumes a role in your account to read logs or manage resources, using ExternalId to prevent the confused deputy problem.
• EKS pods. IAM Roles for Service Accounts (IRSA) lets individual Kubernetes pods assume their own IAM roles, so each workload gets only the permissions it needs.

Cross-account role assumption in AWS

Cross-account role assumption is how one AWS account grants controlled access to resources in another account. This is the standard pattern in multi-account organizations.

The two accounts

• Source account (Account A). The caller’s identity lives here. This could be a developer’s IAM user, a CI/CD pipeline role, or any other principal.
• Target account (Account B). The resources to access live here. A role exists in this account with a trust policy that allows principals from Account A.

Both sides must be configured. The target role must trust the source, and the source principal must have permission to call sts:AssumeRole on the target role.

Step 1: Create the role in Account B (target)

The trust policy on this role determines who from Account A can assume it.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111111111111:root"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "unique-external-id-abc123"
        }
      }
    }
  ]
}

Trusting :root means any principal in Account A can assume this role, as long as their own identity policy also allows sts:AssumeRole. Both conditions must be true.

Step 2: Allow the caller in Account A (source)

Attach an identity policy to the calling user or role in Account A:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "sts:AssumeRole",
      "Resource": "arn:aws:iam::222222222222:role/CrossAccountRole"
    }
  ]
}

Step 3: Assume the role from Account A

aws sts assume-role \
  --role-arn arn:aws:iam::222222222222:role/CrossAccountRole \
  --role-session-name "cross-account-session" \
  --external-id "unique-external-id-abc123"

ExternalId explained

ExternalId is a string agreed upon between you and a third party. It prevents the confused deputy problem. Without it, a malicious customer of the same SaaS vendor could trick the vendor into accessing your account by providing your role ARN. With ExternalId, the vendor must also supply the correct identifier, which only the legitimate customer knows.

AWS CLI examples

Direct assume-role call

aws sts assume-role \
  --role-arn arn:aws:iam::123456789012:role/AdminRole \
  --role-session-name "alice-admin-session" \
  --duration-seconds 3600

This returns a JSON response containing temporary credentials. To use them, export them as environment variables:

Export temporary credentials

# Extract and export credentials
eval $(aws sts assume-role \
  --role-arn arn:aws:iam::123456789012:role/AdminRole \
  --role-session-name "alice-admin-session" \
  --query 'Credentials.[AccessKeyId,SecretAccessKey,SessionToken]' \
  --output text | awk '{print "export AWS_ACCESS_KEY_ID="$1"\nexport AWS_SECRET_ACCESS_KEY="$2"\nexport AWS_SESSION_TOKEN="$3}')

# Verify you are now acting as the role
aws sts get-caller-identity

Using a named profile in ~/.aws/config

For repeated use, define a profile that assumes the role automatically:

[profile staging-admin]
role_arn = arn:aws:iam::123456789012:role/AdminRole
source_profile = default
role_session_name = alice-staging

Then use it with the —profile flag:

aws s3 ls --profile staging-admin

The CLI handles the AssumeRole call, caches the temporary credentials, and refreshes them when they expire. This is the most convenient approach for daily work.

Role assumption vs long-lived access keys

For a deeper look at why access keys are risky, read why long-lived AWS access keys are dangerous.

Role chaining

Role chaining is when an already-assumed role assumes another role. This is valid and sometimes necessary in multi-account architectures, but it comes with an important constraint: chained sessions are always capped at one hour, regardless of the MaxSessionDuration setting on the target role.

# First assumption: your IAM user assumes RoleA
aws sts assume-role \
  --role-arn arn:aws:iam::111111111111:role/RoleA \
  --role-session-name sess1

# Export RoleA's credentials, then assume RoleB from RoleA
aws sts assume-role \
  --role-arn arn:aws:iam::222222222222:role/RoleB \
  --role-session-name sess2

For this to work, RoleB’s trust policy must allow RoleA as a principal. RoleA needs permission to call sts:AssumeRole on RoleB’s ARN.

Troubleshooting AssumeRole failures

If your AssumeRole call returns an error, work through this checklist. Most failures come down to one of these causes. For a broader guide, see fixing IAM AccessDenied errors.

For authentication errors beyond AssumeRole, see troubleshooting authentication errors in AWS.