AWS STS Assume Role Command Builder

Build the call, and see the two duration rules that catch people: the role's own maximum, and the separate cap that applies when you chain.

The role

Role ARN The role to assume, not the caller. Its trust policy is what decides whether this works at all.

Session name It appears in CloudTrail as the assumed-role user, so it is the only link from an API call back to a person. Use something identifying.

Duration

Duration in seconds The default ceiling for a role is one hour, and asking for longer FAILS unless the role's own MaxSessionDuration has been raised. The error names the duration rather than the role setting, so people adjust the request.

Assuming from another assumed role (chaining)

Role chaining caps the session at one hour regardless of what either role permits, and the cap is silent: you get an hour and no warning that you asked for more.

Third party

External id Required by the trust policy of almost every third-party role, and it exists to stop the confused deputy problem. Leave it empty for a role inside your own accounts.

assume-role.sh

updates as you type

Examples

Worked setups you can load into the form above. Each one is a decision the generator makes differently, and the reason it makes it.

A twelve hour session

Needs the role's MaxSessionDuration raised, and is capped at an hour if chained

session: alice@example.com
duration: 43200
role: arn:aws:iam::111122223333:role/Deployer

A third-party role

Almost always needs an external id, which their trust policy will require

role: arn:aws:iam::999988887777:role/Vendor
external-id

Common mistakes

These are the ones that fail silently. The config is accepted, nothing raises an error, and the consequence arrives later.

Raising DurationSeconds and finding it ignored
If the credentials you are using came from an assumed role, this is chaining, and STS caps it at one hour without erroring.
Instead:Assume the second role from the original credentials rather than from the first role.
Assuming that deleting a role kills its sessions
Credentials already issued keep working until they expire. There is no revoke call.
Instead:Add a deny with a condition on aws:TokenIssueTime, and keep durations short.
Using a generic session name
CloudTrail then shows a stream of identical assumed-role identities with nothing to distinguish who or what was behind each.
Instead:Use an email address, a pipeline run id or a hostname.

Role chaining is capped at one hour and ignores your request

Assuming a role using credentials that came from another assumed role is chaining. STS caps that at one hour and silently ignores a longer DurationSeconds rather than erroring.

The role's maximum is the other limit

A request longer than an hour fails unless the role's MaxSessionDuration has been raised, and the error names the duration rather than the role setting, so people adjust the request instead. Twelve hours is the ceiling.

Issued credentials cannot be revoked

There is no revoke call. Deleting the role, detaching its policies or removing the trust does not invalidate sessions already issued: they work until they expire. A twelve hour session that leaks is twelve hours of access, which is the argument for short durations.

The documented way to cut sessions off

An inline deny policy on the role with a condition on aws:TokenIssueTime invalidates everything issued before a moment. It is the mechanism the console's revoke button uses, and it is worth knowing exists before you need it.

The session name is the only trace of who

It appears in CloudTrail and in aws:userid. A session name of session or temp makes every entry indistinguishable, which is discovered during an investigation rather than before one. It can also be constrained in the trust policy with a condition on sts:RoleSessionName.

An external id is for third parties

It is not a secret and not authentication. It stops the third party being tricked into using your role on behalf of another of their customers, which makes their confused deputy problem yours to opt out of.

The profile form is usually better

role_arn and source_profile in ~/.aws/config make the SDK fetch and refresh the credentials for you, rather than handing you three environment variables that expire mid-task.

More aws tools

AWS IAM Policy Validator & Analyzer Valid JSON? And what does it grant? AWS IAM Policy Evaluator Is this actually allowed? AWS S3 Bucket Policy Analyzer Is this bucket actually public? AWS S3 Bucket Policy Generator Pick a pattern, get a safe policy AWS ARN Decoder Split it up, and check it is right AWS ECS Task Definition Analyzer Two roles, and they are not the same AWS S3 Lifecycle Policy Analyzer Minimum durations you still pay AWS S3 Presigned URL Decoder It dies with the session AWS Lambda Configuration Analyzer Memory is the CPU dial AWS SQS Visibility Timeout Calculator Six times the function timeout AWS EventBridge Pattern Tester Every leaf value is an array AWS DynamoDB Capacity Calculator Every index costs a write AWS Resource Name Validator A dot in a bucket breaks TLS AWS CLI Profile Analyzer The prefix rule is opposite AWS IAM Trust Policy Analyzer Account root means the whole account AWS Access Key ID Identifier AKIA never expires, ASIA does AWS KMS Key Policy Analyzer The one AWS mistake with no undo AWS Security Group Analyzer They cannot deny anything AWS Network ACL Return Traffic Checker Stateless, so replies need a rule

Elsewhere on the site

Terraform Validator & Formatter Kubernetes YAML Generator Kubernetes YAML Validator Kubernetes Rollout & Probe Timing