TIP context keys and runtime claims for IAM federation
Trusted identity propagation (TIP) for IAM federation attaches identity context to role sessions created through SAML or OpenID Connect (OIDC) federation. The context identifies the end user, which can be a human user or workload, and the authenticating external identity provider. It can also include selected claims for the current federation session. AWS represents each value with a context key, such as aws:OriginIdentity/Subject. This page defines these keys and their value sources. It also explains which values are required or optional, how AWS preserves the context through supported workflows, and where customers can use or inspect the context.
For the shared TIP model and other ways to establish TIP context, see Trusted identity propagation with IAM. For IAM federation configuration procedures, see Configure TIP for an IAM identity provider. For Region and partition availability, see Regional availability for TIP for IAM federation.
Understand the context established through IAM federation
TIP context can contain core origin identity, optional identity provider runtime claims, and directory references for group-based access. The following table identifies these three categories, the keys or namespaces used for each category, and what each category represents.
Context category |
Keys or namespace |
What it represents |
|---|---|---|
Core origin identity |
|
The end user that originated the workflow, the authenticating identity provider, the AWS account that owns the IAM identity provider, the AWS organization that contains that account when applicable, and the optional Subject type |
Identity provider runtime claims |
|
Additional session-specific values that the identity provider supplies from sources selected by the customer |
Directory context |
|
References to the IAM Identity Center instance and identity store that supported AWS services use to resolve the Subject's group membership |
Values enter TIP context in three ways:
Identity-provider-supplied values: The customer selects a SAML assertion field or OIDC token claim. The identity provider supplies its value during federation. AWS STS validates the SAML assertion or OIDC token before attaching the selected value. This applies to Subject, mapped Subject type, and runtime claims.
Customer-configured values and associations: The customer can configure a fixed Subject type or associate an IAM Identity Center instance with the IAM identity provider.
AWS-derived values: AWS derives Issuer and the identity provider account from the configured IAM identity provider used for federation. When that account belongs to an AWS organization, AWS derives the identity provider organization ID. AWS derives the identity store ARN from the associated IAM Identity Center instance.
Every IAM federation session with TIP context contains Subject, Issuer, the federated provider ARN, and the identity provider account. Subject type and runtime claims are optional. The identity provider organization ID is present only when the identity provider account belongs to an AWS organization. Directory context is included only when group-based access is configured.
Identify the originator and identity provider
Core origin identity identifies the end user that started the workflow, the external identity provider used for federation, and the AWS ownership boundary for the corresponding IAM identity provider. Subject identifies the end user. Issuer and FederatedProviderArn identify the external identity provider and IAM identity provider resource. IdentityProviderAccount identifies the AWS account that owns the IAM identity provider. IdentityProviderOrgID identifies that account's AWS organization when the account belongs to one.
aws:OriginIdentity/IdentityProviderAccount and
aws:OriginIdentity/IdentityProviderOrgID are AWS-derived ownership keys.
They identify the AWS account that owns the IAM identity provider and, when applicable,
the AWS organization that contains that account. AWS STS uses these values to determine
the TIP propagation boundary. Customers do
not configure these values, and callers cannot change them after AWS STS attaches them to the
session.
The following table lists each core origin identity key, when it appears, what it identifies, and where its value comes from.
Context key |
Presence |
What it identifies |
Value source |
|---|---|---|---|
|
Every IAM federation session with TIP context |
The end user that started the workflow |
The identity provider supplies the value from the customer-selected SAML assertion field or OIDC token claim. AWS STS validates the assertion or token before attaching the selected value. |
|
Every IAM federation session with TIP context |
The external identity provider that authenticated the Subject |
AWS derives the value from the identity provider used for federation. For OIDC federation, |
|
Every IAM federation session with TIP context |
The IAM identity provider through which the identity entered AWS |
AWS derives the ARN from the IAM identity provider used for federation. |
|
Every IAM federation session with TIP context |
The AWS account that owns the IAM identity provider used for federation |
AWS derives the account ID from the validated IAM identity provider ARN. When AWS STS carries TIP context within the TIP propagation boundary, this value remains unchanged through role chains and AWS service workflows that use an IAM service role. |
|
When the identity provider account belongs to an AWS organization |
The AWS organization that contains the account that owns the IAM identity provider |
AWS derives the organization ID from the identity provider account. The key is absent when that account does not belong to an AWS organization. When AWS STS carries TIP context within the TIP propagation boundary, this value remains unchanged through role chains and AWS service workflows that use an IAM service role. |
|
Optional |
Whether the end user is a |
The customer configures |
The selected Subject source must be present. Choose a source that is stable and unique within the identity provider. The value must meet the source-value requirements. For source-selection guidance, see Configure TIP for a SAML provider or Configure TIP for an OIDC provider.
If you do not configure Subject type, AWS STS does not attach aws:OriginIdentity/SubjectType.
Map identity provider runtime claims
Runtime-claim mappings attach optional, session-specific identity provider values to TIP context. Each mapping has a required source and an optional target-key suffix:
A required source field in a SAML assertion or claim in an OIDC token
An optional target-key suffix that determines the resulting TIP context key
Each runtime context key uses this format:
aws:TransactionContext/IdentityProvider/<TargetKey>
The customer selects the source and can optionally specify a target-key suffix. If TargetKey is omitted, IAM uses SourceKey as the target-key suffix. If TargetKey is provided, it can differ from SourceKey. The identity provider supplies the source value during federation. AWS STS verifies the assertion or token and attaches the value under the resulting runtime context key.
When you configure TIP through an IAM API, CLI, or SDK, KeyDefinitionList in the ContextProvider request parameter defines the runtime-claim mappings. The following table lists the runtime-specific members, what each member controls, and whether it is required.
|
Purpose |
Requirement |
|---|---|---|
|
Contains the runtime-claim mappings |
Optional; up to 10 entries |
|
Identifies the source field in a SAML assertion or claim in an OIDC token |
Required for each mapping; 1 to 128 characters |
|
Supplies the suffix appended to |
Optional. If omitted, IAM uses |
For the reserved source-key values that select standard SAML assertion fields, see Configure TIP for a SAML provider.
IAM applies the same character requirements to every source and target key in ContextProvider: the required Subject source, the optional Subject type source, each runtime-claim source, and each optional runtime-claim target suffix. In API, AWS CLI, and AWS SDK requests, these values are represented by SubjectSourceKey, SubjectTypeSourceKey, KeyDefinitionList[].SourceKey, and KeyDefinitionList[].TargetKey.
Each supplied key must contain 1 to 128 characters. It can contain only ASCII letters and digits, single spaces, and the characters _ . : / = + - @ #. It cannot start or end with a space or contain two consecutive spaces.
IAM reserves the effective target-key suffixes subject, subjecttype, identitystorearn, identitycenterinstancearn, and identitycentersessionid, in any capitalization. The effective suffix is TargetKey when you provide it and SourceKey when you omit TargetKey.
Runtime claims are optional and do not replace the required Subject. Each SourceKey must be unique without regard to case. Each effective target-key suffix must also be unique without regard to case.
Meet source-value requirements
The Subject, a mapped Subject type, and each mapped runtime claim must contain one value of no more than 128 characters. AWS STS accepts strings, numbers, and Boolean values and represents accepted numbers and Boolean values as strings. Values can contain letters, numbers, spaces, and the characters _ . : / = + - @.
For an OIDC token, AWS STS flattens an object claim nested one level into <claim>/<member> sources. For example, you can map org/team from "org": {"team": "payments"}. The object claim itself is not a mappable value and is treated as absent. AWS STS rejects a mapped object nested more than one level deep. It also rejects a flattened key that collides with another claim of the same name, even when neither claim is mapped.
AWS STS rejects the federation request with InvalidIdentityToken in these cases:
The required Subject source is absent.
A configured mapped Subject type source is absent.
A configured source is present but empty, contains only whitespace or space separators, contains multiple values, exceeds 128 characters, uses an unsupported type, or contains an unsupported character.
The Subject starts or ends with a space or contains a separator character other than a space.
A mapped Subject type has a value other than
userorworkload.A claim mapped to a target key ending in
IssueTime, with that capitalization, does not contain an integer.A target key matches, without regard to case, the
Agekey derived from another target key ending inIssueTime. For example,loginIssueTimereserves the derived keyloginAge.
An absent optional runtime claim is omitted from the session. A present optional runtime claim that violates a requirement causes the federation request to fail.
TIP context shares the capacity of the AWS STS session token with other session data; it does not have a separate fixed aggregate runtime-claim quota in the IAM service model. If the combined session content is too large, the federation request fails with PackedPolicyTooLarge.
Customer-selected runtime claims use aws:TransactionContext/IdentityProvider/*. They do not use the aws:OriginIdentity/* namespace reserved for core origin identity.
Resolve group membership through directory context
When you configure TIP for a SAML or OIDC provider, you can select Allow granting permissions to groups to associate the provider with an IAM Identity Center instance. For the selection and setup procedure, see Configure group-based access for TIP. TIP then includes directory context that supported AWS services use to resolve the Subject and evaluate group-based access.
The following table identifies the directory context keys, what each key represents, and where its value comes from.
Context key |
What it identifies |
Value source |
|---|---|---|
|
The IAM Identity Center instance associated with the IAM identity provider |
The customer selects the IAM Identity Center instance. IAM stores the provider association. AWS STS attaches the instance ARN to the TIP session. |
|
The identity store associated with that IAM Identity Center instance |
IAM derives and stores the identity store ARN from the selected instance. AWS STS attaches it to the TIP session. |
These values are not identity provider claim mappings. They connect the propagated Subject to the directory used by supported AWS services. The Subject value must match the corresponding user's Username in IAM Identity Center so that the AWS service can resolve group membership.
When group-based access is configured, aws:IdentityCenterInstanceArn and aws:IdentityStoreArn are available for evaluation in applicable IAM policy conditions. Use these keys to restrict access to the expected IAM Identity Center instance or identity store. A StringEquals condition that tests either key does not match when the request does not contain that key.
See the resulting TIP context
The following examples distinguish the identity provider input, customer configuration, AWS-derived values, and resulting context. They do not include directory context because group-based access is not configured. For complete configuration requests, see Configure TIP for a SAML provider or Configure TIP for an OIDC provider.
OIDC workload example
Identity provider input. An OIDC provider issues a token that AWS STS verifies. The token contains the following claims:
{ "sub": "workload-1234567890", "environment": "production" }
Customer configuration. The customer selects sub as the Subject, configures the fixed Subject type workload, and maps environment to the target-key suffix environment.
AWS-derived context. AWS derives the Issuer, federated provider ARN, identity provider account, and identity provider organization ID from the configured OIDC provider and its owning account. The customer does not configure these values as runtime-claim mappings.
Resulting TIP context. AWS STS attaches:
aws:OriginIdentity/Subject = "workload-1234567890" aws:OriginIdentity/Issuer = "idp.example.com" aws:OriginIdentity/FederatedProviderArn = "arn:aws:iam::111122223333:oidc-provider/idp.example.com" aws:OriginIdentity/IdentityProviderAccount = "111122223333" aws:OriginIdentity/IdentityProviderOrgID = "o-a1b2c3d4e5" aws:OriginIdentity/SubjectType = "workload" aws:TransactionContext/IdentityProvider/environment = "production"
SAML user example
Identity provider input. A SAML provider sends user@example.com in Subject/NameID and includes a department assertion attribute with the single value Finance.
Customer configuration. The customer selects Subject/NameID as the Subject, configures the fixed Subject type user, and maps the department attribute to the target-key suffix department.
AWS-derived context. AWS derives the Issuer as the lowercase hexadecimal SHA-384 hash of the DER-encoded public key that it used to verify the assertion's signature. The value identifies the signing key, not the assertion's <Issuer> entity ID. AWS also derives the federated provider ARN and identity provider account from the configured SAML provider. The example account belongs to an AWS organization, so AWS derives the identity provider organization ID.
Resulting TIP context. AWS STS attaches:
aws:OriginIdentity/Subject = "user@example.com" aws:OriginIdentity/Issuer = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" aws:OriginIdentity/FederatedProviderArn = "arn:aws:iam::111122223333:saml-provider/ExampleProvider" aws:OriginIdentity/IdentityProviderAccount = "111122223333" aws:OriginIdentity/IdentityProviderOrgID = "o-a1b2c3d4e5" aws:OriginIdentity/SubjectType = "user" aws:TransactionContext/IdentityProvider/department = "Finance"
Preserve TIP context across the workflow
The following scenarios show when TIP context persists as a workflow uses additional IAM roles:
A federated session directly assumes another role. An end user federates into Role A with TIP context and then uses that session to assume Role B. AWS STS first applies the TIP propagation boundary. If Role B is within the boundary, AWS STS carries TIP context into the new role session without requiring a customer-authored Allow for
sts:SetContext. An applicable explicit Deny forsts:AssumeRoleorsts:SetContextcauses the complete request to fail. If Role B is outside the boundary, AWS STS does not carry TIP context into the new session. The role assumption can still succeed ifsts:AssumeRoleis otherwise authorized.An AWS service assumes an IAM service role. An end user calls a supported AWS service with a TIP session. When the AWS service uses its own credentials to assume an IAM service role for that workflow, AWS STS applies the same TIP propagation boundary. Within the boundary, AWS STS reattaches the caller's TIP context to the service role credentials. Outside the boundary, the role assumption can still succeed, but the service role credentials do not contain TIP context.
TIP context has these properties:
Attached after validation: AWS STS attaches identity-provider values only after validating the SAML assertion or OIDC token.
Immutable: A downstream caller cannot change or remove an attached value.
Persistent within the TIP propagation boundary: Supported workflows preserve the context as they use additional IAM roles within the TIP propagation boundary.
Namespace-separated: Core identity and runtime claims use different namespaces, so a runtime claim cannot replace the Subject or Issuer.
Use and inspect TIP context
TIP context does not grant permissions by itself. Customers can use the context in IAM policy conditions and inspect it in AWS CloudTrail records.
Use TIP context in IAM policies
All AWS services can use TIP context when they evaluate an IAM policy for a request made with credentials that carry TIP context. If an AWS service uses an IAM service role, it must carry TIP context into the service role credentials before the context is available for policy evaluation.
For condition keys and policy examples, see Control TIP for IAM federation with IAM policies. To check which AWS services can use TIP context in IAM policies, see AWS services that support TIP.
Inspect TIP context in AWS CloudTrail
AWS CloudTrail records TIP context in the federation event that creates the TIP session. For later requests, supported events can include the context carried by the role session.
The following table shows the CloudTrail location for each TIP context category.
TIP context category |
AWS CloudTrail location |
|---|---|
Core origin identity |
|
Identity provider runtime claims |
|
Directory context |
|
For event paths, recipient accounts, personal-information disclosure, CloudTrail surfaces, retention, redaction, policy safeguards, and logging examples, see Logging TIP activity with AWS CloudTrail.