Let AWS workloads call external services with IAM-issued tokens

What AWS signs and what the receiver decides

An AWS workload can authenticate to an external service without that service's API key by asking AWS STS for a signed JSON Web Token and presenting the token instead. The workload calls GetWebIdentityToken with the IAM role credentials it already has. STS returns a JWT signed with keys published under an issuer URL unique to the AWS account, and the external service verifies the signature against those public keys before deciding what the caller may do. AWS calls this IAM outbound identity federation. It was announced on November 19, 2025, for all commercial Regions, the AWS GovCloud (US) Regions and the China Regions. ^[1][10]

The split of responsibility is the important part. AWS controls who can mint a token, for which audience, for how long and with which signing algorithm, and it logs each request. Everything after issuance belongs to the receiver. The token is a bearer credential that proves which IAM principal asked for it, and only the external service's validation and mapping rules turn that proof into access. A receiver that checks the signature but ignores the audience, or trusts every subject from your issuer, has rebuilt a shared API key in a different format. ^[1][7]

Three conditions make the feature a good fit. The receiver must accept tokens from an OIDC issuer you configure, which Microsoft documents for AWS as a source for Entra workload identity federation and which a self-hosted API can implement with a standard JWT library. The workload must already run under an IAM role, so there is an AWS identity to assert. And the receiver must be able to map a role ARN, an organization ID or a tag to its own permissions. If a vendor accepts only static keys, outbound federation changes nothing until the vendor adds OIDC support. ^[2][11]

This guide covers the outbound direction only, with AWS as the issuer. Bringing an external token into AWS through AssumeRoleWithWebIdentity is a separate trust decision, and AWS states that tokens from GetWebIdentityToken cannot be used on that inbound path. ^[2]

How issuance works

Enablement is an account-level switch. An administrator turns it on under Account settings in the IAM console or calls EnableOutboundWebIdentityFederation, which the CLI exposes as aws iam enable-outbound-web-identity-federation. The response carries an IssuerIdentifier such as https://<unique-id>.tokens.sts.global.api.aws, and that URL hosts /.well-known/openid-configuration and /.well-known/jwks.json. A second enable call fails with FeatureEnabled (HTTP 409); GetOutboundWebIdentityFederationInfo returns the issuer URL whenever you need it again. Until the switch is on, token requests fail with OutboundWebIdentityFederationDisabled (HTTP 403). ^[2][12][3]

Each account has its own issuer. An organization whose workloads in ten accounts call the same SaaS API hands that API ten issuers to trust, unless it deliberately concentrates token minting in fewer accounts. Make that choice before enabling the feature widely, because the issuer list is the first thing every receiver checks. ^[2][13]

The workload then calls GetWebIdentityToken on a Regional STS endpoint; the API is not available on the global endpoint. Audience (one to ten strings of up to 1,000 characters each) and SigningAlgorithm (ES384 or RS256) are required. DurationSeconds is optional, accepts 60 to 3,600 and defaults to 300, and Tags adds up to 50 custom claims. The response returns WebIdentityToken and Expiration. ^[3]

The Regional requirement interacts with SDK defaults. AWS's SDK reference shows that when no Region is configured, AWS CLI v2, Boto3 and the SDK for Kotlin fall back to the global STS endpoint, while the Go v2, Java 2.x and Rust SDKs fail the request. A container that never needed a Region for other STS calls can break on its first token request, so set the Region explicitly in the workload's configuration. ^[14]

Two errors deserve explicit handling. JWTPayloadSizeExceeded (HTTP 400) means the request tags made the token too large. SessionDurationEscalation (HTTP 403) means the requested lifetime would run past the expiry of the caller's own role session, because STS will not issue a token that outlives the credentials that asked for it. ^[3]

# Example: one-time account setup by an administrator.
aws iam enable-outbound-web-identity-federation
aws iam get-outbound-web-identity-federation-info

# Example: the workload requests a token from a Regional STS endpoint.
aws sts get-web-identity-token \
  --region eu-west-1 \
  --audience "https://reports.example.com" \
  --signing-algorithm ES384 \
  --duration-seconds 300 \
  --query WebIdentityToken --output text

Source. Conceptual sequence based on the AWS outbound identity federation overview, getting started guide and GetWebIdentityToken API reference. ^[1][2][3]

Method. Conceptual ordering of the documented flow. Step 2 summarizes request validation; step 6 combines AWS's essential claim checks with RFC 8725 algorithm pinning.

Accessible table and figure data

Figure 1 accessible table

