AWS connect: Enforce secure authentication for profile linking in chat widget
Summary
Removed insecure user ID passing method and mandated JWT-based authentication for profile linking.
Security assessment
Removal of client-side user ID passing without security enables prevents potential spoofing attacks by enforcing JWT-based authentication.
Evidence
- * **Pass the user ID during initialization** – If security is not enabled on your widget, pass the authenticated user ID as an argument when initializing the tracker:
Diff
diff --git a/connect/latest/adminguide/chat-widget-data-tracker.md b/connect/latest/adminguide/chat-widget-data-tracker.md index 5f34b6341..ddb46bae3 100644 --- a//connect/latest/adminguide/chat-widget-data-tracker.md +++ b//connect/latest/adminguide/chat-widget-data-tracker.md @@ -163 +163 @@ Beyond the reserved event types, you can define any custom event type string (fo -Clickstream data captured by the web data tracker is continuously streamed to Customer Profiles and associated with the visitor's profile. The following table describes how that association behaves for anonymous and authenticated visitors. +Clickstream data captured by the web data tracker is continuously streamed to Customer Profiles. How data is associated with a profile depends on whether profile keys are provided during widget initialization. @@ -167,2 +167,2 @@ Clickstream data captured by the web data tracker is continuously streamed to Cu -Anonymous visitor | Tracked by session identifier only. Behavioral data is captured but not linked to a known customer identity. No personally identifiable information is collected. -Authenticated visitor | When you pass an authenticated user ID during widget initialization, the service links all clickstream activity to that user's known profile in Customer Profiles. This enables richer personalization and more accurate trigger conditions. +Visitor without profile keys (anonymous) | Tracked by an anonymous identifier stored in a browser cookie that expires after 7 days. During this period, clickstream data from the same visitor is linked to a single anonymous profile. After the cookie expires, a new anonymous identifier is generated and subsequent activity is tracked under a new profile. No personally identifiable information is collected. If profile keys are provided during widget initialization, clickstream data is linked to the corresponding known profile instead of the anonymous profile. +Visitor with profile keys | When you pass profile keys during widget initialization, the service links all clickstream activity to that user's known profile in Customer Profiles. This enables richer personalization and more accurate trigger conditions. @@ -170 +170 @@ Authenticated visitor | When you pass an authenticated user ID during widget ini -To associate tracking with an authenticated user, use one of the following approaches: +### Link web analytics events with existing profiles @@ -172 +172 @@ To associate tracking with an authenticated user, use one of the following appro - * **(Recommended) Use the CustomerId JWT claim** – If you enabled security on your Communications widget, include the authenticated user ID in the `CustomerId` field of your JSON Web Token (JWT) claims. This links clickstream activity to the user's profile without exposing the ID in client-side code. For setup details, see [Step 3: Confirm and copy communications widget code and security keys](./add-chat-to-website.html#confirm-and-copy-chat-widget-script). +To associate tracking with a known profile, set `profileKeys` in your JWT claims to search for and associate with an existing profile at connection time, and the service uses these keys to find a matching profile via the `SearchProfiles` API. This requires security to be enabled on your Communications widget. For setup details, see [Step 3: Confirm and copy communications widget code and security keys](./add-chat-to-website.html#confirm-and-copy-chat-widget-script). @@ -174 +173,0 @@ To associate tracking with an authenticated user, use one of the following appro - * **Pass the user ID during initialization** – If security is not enabled on your widget, pass the authenticated user ID as an argument when initializing the tracker: @@ -176 +175,10 @@ To associate tracking with an authenticated user, use one of the following appro - await window.amazon_connect.Web.ClickStream.init('<authenticated-user-id>'); + { + "sub": "<widgetId>", + "iat": 1234567890, + "exp": 1234571490, + "profileKeys": { + "_email": "[email protected]", + "_account": "ACCT-12345" + }, + "profileKeysOperator": "OR" + } @@ -177,0 +186 @@ To associate tracking with an authenticated user, use one of the following appro + * `profileKeys` – A key-value object where each key is a searchable Customer Profiles identifier (for example, `_email`, `_phone`, `_account`) and the value is the lookup value. @@ -178,0 +188 @@ To associate tracking with an authenticated user, use one of the following appro + * `profileKeysOperator` (optional) – `"AND"` or `"OR"` (default: `"OR"`). Determines whether the profile must match all keys or any key. @@ -179,0 +190 @@ To associate tracking with an authenticated user, use one of the following appro + * If exactly one profile is found, it is associated with the session. @@ -181 +192,24 @@ To associate tracking with an authenticated user, use one of the following appro -###### Important + * If no profile is found, the session proceeds anonymously (a new profile can be created later). + + * If multiple profiles are found, `window.amazon_connect.Web.ClickStream.init()` returns an error. Revise your key selection to ensure uniqueness. + + + + +### Grouping events by a custom identifier + +If you don't need to link to an existing profile but want to group clickstream activity on your own, you can provide a custom identifier. Clickstream events sharing the same identifier are grouped under a common `_webAnalyticsUserId` profile key. + +There are two ways to provide it: + + * **Via JWT claims** – Set the `customerId` field in your JWT claims (requires security enabled). + + * **Via initialization** – Pass the identifier as an argument when initializing the tracker: + + // Pass the custom user id as a positional string argument. + await window.amazon_connect.Web.ClickStream.init('<custom-user-id>'); + + + + +###### Note @@ -183 +217 @@ To associate tracking with an authenticated user, use one of the following appro -If an authenticated user ID is passed, it links to existing profiles through the account key. Since data tracker events accumulate over time, set object limits for `WebAnalytics-Clickstream` and `_webAnalytics` to prevent new events from overwriting other object types once the profile object limit is reached. For configuration guidance, see [Customer Profiles data limits](https://docs.aws.amazon.com/connect/latest/adminguide/customer-profiles-data-limits.html). +If `profileKeys` are also provided and resolve to an existing profile, profile resolution uses that result and skips this custom identifier.