Understanding token claims
When you call the GetWebIdentityToken API, AWS Security Token Service (AWS STS) returns a signed JSON Web Token (JWT) that contains claims about the calling IAM principal and, when applicable, the requesting session. Understanding these claims helps you implement secure authentication flows, configure claim validation in external services, and use claims for fine-grained access control.
The JWT includes standard OpenID Connect (OIDC) claims such as subject (sub), audience (aud), and issuer (iss). AWS STS also includes AWS identity and session-context claims when they apply to the request. These claims appear under the https://sts.amazonaws.com/ namespace, as shown in the following sample. If the request includes tags, AWS STS places them in the request_tags object under the same namespace.
When credentials that contain trusted identity propagation (TIP) context call GetWebIdentityToken, AWS STS includes each applicable origin_identity and transaction_context claim from that context in the resulting JWT, regardless of SubjectMode. SubjectMode controls which identity AWS STS places in sub; it does not suppress TIP claims. If the request includes an accepted Scope value, AWS STS adds it as the top-level scope claim.
TIP context is Customer-Created Metadata and does not constitute Customer Content. The Subject and identity provider claims can contain personally identifying, confidential, or sensitive information. Do not configure these values with information that you do not want included in the JWT and disclosed to its intended external recipient.
The following sample shows the default token structure and the placement of AWS identity, session-context, and request-tag claims. See TIP and Scope claims for the additional conditional claims. Not every claim is present in every token.
{ "iss": "https://abc123-def456-ghi789-jkl012.tokens.sts.global.api.aws", "aud": "https://api.example.com", "sub": "arn:aws:iam::123456789012:role/DataProcessingRole", "iat": 1700000000, "exp": 1700000900, "jti": "xyz123-def456-ghi789-jkl012", "https://sts.amazonaws.com/": { "aws_account": "123456789012", "source_region": "us-east-1", "org_id": "o-abc1234567", "ou_path": "o-a1b2c3d4e5/r-ab12/ou-ab12-11111111/ou-ab12-22222222/", "principal_tags": { "environment": "production", "team": "data-engineering", "cost-center": "engineering" }, "lambda_source_function_arn": "arn:aws:lambda:us-east-1:123456789012:function:process-data", "request_tags": { "job-id": "job-2024-001", "priority": "high", "data-classification": "sensitive" } } }
Standard claims
The standard OIDC claims present in the tokens facilitate interoperability with a wide range of external services. These claims can be validated using most JWT libraries.
| Claim | Name | Description | Example value |
|---|---|---|---|
| iss | Issuer | Your account-specific issuer URL. External services validate this claim to ensure it matches their trusted issuer. | https://abc123-def456-ghi789-jkl012.tokens.sts.global.api.aws |
| aud | Audience | The intended recipient for the token specified in the GetWebIdentityToken request. | https://api.example.com |
| sub | Subject | The identity represented by the token. If SubjectMode is omitted or set to AWSIdentity, the value is the ARN of the IAM principal that requested the token. If SubjectMode is set to OriginIdentity, the value is the TIP Subject carried by the calling session. |
arn:aws:iam::123456789012:role/DataProcessingRole or user@example.com |
| iat | Issued At | NumericDate value that identifies the time at which the JWT was issued. | 1700000000 |
| exp | Expiration | NumericDate value that identifies the expiration time on or after which the JWT MUST NOT be accepted for processing. | 1700000900 |
| jti | JWT ID | Unique identifier for this token instance. | xyz123-def456-ghi789-jkl012 |
Understand the subject claim
The optional SubjectMode request parameter determines which identity AWS STS places in the standard sub claim:
-
If you omit
SubjectModeor set it toAWSIdentity,subcontains the ARN of the IAM principal that requested the token. -
If you set
SubjectModetoOriginIdentity,subcontains the TIP Subject carried by the calling session.
AWS STS includes principal_id when the caller has an IAM principal ARN, regardless of SubjectMode. For a role session, principal_id contains the role ARN, not the assumed-role session ARN. When SubjectMode is OriginIdentity, AWS STS also includes the subject_mode claim with the value OriginIdentity. The TIP and Scope claims example shows where these claims appear in the token.
If an existing relying party expects sub to contain an IAM principal ARN, omit SubjectMode or set it to AWSIdentity.
Custom claims
In addition to standard OIDC claims, AWS STS can include claims derived from the AWS identity, session context, request tags, and TIP context. AWS STS nests these claims under the https://sts.amazonaws.com/ namespace. The tables in this section explain what each claim contains and when it appears. The optional scope claim is an exception: AWS STS places it at the top level when the request includes an accepted Scope value.
For the condition keys used in cross-partition role assumption and their availability in the destination session, see the AWS STS tab under Available keys for AWS OIDC federation.
AWS identity claims
These claims provide detailed information about your AWS account, organization structure, and IAM principal.
| Claim | Description | Maps to Condition Key | Example Value |
|---|---|---|---|
| aws_account | Your AWS account ID | aws:PrincipalAccount | 123456789012 |
| source_region | The AWS region where the token was requested | aws:RequestedRegion | us-east-1 |
| org_id | Your AWS Organizations ID (if your account is part of an organization) | aws:PrincipalOrgID | o-abc1234567 |
| ou_path | The AWS Organizations paths for the source account, as an array. Present when organization paths are available in the source request context. | aws:PrincipalOrgPaths | ["o-a1b2c3d4e5/r-ab12/ou-ab12-11111111/ou-ab12-22222222/"] |
| principal_tags | Tags attached to the IAM principal or assumed role session. When a token is requested where the requesting IAM principal has both principal tags and session tags, the session tags will be present in the JWT. | aws:PrincipalTag/<tag-key> | {"environment": "production", "team": "data-engineering", "cost-center":"engineering"} |
Session context claims
These claims provide information about the compute environment and session where the token request originated. AWS STS automatically includes these claims when applicable based on the requesting principal's session context.
| Claim | Description | Maps to Condition Key | Example Value |
|---|---|---|---|
| original_session_exp | When the original role session credentials will expire (for assumed roles) | N/A | 2024-01-15T10:00:00Z |
| federated_provider | The identity provider name for federated sessions | aws:FederatedProvider | arn:aws:iam::111122223333:oidc-provider/your_oidc_provider |
| identity_store_user_id | IAM Identity Center user ID | identitystore:UserId | user-abc123def456 |
| identity_store_arn | ARN of the IAM Identity Center identity store | identitystore:IdentityStoreArn | arn:aws:identitystore::123456789012:identitystore/d-abc1234567 |
| ec2_source_instance_arn | ARN of the requesting EC2 instance | ec2:SourceInstanceArn | arn:aws:ec2:us-east-1:123456789012:instance/i-abc123def456 |
| ec2_instance_source_vpc | VPC ID where EC2 role credentials were delivered | aws:Ec2InstanceSourceVpc | vpc-abc123def456 |
| ec2_instance_source_private_ipv4 | Private IPv4 address of the EC2 instance | aws:Ec2InstanceSourcePrivateIPv4 | 10.0.1.25 |
| ec2_role_delivery | The instance metadata service (IMDS) version that delivered the source role credentials: 1.0 for IMDSv1 or 2.0 for IMDSv2. |
ec2:RoleDelivery | 2.0 |
| source_identity | Source identity set by the principal | aws:SourceIdentity | admin-user |
| lambda_source_function_arn | ARN of the calling Lambda function | lambda:SourceFunctionArn | arn:aws:lambda:us-east-1:123456789012:function:my-function |
| glue_credential_issuing_service | AWS Glue service identifier for Glue jobs | glue:CredentialIssuingService | glue.amazonaws.com |
| invoked_by | The AWS service acting on the customer's behalf by assuming the source role, or the last service in a forward access session. This claim is present only when the source session includes that service's identity. | N/A | ec2.amazonaws.com |
| mfa_present | Indicates that the IAM principal authenticated with MFA. Present only when MFA was used, with the string value "true". It is never "false". |
aws:MultiFactorAuthPresent | "true" |
| mfa_age | The number of seconds since the IAM principal authenticated with MFA, encoded as a string. Present only when MFA was used and the authentication age is available. | aws:MultiFactorAuthAge | "1800" |
TIP and Scope claims
When the credentials used to call AWS STS contain TIP context, AWS STS can include supported TIP claims in the JWT. If the request also includes an accepted Scope value, AWS STS includes the scope claim. Except for scope, the claims in the following table are nested under the https://sts.amazonaws.com/ namespace. The table explains what each claim contains and when AWS STS includes it.
| Claim | Description | When included |
|---|---|---|
principal_id |
The ARN of the IAM principal that requested the token. For a role session, this is the role ARN, not the assumed-role session ARN. This value corresponds to the aws:PrincipalArn condition key. | The caller has an IAM principal ARN. |
subject_mode |
Indicates that AWS STS placed the TIP Subject in sub. The value is OriginIdentity. |
SubjectMode is set to OriginIdentity. |
origin_identity |
Contains the supported origin identity claims carried in TIP context. | At least one supported origin identity claim is present. |
origin_identity.subject |
The TIP Subject carried by the calling session. | The calling credentials contain a TIP Subject. |
origin_identity.subject_type |
The optional type value carried with the TIP Subject. | The calling credentials contain a Subject type. |
origin_identity.issuer |
The issuer value carried with the TIP Subject. | The calling credentials contain an Issuer. |
origin_identity.federated_provider_arn |
The ARN of the IAM identity provider used to establish the originating federated session. | The calling credentials contain the federated-provider ARN. |
origin_identity.identity_provider_account |
The JWT representation of aws:OriginIdentity/IdentityProviderAccount. Contains the AWS account ID that owns the identity provider used to establish the originating federated session. |
The calling credentials contain the identity provider account. |
origin_identity.identity_provider_org_id |
The JWT representation of aws:OriginIdentity/IdentityProviderOrgID. Contains the AWS Organizations ID for the account that owns the identity provider. |
The identity provider account belongs to an organization and the calling credentials contain its organization ID. |
transaction_context.identity_provider |
Contains customer-configured identity provider runtime claims carried in TIP context. | At least one mapped identity provider runtime claim is present. |
scope |
Contains the accepted Scope request value unchanged. This claim is top level. |
The request includes an accepted Scope value. |
For a TIP session established through SAML federation, origin_identity.issuer is the SHA-384 hash of the signing public key that AWS used to verify the SAML assertion. The value changes when the identity provider rotates its signing certificate. If an external service uses this value, update its approved values before rotation so it does not reject valid tokens. Use origin_identity.federated_provider_arn when the external service needs a stable identifier for the configured SAML provider.
The following fragment shows where the claims appear in the JWT. It includes only claims relevant to SubjectMode, TIP, and Scope. Values are illustrative.
{ "sub": "user@example.com", "scope": "session:role:analyst", "https://sts.amazonaws.com/": { "principal_id": "arn:aws:iam::123456789012:role/DataProcessingRole", "subject_mode": "OriginIdentity", "origin_identity": { "subject": "user@example.com", "subject_type": "user", "issuer": "idp.example.com", "federated_provider_arn": "arn:aws:iam::123456789012:oidc-provider/idp.example.com", "identity_provider_account": "123456789012", "identity_provider_org_id": "o-a1b2c3d4e5" }, "transaction_context": { "identity_provider": { "department": "analytics" } } } }
TIP and Scope claims count toward the 20,000-byte JWT payload limit. AWS STS rejects a request that would exceed this limit.
Scope represents what the caller requests from the external service. It is not a grant from AWS STS. IAM policies control which Scope values the caller can request, and the external service independently decides what each value means and whether the identity in sub is authorized to use it.
Request tags
You can add custom claims to tokens by specifying tags in the GetWebIdentityToken API request. These claims appear under the request_tags field in the token and enable you to pass specific information that external services can use for fine-grained authorization decisions. You can specify up to 50 tags per request.
Example request:
response = sts_client.get_web_identity_token( Audience=['https://api.example.com'], SigningAlgorithm='ES384', Tags=[ {'Key': 'team', 'Value': 'data-engineering'}, {'Key': 'cost-center', 'Value': 'analytics'}, {'Key': 'environment', 'Value': 'production'} ] )
Resulting claims in token:
{ "request_tags": { "team": "data-engineering", "cost-center": "analytics", "environment": "production" } }