Step	From	To	Message
1	Workload role	AWS STS (Regional)	GetWebIdentityToken with audience, algorithm and lifetime
2	AWS STS (Regional)	AWS STS (Regional)	Check enablement and IAM conditions
3	AWS STS (Regional)	Workload role	Signed JWT and Expiration
4	Workload role	External service	Send the JWT, often in the Authorization header
5	External service	Issuer endpoints	Fetch discovery and JWKS for the pinned issuer
6	External service	External service	Verify signature, alg, iss, aud, exp, sub and claims
7	External service	Workload role	Its own short-lived credential or the API response

Figure 1 accessible table

Step	From	To	Message
1	Workload role	AWS STS (Regional)	GetWebIdentityToken with audience, algorithm and lifetime
2	AWS STS (Regional)	AWS STS (Regional)	Check enablement and IAM conditions
3	AWS STS (Regional)	Workload role	Signed JWT and Expiration
4	Workload role	External service	Send the JWT, often in the Authorization header
5	External service	Issuer endpoints	Fetch discovery and JWKS for the pinned issuer
6	External service	External service	Verify signature, alg, iss, aud, exp, sub and claims
7	External service	Workload role	Its own short-lived credential or the API response

Download imageDownload table CSV

What the token asserts

The token follows RFC 7519. Its standard claims are iss (the account issuer URL), aud (the requested audience), sub (the ARN of the requesting IAM principal), iat, exp and jti. AWS's example sub is a role ARN, arn:aws:iam::123456789012:role/DataProcessingRole, rather than an assumed-role session ARN, which suggests that every session of a role presents the same subject. Treat the role as the unit of identity at the receiver, and give workloads that need different external permissions different roles. ^[13]

AWS-specific claims sit under the namespace key https://sts.amazonaws.com/. Identity claims include aws_account, source_region, org_id, ou_path and principal_tags. Session context claims appear when they apply, among them ec2_source_instance_arn, ec2_instance_source_vpc, ec2_role_delivery, lambda_source_function_arn, source_identity, federated_provider and original_session_exp. AWS's claims table maps most of them to the IAM condition key that carries the same value inside AWS, such as aws:PrincipalOrgID for org_id, and warns that not every claim is present in every token. ^[13]

Those claims do not carry equal weight. AWS fills aws_account, org_id, ou_path and the compute context from its own records. request_tags contains whatever the caller passed in Tags, limited only by aws:RequestTag and aws:TagKeys conditions on sts:GetWebIdentityToken and sts:TagGetWebIdentityToken. principal_tags sits between the two: when a principal has both principal tags and session tags, AWS puts the session tags in the token, so whoever assumed the role with session tags shaped that claim. Base authorization on AWS-derived claims, and use request tags for labels such as a job ID unless your IAM policy pins their values. ^[13][7]

Control token issuance with IAM

A principal needs sts:GetWebIdentityToken to request a token, plus sts:TagGetWebIdentityToken if it passes tags. Three STS condition keys shape the request: sts:IdentityTokenAudience limits audiences, sts:DurationSeconds caps lifetime and sts:SigningAlgorithm fixes the algorithm. aws:RequestTag/${TagKey} and aws:TagKeys constrain tags. The service reference lists no resource type for the action, so Resource is * and the conditions do the scoping. ^[7][15][5]

Audience needs care because it is multivalued. The service reference types sts:IdentityTokenAudience as ArrayOfString, and one request can carry up to ten audiences. AWS's sample policies on the access control page use ForAnyValue:StringEquals, which matches when at least one requested value is on the list, and IAM's own evaluation table shows such a condition matching a request that also contains an unlisted value. A caller could therefore add an unapproved audience next to an approved one and receive a token the unapproved receiver also accepts. ForAllValues:StringEquals requires every requested audience to be listed. Pair it with a Null check set to false, because IAM documents that ForAllValues also returns true when the key is absent. ^[5][3][7][6]

Lifetime and algorithm are simpler. NumericLessThanEquals on sts:DurationSeconds caps the lifetime. The documentation does not say whether that key is present when a caller omits DurationSeconds and takes the 300-second default, so have callers pass the value explicitly and test the omitted case before depending on it. StringEquals on sts:SigningAlgorithm pins one algorithm; AWS recommends ES384 for security and performance and RS256 for receivers without ECDSA support. ^[3][15][2]

