Join our Newsletter — 33% off our NHI Course
Home› Guides› AWS STS and AssumeRole Guide: Role Chaining, Session…
Guide Cloud & Workload Identity

AWS STS and AssumeRole Guide: Role Chaining, Session Policies, External ID and Source Identity

PDF for newsletter subscribers · free to read online

← All guides
By NHI Mgmt Group, edited by Lalit Choda Updated 8 November 2026 14 min read
On this page

Almost every non-human identity in AWS ends up as an AWS STS session, so the way roles are assumed, chained, tagged and revoked decides whether a stolen credential is a contained incident or an organisation-wide one. This guide covers the STS operations, trust policy conditions for cross-account and federated access, role chaining, session policies, session tags, source identity, logging and revocation. It builds on the policy fundamentals in the AWS IAM Policies and Roles Guide and does not repeat them. It is for cloud security engineers, platform teams and anyone reviewing how pipelines, workloads and third parties reach AWS. Parameter limits come from the STS API reference and IAM user guide, checked on 27 October 2026.

This is an independent guide from NHI Mgmt Group, based on AWS's public documentation as of November 2026. It is not sponsored or reviewed by AWS. Product features change, so confirm settings against AWS's current documentation.

Key takeaways

  • Every role session is a temporary credential with an ASIA access key, a session token and a lifetime between 15 minutes and 12 hours; the trust policy decides who can mint one.
  • Role chaining caps sessions at one hour and makes attribution harder, so carry identity through the chain with source identity and transitive tags.
  • External ID solves the confused deputy for third parties: the vendor generates a unique value per customer and your trust policy requires it.
  • Session policies and session tags narrow access per session, but unrestricted sts:TagSession lets callers choose the tags your ABAC policies trust.
  • Revocation is a deny on token issue time, not a delete: disabling the caller does not end sessions already issued.

How identity and access work in AWS STS

AWS Security Token Service issues temporary security credentials: an access key ID beginning ASIA, a secret key and a session token. A principal never "becomes" a role; it asks STS for a session of that role, and STS checks the role's trust policy (and for AssumeRole, the caller's identity policy) before issuing it. The session's permissions are the role's permissions, optionally narrowed by session policies. See the AWS IAM Policies and Roles Guide for policy evaluation.

The STS operations

OperationCallerTypical NHI useDurationNotes
AssumeRoleIAM user or existing role session (signed request)Cross-account automation, third-party access, role chaining900 to 43,200 seconds, default 3,600, capped by the role's maximum session durationSupports external ID, MFA, session policies, tags, source identity
AssumeRoleWithWebIdentityHolder of a JWT from an OIDC provider (unsigned request)CI/CD (GitHub Actions, GitLab), Kubernetes service accounts, other cloudsUp to the role's maximumSecurity depends entirely on trust policy claim conditions
AssumeRoleWithSAMLUser authenticated by a SAML 2.0 IdP (unsigned request)Workforce federation outside IAM Identity Center, emergency accessUp to the role's maximumPass session policies only through a trusted intermediary
GetSessionTokenIAM user with long-term keysAdding MFA state to an IAM user's API calls15 minutes to 36 hours, default 12 hours; 1 hour for rootA sign that long-term keys are still in use
GetFederationTokenIAM user with long-term keysLegacy broker patterns15 minutes to 36 hours, default 12 hoursNo permissions unless a session policy is passed; prefer roles

Sessions created by IAM Identity Center permission sets use the same machinery; their specifics are in the AWS IAM Identity Center Guide. Workloads outside AWS that hold X.509 certificates use the AWS IAM Roles Anywhere Security Guide path.

Key AssumeRole parameters

ParameterLimit (STS API reference)Security use
RoleSessionNameRequired, 2 to 64 charactersAppears in the assumed-role ARN and CloudTrail; set it to something attributable (job ID, user)
DurationSeconds900 to 43,200; fails above 3,600 when chainingShortest workable session
ExternalId2 to 1,224 charactersConfused deputy protection for third parties
SerialNumber and TokenCodeMFA device and 6-digit codeSatisfy aws:MultiFactorAuthPresent for human-driven elevation
Policy and PolicyArnsUp to 10 managed policy ARNs; 2,048 plaintext characters combinedSession policies that narrow the role
Tags and TransitiveTagKeysUp to 50 tags; keys 128 and values 256 charactersABAC attributes for the session
SourceIdentityCannot begin with aws:; fixed once setCarries the original human or workload identity through chains

