aws sts assume-role: Get Temporary Credentials
aws sts assume-role returns temporary AccessKeyId, SecretAccessKey, and SessionToken for an IAM role you are allowed to assume, scoped to a limited duration.
Cross-account deploys and privilege separation lean on assume-role. In CI you usually let the OIDC action assume the role for you, but explicit assume-role is still common for cross-account hops.
What it does
aws sts assume-role calls STS to obtain temporary credentials for --role-arn, provided the role trust policy allows your principal. You name the session with --role-session-name (it appears in CloudTrail and the assumed-role ARN) and can cap the lifetime with --duration-seconds.
Common usage
CREDS=$(aws sts assume-role \
--role-arn arn:aws:iam::123456789012:role/cross-account-deploy \
--role-session-name "ci-$GITHUB_RUN_ID" \
--duration-seconds 3600 \
--query 'Credentials' --output json)
export AWS_ACCESS_KEY_ID=$(echo "$CREDS" | jq -r .AccessKeyId)
export AWS_SECRET_ACCESS_KEY=$(echo "$CREDS" | jq -r .SecretAccessKey)
export AWS_SESSION_TOKEN=$(echo "$CREDS" | jq -r .SessionToken)Options
| Flag | What it does |
|---|---|
| --role-arn <arn> | Role to assume (required) |
| --role-session-name <name> | Session label, shown in CloudTrail (required) |
| --duration-seconds <n> | Lifetime 900 to role MaxSessionDuration |
| --external-id <id> | Third-party confused-deputy guard |
| --serial-number / --token-code | MFA device ARN and one-time code |
| --query Credentials --output json | Pull the credential block to export |
In CI
Always set AWS_SESSION_TOKEN alongside the key/secret; forgetting it causes confusing "InvalidClientTokenId" errors downstream. --duration-seconds cannot exceed the role's MaxSessionDuration; if you raise it, raise that first. In GitHub Actions, prefer aws-actions/configure-aws-credentials with OIDC so no static keys exist; reserve explicit assume-role for the second cross-account hop.
Common errors in CI
"An error occurred (AccessDenied) when calling the AssumeRole operation: User: ... is not authorized to perform: sts:AssumeRole on resource: arn:...role/..." means the role trust policy does not list your principal. "The requested DurationSeconds exceeds the MaxSessionDuration set for this role" means --duration-seconds is too high. "ExpiredToken: The security token included in the request is expired" means the credentials you are assuming WITH already expired; re-authenticate.