AWS Security ChangesHomeSearch

AWS awscloudtrail: Document trusted identity propagation fields in CloudTrail userIdentity

Service: awscloudtrail · 2026-11-20 · Documentation medium

File: awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.md · Type: logging

Summary

Adds a new 'Trusted identity propagation' section and JSON examples describing the onBehalfOf (subject, subjectType, issuer, federatedProviderArn) and transactionContext fields that appear in CloudTrail userIdentity for IAM federation (SAML/OIDC) and IAM Roles Anywhere sessions, plus notes on which account receives these events and where to view them. Also clarifies WebIdentityUser principalId/identityProvider values for IAM OIDC providers and removes a duplicate AssumedRole description.

Security assessment

The change documents audit/forensic fields (onBehalfOf, transactionContext) that CloudTrail records for requests carrying trusted identity propagation context, improving attribution of actions to the human user or workload behind federated and IAM Roles Anywhere sessions. It is security-relevant logging/audit guidance but does not describe or remediate any specific vulnerability, so it is not tied to a security incident.

Evidence

+If the request includes a trusted identity propagation context, `transactionContext` contains the runtime claims attached to the request. Each key identifies the source that supplied the claims.

Diff

diff --git a/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.md b/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.md
index 2ee5ca9..c08a5e7 100644
--- a//awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.md
+++ b//awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.md
@@ -7 +7 @@
-ExamplesFieldsValues for AWS STS APIs with SAML and web identity federationAWS STS source identity
+ExamplesFieldsTrusted identity propagationValues for AWS STS APIs with SAML and web identity federationAWS STS source identity
@@ -18,0 +19,12 @@ AWS Identity and Access Management (IAM) provides different types of identities.
+  * [Trusted identity propagation](./cloudtrail-event-reference-user-identity.html#cloudtrail-event-reference-user-identity-tip)
+
+    * [onBehalfOf fields](./cloudtrail-event-reference-user-identity.html#cloudtrail-event-reference-user-identity-tip-onbehalfof)
+
+    * [transactionContext fields](./cloudtrail-event-reference-user-identity.html#cloudtrail-event-reference-user-identity-tip-transactioncontext)
+
+    * [Which account receives these events](./cloudtrail-event-reference-user-identity.html#cloudtrail-event-reference-user-identity-tip-accounts)
+
+    * [Where to view trusted identity propagation data](./cloudtrail-event-reference-user-identity.html#cloudtrail-event-reference-user-identity-tip-view)
+
+    * [Examples](./cloudtrail-event-reference-user-identity.html#cloudtrail-event-reference-user-identity-tip-examples)
+
@@ -137,0 +150,139 @@ The `invokedByDelegate` field contains the AWS account ID of the product provide
+**`userIdentity` for a request made with an IAM federation session that carries trusted identity propagation context**
+
+The following example shows a `userIdentity` element for a request made with a role session that carries trusted identity propagation (TIP) context. The session was created with `AssumeRoleWithWebIdentity` through an IAM OIDC identity provider. The `onBehalfOf` element identifies the propagated user and the identity provider. The `transactionContext` element contains the runtime claims that the identity provider supplied. These fields appear only if trusted identity propagation is configured for the IAM identity provider, and only for requests to AWS services that support TIP. For descriptions of these fields, see Trusted identity propagation.
+    
+    
+    "userIdentity": {
+        "type": "AssumedRole",
+        "principalId": "AROA123456789EXAMPLE:MySessionName",
+        "arn": "arn:aws:sts::123456789012:assumed-role/RoleToBeAssumed/MySessionName",
+        "accountId": "123456789012",
+        "accessKeyId": "ASIAIOSFODNN7EXAMPLE",
+        "sessionContext": {
+            "sessionIssuer": {
+                "type": "Role",
+                "principalId": "AROA123456789EXAMPLE",
+                "arn": "arn:aws:iam::123456789012:role/RoleToBeAssumed",
+                "accountId": "123456789012",
+                "userName": "RoleToBeAssumed"
+            },
+            "webIdFederationData": {
+                "federatedProvider": "arn:aws:iam::123456789012:oidc-provider/idp.example.com",
+                "attributes": {}
+            },
+            "attributes": {
+                "mfaAuthenticated": "false",
+                "creationDate": "2026-10-10T06:50:23Z"
+            }
+        },
+        "onBehalfOf": {
+            "subject": "[email protected]",
+            "subjectType": "user",
+            "issuer": "idp.example.com",
+            "federatedProviderArn": "arn:aws:iam::123456789012:oidc-provider/idp.example.com"
+        },
+        "transactionContext": {
+            "IdentityProvider": {
+                "department": "Engineering",
+                "costCenter": "CC-1234"
+            }
+        }
+    }
+
+**`userIdentity` for an `AssumeRoleWithWebIdentity` request that carries trusted identity propagation context**
+
+The following example shows the `userIdentity` element of the `AssumeRoleWithWebIdentity` event that creates a role session with trusted identity propagation (TIP) context. The `type` is `WebIdentityUser`, and `userName` is the `sub` claim of the OIDC token. The `subject` attribute in `onBehalfOf` comes from the token claim that your identity provider configuration maps to the subject, so it can differ from `userName`. In this example, the subject is the user's email address.
+    
+    
+    "userIdentity": {
+        "type": "WebIdentityUser",
+        "principalId": "arn:aws:iam::123456789012:oidc-provider/idp.example.com:my-client-id:a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
+        "userName": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
+        "identityProvider": "arn:aws:iam::123456789012:oidc-provider/idp.example.com",
+        "onBehalfOf": {
+            "subject": "[email protected]",
+            "subjectType": "user",
+            "issuer": "idp.example.com",
+            "federatedProviderArn": "arn:aws:iam::123456789012:oidc-provider/idp.example.com"
+        },
+        "transactionContext": {
+            "IdentityProvider": {
+                "department": "Engineering",
+                "costCenter": "CC-1234"
+            }
+        }
+    }
+
+**`userIdentity` for an `AssumeRoleWithSAML` request that carries trusted identity propagation context**
+
+The following example shows the `userIdentity` element of the `AssumeRoleWithSAML` event that creates a role session with trusted identity propagation (TIP) context. The `type` is `SAMLUser`, and `userName` is the `NameID` from the SAML assertion. The `subject` attribute in `onBehalfOf` comes from the assertion attribute that your identity provider configuration maps to the subject. For SAML federation, `issuer` is a lowercase hexadecimal SHA-384 hash that identifies the key that signed the SAML assertion.
+    
+    
+    "userIdentity": {
+        "type": "SAMLUser",
+        "principalId": "EXAMPLE/4PXo6ZyN725NFgZfIYs=:_a1b2c3d4e5f6EXAMPLE",
+        "userName": "_a1b2c3d4e5f6EXAMPLE",
+        "identityProvider": "EXAMPLE/4PXo6ZyN725NFgZfIYs=",
+        "onBehalfOf": {
+            "subject": "[email protected]",
+            "subjectType": "user",
+            "issuer": "9b52a9e427b4aa878afa064a80879049eca6a141b6e2c413802ac22f3f74489de8cba9b356c7a257d39e8a27b61f3c96",
+            "federatedProviderArn": "arn:aws:iam::123456789012:saml-provider/ExampleProvider"
+        },
+        "transactionContext": {
+            "IdentityProvider": {
+                "department": "Engineering",
+                "costCenter": "CC-1234"
+            }
+        }
+    }
+
+**`userIdentity` for the `AssumeRole` request that IAM Roles Anywhere makes to create a role session with trusted identity propagation context**
+
+The following example shows the `userIdentity` element of the `AssumeRole` event that IAM Roles Anywhere records when it creates a role session for a workload. The `type` is `AWSService`, and `invokedBy` is `service.rolesanywhere.amazonaws.com`. The `onBehalfOf` element identifies the workload from its X.509 certificate. `subject` is the value from the certificate field that the profile uses as the subject source. `federatedProviderArn` is the ARN of the trust anchor that authenticated the certificate, and `issuer` is the SHA-384 hash of the trust anchor's CA certificate. IAM Roles Anywhere sessions don't include `transactionContext`.
+    
+    
+    "userIdentity": {
+        "type": "AWSService",
+        "invokedBy": "service.rolesanywhere.amazonaws.com",
+        "onBehalfOf": {
+            "federatedProviderArn": "arn:aws:rolesanywhere:ca-central-1:111122223333:trust-anchor/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
+            "subject": "spiffe://example.com/workload-a",
+            "subjectType": "workload",
+            "issuer": "38b060a751ac96384cd9327eb1b1e36a21fdb71114be07434c0cc7bf63f6e1da274edebfe76f65fbd51ad2f14898b95b"
+        }
+    }
+
+**`userIdentity` for a request made with an IAM Roles Anywhere role session that carries trusted identity propagation context**
+
+The following example shows a `userIdentity` element for a request made with the role session that IAM Roles Anywhere created in the previous example. The `onBehalfOf` element carries the same workload identity into requests made with the role session.
+    
+    
+    "userIdentity": {
+        "type": "AssumedRole",
+        "principalId": "AROA123456789EXAMPLE:a1b2c3d4e5f6a7b8c9",
+        "arn": "arn:aws:sts::111122223333:assumed-role/ExampleRole/a1b2c3d4e5f6a7b8c9",
+        "accountId": "111122223333",
+        "accessKeyId": "ASIAIOSFODNN7EXAMPLE",
+        "sessionContext": {
+            "sessionIssuer": {
+                "type": "Role",
+                "principalId": "AROA123456789EXAMPLE",
+                "arn": "arn:aws:iam::111122223333:role/ExampleRole",
+                "accountId": "111122223333",
+                "userName": "ExampleRole"
+            },
+            "attributes": {
+                "creationDate": "2026-11-18T15:37:28Z",
+                "mfaAuthenticated": "false"
+            },
+            "sourceIdentity": "CN=workload-a"
+        },
+        "onBehalfOf": {
+            "federatedProviderArn": "arn:aws:rolesanywhere:ca-central-1:111122223333:trust-anchor/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
+            "subject": "spiffe://example.com/workload-a",
+            "subjectType": "workload",
+            "issuer": "38b060a751ac96384cd9327eb1b1e36a21fdb71114be07434c0cc7bf63f6e1da274edebfe76f65fbd51ad2f14898b95b"
+        }
+    }
+
@@ -151,2 +301,0 @@ The type of the identity. The following values are possible:
-  * `AssumedRole` – The request was made with temporary security credentials that were obtained with a role by making a call to the AWS Security Token Service (AWS STS) [`AssumeRole`](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) API. This can include [roles for Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) and cross-account API access. 
-
@@ -210 +358,0 @@ The friendly name of the identity that made the call. The value that appears in
-`AssumedRole` | Not present | For the `AssumedRole` type, you can find the `userName` field in `sessionContext` as part of the sessionIssuer element. For an example entry, see Examples.  
@@ -352 +500 @@ For more information and a JSON example of delegated access in CloudTrail events
-If the request was made by an IAM Identity Center caller or an AWS Builder ID user, `onBehalfOf` provides information about the user on whose behalf the call was made. This element has the following attributes:
+If the request was made on behalf of another identity, `onBehalfOf` provides information about the human user or workload on whose behalf the call was made. This includes requests made by an IAM Identity Center caller or an AWS Builder ID user. It also includes requests made with credentials that carry trusted identity propagation (TIP) context. This element has the following attributes:
@@ -360,0 +509,11 @@ If the request was made by an IAM Identity Center caller or an AWS Builder ID us
+Note
+
+For requests made with trusted identity propagation (TIP) context, `onBehalfOf` can contain additional attributes. For more information, see Trusted identity propagation.
+
+**Optional:** True
+
+**`transactionContext`**
+    
+
+If the request includes a trusted identity propagation context, `transactionContext` contains the runtime claims attached to the request. Each key identifies the source that supplied the claims. For example, `IdentityProvider` contains the claims that your identity provider supplied during IAM federation. Each value is an object that contains claim-name and value pairs from that source.
+
@@ -387,0 +547,60 @@ The credential ID for the request. This is only set when the caller uses a beare
+## Trusted identity propagation
+
+When a request is made with credentials that carry trusted identity propagation (TIP) context, the `userIdentity` element can contain additional information about the human user or workload on whose behalf the call was made. TIP context comes from one of two paths:
+
+  * **IAM federation** – Sessions created through an IAM SAML or OIDC identity provider when trusted identity propagation is configured for that identity provider. For more information, see [Logging TIP activity with AWS CloudTrail](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_tip_cloudtrail.html) in the _IAM User Guide_.
+
+  * **IAM Roles Anywhere** – Sessions created through IAM Roles Anywhere, where the TIP context comes from an external X.509 certificate. For more information, see [Trusted identity propagation with IAM Roles Anywhere](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/trusted-identity-propagation.html) in the _IAM User Guide_.
+
+
+
+
+### `onBehalfOf` fields
+
+When a request is made with credentials that carry trusted identity propagation (TIP) context, the `onBehalfOf` element can contain additional attributes. These attributes identify the human user or workload on whose behalf the call was made. The `subject`, `subjectType`, `issuer`, and `federatedProviderArn` attributes appear for IAM federation sessions only if trusted identity propagation is configured for the IAM identity provider. For IAM Roles Anywhere sessions, the `subject`, `issuer`, and `federatedProviderArn` attributes appear only if trusted identity propagation is turned on for the profile. `subjectType` appears only if the profile also declares a subject type. These attributes also appear only for requests to AWS services that support TIP. `onBehalfOf` can appear with any `userIdentity` type.
+
+The `onBehalfOf` element can contain the following additional attributes:
+
+  * `subject` – The identifier of the human user or workload on whose behalf the call was made, as asserted by the trusted identity source, such as an identity provider for IAM federation, or an X.509 certificate for IAM Roles Anywhere.
+