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:TagSessionlets 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
| Operation | Caller | Typical NHI use | Duration | Notes |
|---|---|---|---|---|
AssumeRole | IAM user or existing role session (signed request) | Cross-account automation, third-party access, role chaining | 900 to 43,200 seconds, default 3,600, capped by the role's maximum session duration | Supports external ID, MFA, session policies, tags, source identity |
AssumeRoleWithWebIdentity | Holder of a JWT from an OIDC provider (unsigned request) | CI/CD (GitHub Actions, GitLab), Kubernetes service accounts, other clouds | Up to the role's maximum | Security depends entirely on trust policy claim conditions |
AssumeRoleWithSAML | User authenticated by a SAML 2.0 IdP (unsigned request) | Workforce federation outside IAM Identity Center, emergency access | Up to the role's maximum | Pass session policies only through a trusted intermediary |
GetSessionToken | IAM user with long-term keys | Adding MFA state to an IAM user's API calls | 15 minutes to 36 hours, default 12 hours; 1 hour for root | A sign that long-term keys are still in use |
GetFederationToken | IAM user with long-term keys | Legacy broker patterns | 15 minutes to 36 hours, default 12 hours | No 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
| Parameter | Limit (STS API reference) | Security use |
|---|---|---|
RoleSessionName | Required, 2 to 64 characters | Appears in the assumed-role ARN and CloudTrail; set it to something attributable (job ID, user) |
DurationSeconds | 900 to 43,200; fails above 3,600 when chaining | Shortest workable session |
ExternalId | 2 to 1,224 characters | Confused deputy protection for third parties |
SerialNumber and TokenCode | MFA device and 6-digit code | Satisfy aws:MultiFactorAuthPresent for human-driven elevation |
Policy and PolicyArns | Up to 10 managed policy ARNs; 2,048 plaintext characters combined | Session policies that narrow the role |
Tags and TransitiveTagKeys | Up to 50 tags; keys 128 and values 256 characters | ABAC attributes for the session |
SourceIdentity | Cannot begin with aws:; fixed once set | Carries 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:PrincipalOrgIDor tag conditions. - Require MFA for humans:
"Bool": {"aws:MultiFactorAuthPresent": "true"}on roles people elevate into withAssumeRole. - Require source identity: add
sts:SetSourceIdentityto the trust policy and condition onsts:SourceIdentityso 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:UpdateAssumeRolePolicyon 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
AssumeRolewith a different value is denied. It is recorded inrequestParameters.sourceIdentityon the assume event and inuserIdentity.sessionContext.sourceIdentityon every later call. Cross-account chains needsts:SetSourceIdentityin 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 condition | Effect | Risk level |
|---|---|---|
sub equals repo:org/repo:environment:production | Only jobs in that repository's protected environment | Low |
sub equals repo:org/repo:ref:refs/heads/main | Only the main branch of one repository | Low to moderate |
sub like repo:org/repo:* | Any branch, tag or pull request in the repository | High for privileged roles |
sub like repo:org/* | Every repository in the organisation | Very high |
Only aud checked | Any workflow anywhere that can mint a token for that audience | Critical |
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.
| Signal | Where to look | Why it matters |
|---|---|---|
GetCallerIdentity from an unfamiliar IP or ASN | CloudTrail, any account | The usual first call when testing a stolen key |
AssumeRole into privileged roles without sourceIdentity | requestParameters | Unattributed elevation |
AssumeRoleWithWebIdentity with a new sub | userIdentity and request parameters | New repository or branch using a role |
UpdateAssumeRolePolicy | IAM events | Trust changes are a persistence technique |
| ASIA key used from two networks | userIdentity.accessKeyId and sourceIPAddress | Session theft |
Sessions with mfaAuthenticated false on human roles | sessionContext.attributes | MFA 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
AKIAkeys, trending down. - Mean session duration on administrative roles: at or below one hour.
Hardening baseline
- 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.
- Fix the high-risk classes first: OIDC roles without a tight
sub, third-party roles withoutExternalId, and roles trusting whole external accounts. - Introduce source identity: configure the IdP (SAML attribute
https://aws.amazon.com/SAML/Attributes/SourceIdentityor the JWT claimhttps://aws.amazon.com/source_identity) and pipelines to set it, addsts:SetSourceIdentityto trust policies, then require it with a condition. Roll out in audit first by alerting on sessions without it. - Constrain session tags with
aws:TagKeysandaws:RequestTagbefore relying on them for ABAC. - 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.
- Prefer regional STS endpoints close to the workload, with failover to another Region.
- 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:AssumeRolepermission 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
| Framework | Reference | STS control |
|---|---|---|
| NIST CSF 2.0 | PR.AA-01, PR.AA-03, PR.AA-05 | Workload identities, federated authentication, least privilege per session |
| NIST SP 800-53 Rev. 5 | AC-6, IA-5, IA-9, AU-2, AC-2 | Session policies, short-lived authenticators, service authentication, CloudTrail, account management |
| CIS Controls v8.1 | 5 Account Management, 6 Access Control Management, 8 Audit Log Management | Role inventory, MFA on elevation, STS logging |
| ISO/IEC 27001:2022 Annex A | 5.15, 5.17, 8.2, 8.15 | Access control, authentication information, privileged access, logging |
| MITRE ATT&CK v20 | T1078.004, T1550.001, T1528, T1098.003 | Detection of stolen sessions and trust changes |
Practitioner checklist
- Export and classify every role trust policy by principal type.
- Require
sts:ExternalIdon every third-party role, using the vendor's value. - Tighten every OIDC trust policy to an exact
subfor roles with write access. - Require source identity on privileged and deployment roles.
- Condition
sts:TagSessionwithaws:TagKeysandaws:RequestTag. - Set administrative role maximum sessions to one hour and plan for the one hour chaining cap.
- Restrict
iam:UpdateAssumeRolePolicyon privileged roles. - Collect CloudTrail from every Region and alert on
GetCallerIdentityfrom new networks. - Rehearse Revoke active sessions and long-term key deactivation.
Standards and references
- AWS: STS API Reference, AssumeRole
- AWS: The confused deputy problem
- AWS: Monitor and control actions taken with assumed roles (source identity)
- AWS: Pass session tags in AWS STS
- AWS: Identity-provider controls for shared OIDC providers
- AWS: Revoke IAM role temporary security credentials
- AWS: Logging IAM and AWS STS API calls with AWS CloudTrail
- MITRE ATT&CK: Use Alternate Authentication Material: Application Access Token
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