AWS IAM: STS outbound federation JWT condition keys; tighter aud policy guidance
Summary
Adds a new AWS STS tab documenting how claims from GetWebIdentityToken JWTs (issuer-host-prefixed sub, aud, jti, mfa_present, mfa_age, org_id, ec2_source_instance_arn, etc.) map to condition keys usable in a destination role's trust policy, with an example cross-partition trust policy and MFA/source-workload scoping notes. Also updates the sts:IdentityTokenAudience guidance to describe the key as multivalued and changes the example from ForAnyValue:StringEquals to ForAllValues:StringEquals with a Null:false condition.
Security assessment
The IdentityTokenAudience example previously used ForAnyValue:StringEquals, which matches if ANY requested audience is allowed, so a caller could silently request tokens for additional, unintended audiences; switching to ForAllValues:StringEquals requires every requested audience to match an allowed value, and the added "Null": {"sts:IdentityTokenAudience": "false"} forces the key to be present and nonempty. This corrects an over-permissive authorization pattern in documented trust/identity policies. The new STS federation tables and example trust policy additionally show how to constrain role assumption by issuer-host:sub, :aud, :source_region, :org_id, and workload identity claims, and how to require MFA via issuer-host:mfa_present.
Evidence
+ "ForAllValues:StringEquals": {
Diff
diff --git a/IAM/latest/UserGuide/reference_policies_iam-condition-keys.md b/IAM/latest/UserGuide/reference_policies_iam-condition-keys.md index 31149d2..e1d46fc 100644 --- a//IAM/latest/UserGuide/reference_policies_iam-condition-keys.md +++ b//IAM/latest/UserGuide/reference_policies_iam-condition-keys.md @@ -853,0 +854,243 @@ JSON +AWS STS + + +This tab explains how [AWS STS](https://docs.aws.amazon.com/STS/latest/APIReference/Welcome.html) maps claims in JSON Web Tokens (JWTs) generated by [GetWebIdentityToken](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetWebIdentityToken.html) to AWS STS condition context keys. You can use these keys in the destination role's trust policy to control access to the role. The **IdP JWT claim** column identifies the token claim mapped to each condition key. + +For AWS STS, issuer-prefixed keys consist of your source account's issuer host, a colon, and the claim name. The issuer host is your issuer URL without the `https://` prefix. For example, the `sub` claim maps to `a1d2b0fd-1177-4468-9351-2fEXAMPLE723.tokens.sts.global.api.aws:sub`. For claims nested under the `https://sts.amazonaws.com/` namespace, omit the namespace—for example, use ``issuer-host`:org_id`. The `request_tags` and `source_identity` claims use the separate mappings shown in the table. To find your issuer URL, see [Getting started with outbound identity federation](./id_roles_providers_outbound_getting_started.html). + +The Available in session column indicates whether the same condition key is retained for policies evaluated on subsequent requests made with the role's temporary credentials. + +For more information, see [Federating AWS identities across AWS partitions](./id_roles_providers_outbound_cross_partition.html). + +AWS STS condition key | IdP JWT claim | Available in session +---|---|--- +``issuer-host`:sub` | `sub` | Yes +``issuer-host`:aud` | `aud` | Yes +``issuer-host`:jti` | `jti` | No +``issuer-host`:aws_account` | `aws_account` | No +``issuer-host`:source_region` | `source_region` | No. The value is retained as [aws:CrossPartitionSourceRegion](./reference_policies_condition-keys.html#condition-keys-crosspartitionsourceregion). +``issuer-host`:principal_id` | `principal_id` | No +``issuer-host`:original_session_exp` | `original_session_exp` | No +``issuer-host`:invoked_by` | `invoked_by` | No +``issuer-host`:mfa_present` | `mfa_present` | No +``issuer-host`:mfa_age` | `mfa_age` | No +``issuer-host`:org_id` | `org_id` | No +``issuer-host`:ou_path` | `ou_path` | No +``issuer-host`:identity_store_user_id` | `identity_store_user_id` | No +``issuer-host`:identity_store_arn` | `identity_store_arn` | No +``issuer-host`:ec2_source_instance_arn` | `ec2_source_instance_arn` | No +``issuer-host`:ec2_role_delivery` | `ec2_role_delivery` | No +``issuer-host`:ec2_instance_source_vpc` | `ec2_instance_source_vpc` | No +``issuer-host`:ec2_instance_source_private_ipv4` | `ec2_instance_source_private_ipv4` | No +``issuer-host`:lambda_source_function_arn` | `lambda_source_function_arn` | No +``issuer-host`:glue_credential_issuing_service` | `glue_credential_issuing_service` | No +`aws:RequestTag/`tag-key`` | A tag value in `request_tags` | No. The tag is retained as [aws:PrincipalTag/tag-key](./reference_policies_condition-keys.html#condition-keys-principaltag). +`aws:TagKeys` | The tag keys in `request_tags` | No +`sts:SourceIdentity` | `source_identity` | No. The value is retained as [aws:SourceIdentity](./reference_policies_condition-keys.html#condition-keys-sourceidentity). + +###### Note + +The `iss`, `iat`, `exp`, `principal_tags`, and `federated_provider` claims aren't mapped to condition keys for cross-partition role assumption. + +**`issuer-host`:sub** + + +**Data type:** String. Works with [string operators](./reference_policies_elements_condition_operators.html#Conditions_String). + +The ARN of the source IAM principal that requested the token. This claim is always present. For example, `arn:aws:iam::123456789012:role/SourceWorkloadRole`. + +**`issuer-host`:aud** + + +**Data type:** String. Works with [string operators](./reference_policies_elements_condition_operators.html#Conditions_String). + +The audience for which the token was requested. This claim is always present. For example, `my-destination-app`. + +**`issuer-host`:jti** + + +**Data type:** String. Works with [string operators](./reference_policies_elements_condition_operators.html#Conditions_String). + +The unique identifier of the token. This claim is always present. For example, `a1b2c3d4-5678-90ab-cdef-0123456789ab`. + +**`issuer-host`:aws_account** + + +**Data type:** String. Works with [string operators](./reference_policies_elements_condition_operators.html#Conditions_String). + +The account ID of the source IAM principal. This claim is always present. For example, `123456789012`. + +**`issuer-host`:source_region** + + +**Data type:** String. Works with [string operators](./reference_policies_elements_condition_operators.html#Conditions_String). + +The AWS Region where the token was requested. This claim is always present. For example, `us-east-1`. + +**`issuer-host`:principal_id** + + +**Data type:** ARN. Works with [ARN operators](./reference_policies_elements_condition_operators.html#Conditions_ARN). + +The ARN of the source IAM principal that requested the token. This claim is always present. For example, `arn:aws:iam::123456789012:role/SourceWorkloadRole`. + +**`issuer-host`:original_session_exp** + + +**Data type:** Date. Works with [date operators](./reference_policies_elements_condition_operators.html#Conditions_Date). + +The expiration time of the source session credentials, in ISO 8601 format. This claim is present when the credentials have an expiration time. For example, `2026-10-02T02:03:26Z`. + +**`issuer-host`:invoked_by** + + +**Data type:** String. Works with [string operators](./reference_policies_elements_condition_operators.html#Conditions_String). + +The AWS service acting on the customer's behalf by assuming the source role, or the last service in a [forward access session](./access_forward_access_sessions.html). This claim is present only when the source session includes that service's identity. For example, `ec2.amazonaws.com`. + +**`issuer-host`:mfa_present** + + +**Data type:** String. Works with [string operators](./reference_policies_elements_condition_operators.html#Conditions_String). + +Indicates that the source IAM principal authenticated with MFA. This claim is present only when MFA was used and has the string value `"true"`. It is never `"false"`. + +To require MFA, use `StringEquals` with `"true"` in an `Allow` statement. To deny requests where the key is absent, use `Null` with `"true"` in a `Deny` statement. + +**`issuer-host`:mfa_age** + + +**Data type:** Numeric. Works with [numeric operators](./reference_policies_elements_condition_operators.html#Conditions_Numeric). + +The number of seconds since the source IAM principal authenticated with MFA, encoded as a string. This claim is present when MFA was used and the authentication age is available. For example, `"1800"`. + +**`issuer-host`:org_id** + + +**Data type:** String. Works with [string operators](./reference_policies_elements_condition_operators.html#Conditions_String). + +The AWS Organizations ID of the source account. This claim is present when the account belongs to an organization and its ID is available. For example, `o-a1b2c3d4e5`. + +**`issuer-host`:ou_path** + + +**Data type:** String. Works with [string operators](./reference_policies_elements_condition_operators.html#Conditions_String) and the `ForAnyValue` or `ForAllValues` set operator. + +**Value type:** Multivalued. + +The AWS Organizations paths for the source account. This claim is present when the source account's organization paths are available. For example, `["o-a1b2c3d4e5/r-ab12/ou-ab12-11111111/"]`. + +Use `ForAnyValue:StringLike` with a path ending in `/*`, such as `o-a1b2c3d4e5/r-ab12/ou-ab12-11111111/*`, to match an organizational unit and its descendants. For more information, see [aws:PrincipalOrgPaths](./reference_policies_condition-keys.html#condition-keys-principalorgpaths). + +**`issuer-host`:identity_store_user_id** + + +**Data type:** String. Works with [string operators](./reference_policies_elements_condition_operators.html#Conditions_String). + +The IAM Identity Center user ID associated with the source session. This claim is present when the session includes an IAM Identity Center user identity. For example, `94482488-3041-7026-1234-123456789012`. Use it with ``issuer-host`:identity_store_arn` to identify the user and identity store. + +**`issuer-host`:identity_store_arn** + + +**Data type:** ARN. Works with [ARN operators](./reference_policies_elements_condition_operators.html#Conditions_ARN). + +The ARN of the IAM Identity Center identity store. This claim is present when the source session includes the identity store ARN. For example, `arn:aws:identitystore::123456789012:identitystore/d-1234567890`. + +**`issuer-host`:ec2_source_instance_arn** + + +**Data type:** ARN. Works with [ARN operators](./reference_policies_elements_condition_operators.html#Conditions_ARN). + +The ARN of the Amazon EC2 instance that received the source role credentials. This claim is present when those credentials include the instance ARN. For example, `arn:aws:ec2:us-east-1:123456789012:instance/i-0123456789abcdef0`. + +**`issuer-host`:ec2_role_delivery** + + +**Data type:** Numeric. Works with [numeric operators](./reference_policies_elements_condition_operators.html#Conditions_Numeric). + +The instance metadata service (IMDS) version used to deliver the source role credentials. This claim is present when the credentials include the [IMDS version](./reference_policies_condition-keys.html#condition-keys-ec2-role-delivery): `1.0` for IMDSv1 or `2.0` for IMDSv2. For example, `2.0`. + +**`issuer-host`:ec2_instance_source_vpc** + + +**Data type:** String. Works with [string operators](./reference_policies_elements_condition_operators.html#Conditions_String). + +The VPC ID of the Amazon EC2 instance that received the source role credentials. This claim is present when those credentials include the instance VPC ID. For example, `vpc-0123456789abcdef0`. + +**`issuer-host`:ec2_instance_source_private_ipv4** + + +**Data type:** IP address. Works with [IP address operators](./reference_policies_elements_condition_operators.html#Conditions_IPAddress). + +The primary private IPv4 address of the Amazon EC2 instance that received the source role credentials. This claim is present when those credentials include the instance's private IPv4 address. For example, `10.0.0.15`. + +**`issuer-host`:lambda_source_function_arn** + + +**Data type:** ARN. Works with [ARN operators](./reference_policies_elements_condition_operators.html#Conditions_ARN). + +The ARN of the Lambda function associated with the source credentials. This claim is present when those credentials include the function ARN. For example, `arn:aws:lambda:us-east-1:123456789012:function:MyFunction`. + +**`issuer-host`:glue_credential_issuing_service** + + +**Data type:** String. Works with [string operators](./reference_policies_elements_condition_operators.html#Conditions_String). + +The AWS Glue service that issued the source credentials. This claim is present when credentials for a Glue job or developer endpoint include the [service identifier](./reference_policies_condition-keys.html#condition-keys-glue-credential-issuing). For example, `glue.amazonaws.com`. + +**aws:RequestTag/`tag-key`** + + +**Data type:** String. Works with [string operators](./reference_policies_elements_condition_operators.html#Conditions_String). + +A tag value from the token's `request_tags` claim. This key is present when the caller passes the corresponding tag to `GetWebIdentityToken`. For example, [aws:RequestTag/project](./reference_policies_condition-keys.html#condition-keys-requesttag) has the value `migration`. + +The destination role's trust policy must allow `sts:TagSession`. Apply `aws:RequestTag/`tag-key`` conditions to that statement to restrict tag values.