Grant the permission to the specific roles that call external services, not to a broad role shared by unrelated functions. The receiver sees the role ARN as the subject, so every function behind a shared role gets the same external identity and the same external permissions. ^[13][7]

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "MintTokensForTheReportsApiOnly",
      "Effect": "Allow",
      "Action": "sts:GetWebIdentityToken",
      "Resource": "*",
      "Condition": {
        "ForAllValues:StringEquals": {
          "sts:IdentityTokenAudience": [
            "https://reports.example.com"
          ]
        },
        "Null": {
          "sts:IdentityTokenAudience": "false"
        },
        "NumericLessThanEquals": {
          "sts:DurationSeconds": 300
        },
        "StringEquals": {
          "sts:SigningAlgorithm": "ES384"
        }
      }
    },
    {
      "Sid": "AllowOnlyTheJobIdTag",
      "Effect": "Allow",
      "Action": "sts:TagGetWebIdentityToken",
      "Resource": "*",
      "Condition": {
        "ForAllValues:StringEquals": {
          "aws:TagKeys": [
            "job-id"
          ]
        },
        "Null": {
          "aws:TagKeys": "false"
        }
      }
    }
  ]
}

Guardrails above the role

Identity policies decide which roles may mint tokens; the account switch and organization policies decide whether any role can. The IAM operations behind the switch are EnableOutboundWebIdentityFederation, DisableOutboundWebIdentityFederation and GetOutboundWebIdentityFederationInfo. Disabling stops new tokens, but the API reference states that it does not affect tokens issued before. The documentation does not say whether re-enabling restores the same issuer URL, so read it back before telling receivers that nothing changed. ^[12][4]

AWS lists service control policies, resource control policies and VPC endpoint policies alongside identity policies as ways to control the feature. An SCP is the natural place for organization-wide ceilings: deny the switch to everyone except a platform role, deny audiences outside an approved list and cap lifetime below the API maximum. A deny with ForAnyValue:StringNotEquals rejects any request that includes an unlisted audience, which closes the multivalued gap even in accounts where a team wrote its identity policy with ForAnyValue. ^[7][6]

A VPC endpoint policy on an STS interface endpoint can restrict which principals call GetWebIdentityToken through that endpoint. It does not control where the token goes next. Once issued, the JWT leaves AWS in an ordinary HTTPS request, and only the receiver's checks constrain it. ^[7]

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "OnlyThePlatformRoleChangesTheSwitch",
      "Effect": "Deny",
      "Action": [
        "iam:EnableOutboundWebIdentityFederation",
        "iam:DisableOutboundWebIdentityFederation"
      ],
      "Resource": "*",
      "Condition": {
        "ArnNotLike": {
          "aws:PrincipalArn": "arn:aws:iam::*:role/platform-identity-admin"
        }
      }
    },
    {
      "Sid": "DenyUnapprovedAudiences",
      "Effect": "Deny",
      "Action": "sts:GetWebIdentityToken",
      "Resource": "*",
      "Condition": {
        "ForAnyValue:StringNotEquals": {
          "sts:IdentityTokenAudience": [
            "https://reports.example.com",
            "api://AzureADTokenExchange"
          ]
        }
      }
    },
    {
      "Sid": "DenyTokensLongerThanFifteenMinutes",
      "Effect": "Deny",
      "Action": "sts:GetWebIdentityToken",
      "Resource": "*",
      "Condition": {
        "NumericGreaterThan": {
          "sts:DurationSeconds": 900
        }
      }
    }
  ]
}

Source. Conceptual matrix based on AWS outbound identity federation policy documentation, the STS API reference, IAM condition key documentation and the Disable API reference. ^[7][3][6][4]

Method. Conceptual summary of documented controls. The Does not column records documented limits or direct consequences of them; it is not an exhaustive list.

Accessible table and figure data

Figure 2 accessible table

Control	Limits	Does not
sts:GetWebIdentityToken	Which roles can mint tokens	Decide what the receiver grants
sts:IdentityTokenAudience	aud values, up to 10 per request	Block extra audiences under ForAnyValue
sts:DurationSeconds	Requested lifetime, 60 to 3600 seconds	Revoke a token already issued
sts:SigningAlgorithm	ES384 or RS256	Make the receiver pin the algorithm
sts:TagGetWebIdentityToken	Which request tag keys and values	Make tag values trustworthy facts
Account enable switch	Whether the account mints at all	Invalidate tokens issued earlier
SCP deny statements	Ceilings across member accounts	Grant any permission
VPC endpoint policy	Principals calling through that endpoint	Control where the token is sent

Figure 2 accessible table

Control	Limits	Does not
sts:GetWebIdentityToken	Which roles can mint tokens	Decide what the receiver grants
sts:IdentityTokenAudience	aud values, up to 10 per request	Block extra audiences under ForAnyValue
sts:DurationSeconds	Requested lifetime, 60 to 3600 seconds	Revoke a token already issued
sts:SigningAlgorithm	ES384 or RS256	Make the receiver pin the algorithm
sts:TagGetWebIdentityToken	Which request tag keys and values	Make tag values trustworthy facts
Account enable switch	Whether the account mints at all	Invalidate tokens issued earlier
SCP deny statements	Ceilings across member accounts	Grant any permission
VPC endpoint policy	Principals calling through that endpoint	Control where the token is sent

