AWS STS AssumeRoleWithWebIdentity

What this API does in federated access

AWS STS AssumeRoleWithWebIdentity is the AWS role-exchange step that turns a validated web identity token into temporary AWS role credentials. In practice, it is the bridge between an external identity provider and AWS authorization, so the trust policy behind the role matters as much as the token itself.

This pattern is common in OIDC-based federation for CI/CD, apps, and cross-cloud workloads. The security value comes from removing static AWS keys, but the trade-off is that the role trust now depends on claims such as issuer, audience, and subject being tightly constrained.

How trust is established and scoped

The API does not authenticate a user directly, it validates whether AWS should trust the presented web identity token for a specific role. That makes the role trust policy the core control surface, especially when the identity provider is shared across many apps or repositories.

Good federation design narrows the allowed issuer and subject claims, and it avoids broad wildcard matching that lets unrelated workloads assume the same role. NHIMG's Workload Identity Federation Guide explains how token exchange, claim scoping and OIDC trust policies fit together across cloud platforms.

For AWS-specific federation patterns, AWS STS and AssumeRole Guide shows how session controls, role chaining and revocation practices affect the trust boundary around temporary credentials.

Why temporary credentials still need tight governance

Temporary credentials reduce standing exposure, but they are still powerful AWS access. If the upstream identity provider is compromised, or if the trust policy is loose enough to accept the wrong subject, the attacker can mint fresh role sessions without needing a long-lived secret.

This is why AssumeRoleWithWebIdentity is often part of a broader workload identity control set rather than a standalone feature. NHIMG's Cloud Workload Identity Guide frames AWS STS alongside other keyless workload identity patterns and highlights the operational difference between static keys and federated credentials.

Where teams are replacing secrets in delivery pipelines, OWASP NHI Top 10 NHI6 Insecure Cloud Deployment Configurations Guide connects that design choice to trust-policy pinning and least-privilege deployment roles.

Detection and exposure review

Exposure checks start with inventory, because organisations need to know which roles trust a web identity provider, which apps can request them, and whether any provider or subject claim is broader than intended. That review should include the external identity provider, the AWS role trust policy, and any workflow or platform that can request federation.

Operationally, suspicious federation often shows up as unusual role assumption from a new repository, tenant, environment, or subject claim. A focused audit can also reveal stale providers, unused roles, or trust drift that was never intended to be permanent. How to audit AWS IAM Roles Anywhere and OIDC identity providers is useful here because it centers on inventory, trust-policy checks and safe removal of idle federation.

When the API is used in GitHub or similar automation, GitHub Actions OIDC Federation Hardening Guide is a practical reference for detecting trust misbinding and enforcing exact subject claims.

Threat patterns and failure modes

The main failure mode is trust abuse rather than token cracking. An attacker who can alter the trusted identity provider, tamper with claims, or exploit an overly permissive trust policy can repeatedly exchange web identity tokens for fresh AWS credentials and preserve access even after a workflow or host is reimaged.

That makes this API attractive for persistence, lateral movement, and stealthy cloud access because the resulting sessions look like legitimate federation. The issue is not just credential theft, it is the ability to keep re-establishing valid access through a trusted authentication path.

For a broader adversary view of this abuse pattern, MITRE ATT&CK T1199 Trusted Relationship Guide maps how trusted third-party relationships become an initial access and persistence path.

Cross-cloud workload identity federation is also relevant when the same trust assumptions span more than one cloud, because the blast radius grows if the federation boundary is misconfigured in one place and reused elsewhere.

Risk and Threat Considerations

AssumeRoleWithWebIdentity reduces static-key exposure, but it also concentrates trust in the identity provider and the role trust policy. If either is too broad, compromised, or poorly reviewed, an attacker can keep issuing fresh temporary credentials and bypass many of the controls that normally limit long-lived access.

Failure mechanism: A malicious or misconfigured identity provider, or a trust policy with weak claim conditions, lets an untrusted token exchange for valid AWS role credentials and turns federation into a persistence channel.

Impact: The attacker can obtain repeated short-lived access, evade key rotation benefits, and sustain access to AWS resources without needing a stored AWS secret.

Practitioner Guidance

What to watch for: Treat the trust policy, not just the token, as the object under control. The useful question is whether the role only accepts the exact issuer, audience and subject values that were intended for that workload or pipeline.

Governance implication: Own this as a federation boundary, with clear review for every role that can be assumed through web identity. If the role is shared across environments or repositories, the subject scoping and revocation process need the same level of control as any other privileged access path.

Practitioner takeaway: The safer the federation model, the more narrowly each AWS role should map to one workload, one claim pattern, and one revocation path.

Related resources from NHI Mgmt Group

• How should security teams use AWS STS to reduce standing access in cloud environments?
• What is the difference between AWS STS and permanent IAM credentials?
• How should teams design AWS application access when Cognito Identity Pools, STS, and IAM roles all participate in the credential flow?
• Why does using temporary credentials through STS reduce risk compared with long-lived AWS credentials?