Session policies and tags count towards the packed session token size, so a call can fail with PackedPolicyTooLarge even inside the individual limits. The response field SessionTokenUtilization shows how close you are; PackedPolicySize is deprecated.

Admin roles and privileged access

Privileged roles are where STS design matters most, because the trust policy is the only thing standing between a compromised caller and administrator credentials.

Trust policy conditions for privileged roles

  • Name exact principals: trust a specific role ARN, not the account root, where you can. A trust policy cannot use a wildcard inside a principal ARN, so where you trust the account, narrow it with aws:PrincipalArn, aws:PrincipalOrgID or tag conditions.
  • Require MFA for humans: "Bool": {"aws:MultiFactorAuthPresent": "true"} on roles people elevate into with AssumeRole.
  • Require source identity: add sts:SetSourceIdentity to the trust policy and condition on sts:SourceIdentity so every privileged session carries a named actor.
  • Short maximum session duration: one hour for administrative roles; the maximum session duration setting can be lowered on the role itself.
  • Restrict who can edit trust policies: iam:UpdateAssumeRolePolicy on a privileged role is itself administrator access. Guard it with SCPs or permissions boundaries; see the AWS Organizations and SCPs Guide.

Role chaining

Role chaining is using one role session to assume another. AWS limits a chained session to one hour, regardless of either role's maximum, and a DurationSeconds above 3,600 makes the call fail. Chaining is normal (a pipeline role assumes a deployment role in each target account), but each hop drops context: the second role's CloudTrail entries show only the first role's session, not the person or job behind it. Two features restore that context.

  • Source identity: set once, it persists through every hop and cannot be changed during the session; a later AssumeRole with a different value is denied. It is recorded in requestParameters.sourceIdentity on the assume event and in userIdentity.sessionContext.sourceIdentity on every later call. Cross-account chains need sts:SetSourceIdentity in both the caller's permissions and the target trust policy.
  • Transitive session tags: tags marked transitive are passed to every later session in the chain. Role tags cannot be made transitive, so pass the attribute as a session tag. Passing a key that matches an inherited transitive tag fails.

Integrations, API tokens and service accounts

Third parties and the confused deputy

When a SaaS vendor assumes a role in your account, the role ARN is not a secret. Without further protection, another customer of the same vendor could give the vendor your ARN and have it act on your account: the confused deputy. The fix is sts:ExternalId. The third party generates the value, it must be unique among that vendor's customers and controlled by the vendor, and your trust policy requires it with StringEquals. A value you invent yourself defeats the point, because the vendor cannot guarantee it is unique. For the broader pattern in agents and services, see the Confused Deputy in AI Agents Guide.

The cross-service equivalent applies when an AWS service principal (for example cloudtrail.amazonaws.com) writes to your resources. Use aws:SourceArn, aws:SourceAccount, aws:SourceOrgID or aws:SourceOrgPaths in the resource policy, or enforce it centrally with a resource control policy as described in the AWS Resource Control Policies and Data Perimeter Guide.

OIDC federation for pipelines and workloads

AssumeRoleWithWebIdentity requests are unsigned: anyone holding a valid token from the trusted issuer can call it, so the trust policy's claim conditions are the whole control. For shared OIDC providers, where one issuer URL serves many organisations, IAM now refuses to create or update a trust policy without an identity-provider control and returns MalformedPolicyDocument. The required claim is sub or job_workflow_ref for GitHub Actions, sub for GitLab and Terraform Cloud, and aud for Amazon Cognito. Existing roles are not re-evaluated until their trust policy is next edited, so older roles may still be open.