Download imageDownload table CSV

What the external service must verify

AWS names four essential checks: sub matches the expected principal ARN pattern, exp has not passed, aud matches the receiver's value and iss is one of the issuer URLs you trust. RFC 8725, the JWT best current practice, adds two conditions that make those checks meaningful: the verifier, not the token, chooses which algorithms are acceptable, and the verification keys must belong to the issuer. The checklist below turns that into code-level rules. ^[2][8]

• Pin the issuer list. Compare iss exactly with the URLs you configured, as OIDC Discovery requires the issuer to be identical, and build the JWKS URL from the configured issuer rather than from anything inside the token. ^[2][16]
• Pin the algorithm. Accept only the algorithm your issuance policy requires and reject everything else, including none. AWS's sample JWKS lists both an EC key and an RSA key, so pinning one algorithm also enforces the issuance choice at the receiver. ^[2][8]
• Require your own audience. RFC 7519 says a recipient that does not identify itself with a value in aud must reject the token. Choose an identifier unique to this receiver; Microsoft Entra recommends api://AzureADTokenExchange for its federated credentials. ^[9][17]
• Check expiry with a small leeway. RFC 7519 allows leeway of usually no more than a few minutes for clock skew. AWS documents no nbf claim, so do not require one. ^[9][13]
• Authorize on the subject and AWS-derived claims. Map exact role ARNs, and add org_id or ou_path so that an account which later leaves your organization stops matching even if its issuer is still on your list. ^[2][13]
• Decide on replay. The token is a bearer credential. jti is unique per token, and RFC 7519 notes it can be used to prevent replay, which only works if the receiver records each value until exp. ^[13][9]
• Cache keys. AWS recommends caching the JWKS rather than fetching it for every token. A common practice, not an AWS requirement, is to refetch when a token arrives with an unknown kid and to rate-limit those refetches. ^[2]

# Example verifier fragment for a self-hosted API. PyJWT 2.x with the crypto extra.
# Placeholder issuer, account, role and organization values.
import jwt

TRUSTED_ISSUER = "https://a1b2c3d4-0000-1111-2222-example00001.tokens.sts.global.api.aws"
EXPECTED_AUDIENCE = "https://reports.example.com"
ALLOWED_SUBJECTS = {"arn:aws:iam::111122223333:role/report-exporter"}
EXPECTED_ORG_ID = "o-exampleorg1"
MAX_LIFETIME_SECONDS = 900
AWS_CLAIMS = "https://sts.amazonaws.com/"

# Build the JWKS URL from the pinned issuer, never from the token.
jwks = jwt.PyJWKClient(TRUSTED_ISSUER + "/.well-known/jwks.json", cache_keys=True)
seen_jti = {}  # use a shared store that expires each entry at its exp

def verify(token: str) -> dict:
    signing_key = jwks.get_signing_key_from_jwt(token)
    claims = jwt.decode(
        token,
        signing_key.key,
        algorithms=["ES384"],  # pinned; never taken from the token header
        audience=EXPECTED_AUDIENCE,
        issuer=TRUSTED_ISSUER,
        leeway=30,
        options={"require": ["iss", "aud", "sub", "exp", "iat", "jti"]},
    )
    if claims["sub"] not in ALLOWED_SUBJECTS:
        raise PermissionError("subject not allowed")
    if claims["exp"] - claims["iat"] > MAX_LIFETIME_SECONDS:
        raise PermissionError("lifetime above local limit")
    if claims.get(AWS_CLAIMS, {}).get("org_id") != EXPECTED_ORG_ID:
        raise PermissionError("organization not allowed")
    if claims["jti"] in seen_jti:
        raise PermissionError("token already used")
    seen_jti[claims["jti"]] = claims["exp"]
    return claims

Hosted receivers do part of the work

When the receiver is a managed identity platform, its configuration replaces most of the code above. Microsoft Entra is the clearest documented case: its workload identity federation overview lists AWS workloads using IAM outbound identity federation as a supported source, exchanging the AWS JWT for a Microsoft access token. ^[11]

