AWS singlesignon medium security documentation change
Summary
Updated CloudTrail documentation to clarify user identification fields, added session correlation guidance using AuthWorkflowID, and deprecated reliance on userName/principalId fields
Security assessment
The change explicitly warns against using userName/principalId fields for auditing (which could lead to misattribution of actions) and provides secure alternatives (userId/identityStoreArn). This addresses potential security monitoring gaps by guiding proper user attribution in logs.
Diff
diff --git a/singlesignon/latest/userguide/sso-cloudtrail-use-cases.md b/singlesignon/latest/userguide/sso-cloudtrail-use-cases.md index a595d06e3..5ddc46816 100644 --- a//singlesignon/latest/userguide/sso-cloudtrail-use-cases.md +++ b//singlesignon/latest/userguide/sso-cloudtrail-use-cases.md @@ -5 +5 @@ -Identifying the user and session in IAM Identity Center user-initiated CloudTrail events Correlating usersViewing usersViewing a user’s SID +Identifying the user in IAM Identity Center user-initiated CloudTrail events Correlating user events within the same user sessionCorrelating users between IAM Identity Center and external directoriesViewing usersViewing a user’s SID @@ -13 +13 @@ The following sections describe the foundational use cases that inform your work -## Identifying the user and session in IAM Identity Center user-initiated CloudTrail events +## Identifying the user in IAM Identity Center user-initiated CloudTrail events @@ -24 +24 @@ IAM Identity Center emits two CloudTrail fields that enable you to identify the -The `userID` and `identityStoreArn` fields display in the `onBehalfOf` element nested inside the [`userIdentity`](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html) element as shown in the following example. This example shows these two fields on an event where the `userIdentity` type is "`IdentityCenterUser`". You can also include these fields on events for authenticated IAM Identity Center users where the `userIdentity` type is "`Unknown`". Your workflows should accept both type values. +The `userID` and `identityStoreArn` fields display in the `onBehalfOf` element nested inside the [`userIdentity`](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html) element as shown in the following example CloudTrail event log. This event log shows these two fields on an event where the `userIdentity` type is "`IdentityCenterUser`". You can also find these fields on events for authenticated IAM Identity Center users where the `userIdentity` type is "`Unknown`". Your workflows should accept both type values. @@ -38 +38 @@ The `userID` and `identityStoreArn` fields display in the `onBehalfOf` element n -###### Note +###### Tip @@ -40 +40 @@ The `userID` and `identityStoreArn` fields display in the `onBehalfOf` element n -We recommend you use `userId` and `identityStoreArn` for identifying the user behind IAM Identity Center CloudTrail events. Avoid using the fields `userName` or `principalId` under the `userIdentity` element when tracking the actions of an IAM Identity Center user who is signing in and using the AWS access portal. If your workflows, such as audit or incident response, depend on having access to the `username`, you have two options: +We recommend you use `userId` and `identityStoreArn` for identifying the user behind IAM Identity Center CloudTrail events. The `userName` and `principalId` fields under the `userIdentity` element are no longer available. If your workflows, such as audit or incident response, depend on having access to the `username`, you have two options: @@ -62 +62,5 @@ If you're automating the lookup of users in the IAM Identity Center directory, w -The `credentialId` value is set to the ID of the IAM Identity Center user’s session used to request the action. You can use this value to identify CloudTrail events initiated within the same authenticated IAM Identity Center user session except for sign-in events. +## Correlating user events within the same user session + +The [AuthWorkflowID](./understanding-sign-in-events.html) field emitted in sign-in events enables tracking all CloudTrail events associated with a sign-in sequence before the commencement of an IAM Identity Center user session. + +For user actions inside the AWS access portal, the `credentialId` value is set to the ID of the IAM Identity Center user’s session used to request the action. You can use this value to identify CloudTrail events initiated within the same authenticated IAM Identity Center user session in the AWS access portal. @@ -66 +70 @@ The `credentialId` value is set to the ID of the IAM Identity Center user’s se -The [`AuthWorkflowID`](https://docs.aws.amazon.com/singlesignon/latest/userguide/understanding-sign-in-events.html) field emitted in sign-in events enables tracking all CloudTrail events associated with a sign-in sequence before the commencement of an IAM Identity Center user session. +You can't use `credentialId` to correlate sign-in events to the subsequent events, such as the use of the AWS access portal. The value of the `credentialId` field emitted in sign-in events has internal use, and we recommend that you not rely on it. The value of the `credentialId` field emitted for [AWS access portal events](./sso-info-in-cloudtrail.html#cloudtrail-events-access-portal-operations) invoked with OIDC equals the ID of the access token. @@ -107 +111 @@ In certain cases, IAM Identity Center emits a user’s SID in the `principalId` -Correlating users between IAM Identity Center and external directories discusses how you can use the `externalId` and `username` fields to correlate an IAM Identity Center user to a matching user in an external directory. By default, IAM Identity Center maps `externalId` to the `objectguid` attribute in AD, and this mapping is fixed. IAM Identity Center allows administrators the flexibility to map `username` differently than its default mapping to `userprincipalname` in AD. +Correlating user events within the same user session describes how you can use the `externalId` and `username` fields to correlate an IAM Identity Center user to a matching user in an external directory. By default, IAM Identity Center maps `externalId` to the `objectguid` attribute in AD, and this mapping is fixed. IAM Identity Center allows administrators the flexibility to map `username` differently than its default mapping to `userprincipalname` in AD.