Trust conditionEffectRisk level
sub equals repo:org/repo:environment:productionOnly jobs in that repository's protected environmentLow
sub equals repo:org/repo:ref:refs/heads/mainOnly the main branch of one repositoryLow to moderate
sub like repo:org/repo:*Any branch, tag or pull request in the repositoryHigh for privileged roles
sub like repo:org/*Every repository in the organisationVery high
Only aud checkedAny workflow anywhere that can mint a token for that audienceCritical

See the Workload Identity Federation Guide for the cross-cloud design.

Session policies for brokers and agents

A session policy can only narrow: the session's permissions are the intersection of the role's identity policy and the session policies, and an explicit deny in a resource policy still applies. That makes session policies the right tool for a broker that assumes a broad role on behalf of many tenants or tasks, such as a job runner or an AI agent gateway, and passes a per-task policy scoped to one bucket prefix or table. Pass session policies with AssumeRoleWithSAML only through a trusted intermediary, because the unsigned request could be altered to drop them.

Session tags and ABAC

Session tags feed aws:PrincipalTag, which ABAC policies trust. Passing them requires sts:TagSession in the trust policy, and every role connected to an IdP that sends tags must allow it or the assume call fails. If the trust policy allows sts:TagSession without conditions, the caller chooses the tags. Constrain them with aws:RequestTag/<key> (allowed values), aws:TagKeys (allowed keys) and sts:TransitiveTagKeys (which keys may be transitive). New session tags override existing session tags with the same key regardless of case.

Logging and detection

STS calls are management events in AWS CloudTrail. A cross-account AssumeRole is logged in both accounts with the same sharedEventID: the caller's account shows the full caller identity, while the role's account shows only the caller's account and principal ID. Denied cross-account STS requests are not logged in the target account, so failed attempts against your roles are invisible there. Requests to the global endpoint carry additionalEventData.RequestDetails.endpointType of global and are logged in US East (N. Virginia); regional endpoint calls are logged in the serving Region, so collect every Region. See the AWS CloudTrail Guide.

SignalWhere to lookWhy it matters
GetCallerIdentity from an unfamiliar IP or ASNCloudTrail, any accountThe usual first call when testing a stolen key
AssumeRole into privileged roles without sourceIdentityrequestParametersUnattributed elevation
AssumeRoleWithWebIdentity with a new subuserIdentity and request parametersNew repository or branch using a role
UpdateAssumeRolePolicyIAM eventsTrust changes are a persistence technique
ASIA key used from two networksuserIdentity.accessKeyId and sourceIPAddressSession theft
Sessions with mfaAuthenticated false on human rolessessionContext.attributesMFA condition missing

Correlate later activity to a session by the temporary access key ID returned in responseElements.credentials and seen in userIdentity.accessKeyId. Relevant ATT&CK techniques are T1078.004 Valid Accounts: Cloud Accounts, T1550.001 Application Access Token, T1528 Steal Application Access Token and T1098.003 Additional Cloud Roles.

Revoking sessions

You cannot delete an issued session. The IAM console's Revoke active sessions action attaches an inline policy named AWSRevokeOlderSessions that denies everything to sessions issued before the revocation time (plus about 30 seconds for propagation). You can do the same with a deny on aws:TokenIssueTime. It needs iam:PutRolePolicy, affects every user of the role, does not work on service-linked roles, and does not touch requests signed with long-term IAM user keys, which must be deactivated instead. IAM Identity Center roles cannot be edited in IAM, so revoke those sessions in Identity Center.

Metrics

  • Privileged role sessions with source identity: target 100 percent.
  • Third-party roles with ExternalId: target 100 percent, checked by IAM Access Analyzer or config rules.
  • OIDC roles with wildcard sub: target zero for any role with write access.
  • Calls signed with long-term keys: share of API calls using AKIA keys, trending down.
  • Mean session duration on administrative roles: at or below one hour.

Hardening baseline

  1. Inventory trust: export every role's trust policy and classify principals as same account, same organisation, third party, SAML or OIDC. IAM Access Analyzer external access findings help; see the IAM Access Analyzer Guide.
  2. Fix the high-risk classes first: OIDC roles without a tight sub, third-party roles without ExternalId, and roles trusting whole external accounts.
  3. Introduce source identity: configure the IdP (SAML attribute https://aws.amazon.com/SAML/Attributes/SourceIdentity or the JWT claim https://aws.amazon.com/source_identity) and pipelines to set it, add sts:SetSourceIdentity to trust policies, then require it with a condition. Roll out in audit first by alerting on sessions without it.
  4. Constrain session tags with aws:TagKeys and aws:RequestTag before relying on them for ABAC.
  5. Shorten sessions: lower maximum session duration on administrative and deployment roles; test long-running jobs in a pilot account, since a job that outlives its session will fail.
  6. Prefer regional STS endpoints close to the workload, with failover to another Region.
  7. Prepare revocation: document who can run Revoke active sessions and rehearse it. Rollback for a trust change is reapplying the previous trust document from version control.

Small versus large organisations: a small estate can name exact role ARNs in each trust policy. A large organisation should standardise trust with aws:PrincipalOrgID or aws:PrincipalOrgPaths, enforce identity perimeters with RCPs, and generate trust policies from code so that conditions such as ExternalId cannot be forgotten.

Common misconfigurations

  • Trusting the account root without conditions: any principal in that account with sts:AssumeRole permission can use the role.
  • Wildcard OIDC subjects: a pull request workflow in any repository gets production credentials.
  • Customer-chosen external IDs: a guessable or reused value does not prevent the confused deputy.
  • Unconditioned sts:TagSession: callers pick the tag values your ABAC conditions trust.
  • Long-term keys used to call AssumeRole: the role is short-lived but the key that unlocks it is not. A static key works from anywhere; see the AWS Access Keys Security Guide.
  • Believing a disabled caller ends the session: issued credentials last until expiry unless you revoke on token issue time.

Framework mapping

FrameworkReferenceSTS control
NIST CSF 2.0PR.AA-01, PR.AA-03, PR.AA-05Workload identities, federated authentication, least privilege per session
NIST SP 800-53 Rev. 5AC-6, IA-5, IA-9, AU-2, AC-2Session policies, short-lived authenticators, service authentication, CloudTrail, account management
CIS Controls v8.15 Account Management, 6 Access Control Management, 8 Audit Log ManagementRole inventory, MFA on elevation, STS logging
ISO/IEC 27001:2022 Annex A5.15, 5.17, 8.2, 8.15Access control, authentication information, privileged access, logging
MITRE ATT&CK v20T1078.004, T1550.001, T1528, T1098.003Detection of stolen sessions and trust changes

Practitioner checklist

  • Export and classify every role trust policy by principal type.
  • Require sts:ExternalId on every third-party role, using the vendor's value.
  • Tighten every OIDC trust policy to an exact sub for roles with write access.
  • Require source identity on privileged and deployment roles.
  • Condition sts:TagSession with aws:TagKeys and aws:RequestTag.
  • Set administrative role maximum sessions to one hour and plan for the one hour chaining cap.
  • Restrict iam:UpdateAssumeRolePolicy on privileged roles.
  • Collect CloudTrail from every Region and alert on GetCallerIdentity from new networks.
  • Rehearse Revoke active sessions and long-term key deactivation.

Standards and references

Related NHI Mgmt Group resources: AWS IAM Policies and Roles Guide · Workload Identity Federation Guide · AWS IAM Identity Center Guide · Cloud Workload Identity Guide · AWS Access Keys Security Guide

PDF for subscribers

Take this guide with you

Every section, table and checklist in one PDF, with links to the sources and related guides. Subscribe to our weekly NHI & AI Identity Journal and we’ll email you a download link.

Free weekly newsletter

Subscribe to the NHI & AI Identity Journal

The latest on NHI and Agentic AI security – articles, research, breaches, news and events every week.

Bonus 33% off our NHI Course when you subscribe.

NHIMG Editorial Note
Researched and written by the NHI Mgmt Group editorial team using AI tools, under the editorial direction of Lalit Choda. Facts are drawn from the sources listed on this page and checked by our automated quality process. Last updated 8 November 2026. Spotted an error? Use our contact page.
NHI Mgmt Group, the independent authority on Non-Human Identity, IAM and Agentic AI security. nhimg.org

PDF Downloads for Newsletter Subscribers

Get the guide

Enter your details and we’ll email you a download link.

The full guide is free to read online. The PDF is a thank you for subscribing.

Fill in all fields marked * and tick the PDF box to continue.