The federated credential holds an issuer, a subject and an audience, and Entra matches them case-sensitively against the token. Wildcards are not supported, an application or user-assigned managed identity can hold at most 20 federated credentials, and Microsoft warns that a credential with a mistyped subject is created without error and only fails at exchange time. Because the AWS subject is a role ARN, one Entra credential trusts one role in one account, and the 20-credential limit becomes a real constraint if many roles need the same Entra application. That is another reason to give each external integration its own small set of roles. ^[11][17][13]

Choose lifetimes on both sides

Three clocks meet in this design. The JWT lifetime comes from DurationSeconds: 60 seconds to one hour, five minutes by default, and AWS's own getting-started policy caps it at 300 seconds. That lifetime cannot exceed the remaining life of the role session that requested it, and the original_session_exp claim tells the receiver when that session ends. ^[3][2][13]

The API reference describes the token as proof of identity to be exchanged for credentials or short-lived tokens in the external service. That exchange starts the third clock, which AWS does not control. In a hypothetical integration where a five-minute JWT is exchanged for a 12-hour vendor session, the workload holds 12 hours of access, so set the receiver's session lifetime with the same care as DurationSeconds. ^[3]

Requesting a token is a single STS call, so a workload can request one per exchange or cache one and refresh it shortly before Expiration. Longer tokens buy little: nothing revokes an issued token, and disabling the feature leaves earlier tokens valid until they expire. The way to stop new tokens for a compromised workload is to stop its role from minting them. ^[3][4]

Source. GetWebIdentityToken API reference (DurationSeconds) and the getting started example IAM policy, accessed October 7, 2026. ^[3][2]

Method. Values copied from the cited AWS pages without transformation. The sample policy cap is an AWS example, not a service limit.

Accessible table and figure data

Figure 3 accessible table

Documented value	Seconds
API minimum	60
API default	300
AWS sample policy cap	300
API maximum	3600

Figure 3 accessible table

Documented value	Seconds
API minimum	60
API default	300
AWS sample policy cap	300
API maximum	3600

Download imageDownload table CSV

Rollout and monitoring

Roll out one integration at a time. Enable the feature in the account that runs the workload, record the issuer, and register it at the receiver with one role ARN as the allowed subject. Attach the identity policy, deploy the workload change behind a flag while the old API key still works, and watch both paths. When the token path has carried real traffic through at least one full cycle of the workload's slowest schedule, revoke the API key at the vendor first, then delete it from the secret store.

AWS states that token requests are logged in CloudTrail. Because the API runs only on Regional endpoints, its events land in the Region the workload called; the CloudTrail integration page notes that requests to the global endpoint are logged in US East (N. Virginia) and Regional requests in their own Region. A trail that covers all Regions sees both. Useful detections are GetWebIdentityToken calls from roles outside the approved list and EnableOutboundWebIdentityFederation in accounts where nobody planned it. AWS does not publish a sample event for this API, so confirm which request fields, such as the audience, appear in your trail before writing rules on them. ^[1][18]

CloudTrail shows that a role asked for a token. Only the receiver can show which token it accepted and what it issued in exchange. Log iss, sub, jti and the decision at the receiver so an investigation can join the two records. For verifiers that run inside AWS without internet egress, AWS added interface VPC endpoint support for the OIDC discovery and JWKS endpoints on September 25, 2026. ^[19]

Limits and alternatives

The feature removes a stored secret. It does not change the token's nature or the receiver's support, and these limits follow from the documentation.

• Bearer, not bound. Anyone who obtains the token before exp can present it to any receiver named in aud. Nothing in the documented claims binds it to a key held by the workload. ^[3][13]
• Outbound only. Tokens from GetWebIdentityToken are rejected by AssumeRoleWithWebIdentity, so they cannot carry identity from one AWS account into another. ^[2]
• Regional only. The API is unavailable on the global STS endpoint, which matters for SDKs that fall back to it without a Region. ^[3][14]
• Receiver support decides adoption. A service that cannot register a custom issuer still needs a static credential, and that credential needs rotation that reaches running processes. ^[2]
• No revocation. Disabling the feature or editing a policy does not invalidate tokens already issued, so short lifetimes are the containment control. ^[4]

Checks before the first token leaves AWS

Start at the receiver, not at AWS. Confirm that it can register a custom OIDC issuer and map an exact role ARN, an audience unique to it and your organization ID; if it cannot, stop there. Then give the calling workload its own role, enable the feature in that one account, and grant sts:GetWebIdentityToken with ForAllValues on the audience, a Null check, an explicit lifetime cap and a pinned algorithm. Put the audience and lifetime ceilings in an SCP so a later policy cannot loosen them. Keep tokens at the 300-second default or shorter, keep the receiver's exchanged session short, log jti on both sides, and revoke the old API key only after the token path has run through the workload's full schedule.