User Attribution

User Attribution is the process of identifying a user ID, role, and other custom attributes. Once Traceable identifies these attributes, it is easier to associate them with the user action. This feature is also required to attribute the user requests across multiple user sessions. Correctly configured user attribution helps identify threat activities and prevent fraud. In the absence of user attribution:

• To understand a user’s activity, you would have to search through many sessions and IP addresses and stitch the data together.

• Only the IP address, not the user ID would be visible in the UI.

User attribution is also necessary as IP addresses can be shared, spoofed, or frequently changed. Correctly configured user attribution helps Traceable visualize user activity across devices and identify the user even in a shared network environment.

You can configure user attribution using either of the following authentication schemes:

• Basic — Configuration for detecting user ID from the basic authentication schema using the authorization header.

• Token-based — Configuration for detecting the user ID, role, and custom attributes from the JWT authentication schema using either the header or Cookie.

• Custom — Configuration for detecting user ID, role, and custom attributes from a custom authentication schema using headers, tokens, or credentials.

To configure user attribution, navigate to Settings () → User Attribution → User Attribution tab, click + Add User Attribution, and based on the authentication scheme you select, complete the steps in the following sections:

Basic Authentication

The basic authentication method uses the authorization header for transmitting user credentials, such as the user ID and password. These credentials are encoded using the Base64 encoding. This encoded string is used in the authorization header of an API request, allowing Traceable to identify the user using the credentials. When you select this method, Traceable uses the authorization header in this API request by default and attributes the user ID.

To configure basic authentication, complete the following steps:

1. Define the authentication scope:

   1. Specify the Name.

   2. (Optional) Specify a Description for the configuration.

   3. Select the Environment in which you wish to apply the configuration.

   4. Select the Services on which Traceable should apply the configuration. You can select all or specific services from the drop-down according to your requirements.

   5. (Optional) Specify the URL Regex if you wish to provide a granular scope for user attribution.

   6. Click Next.

2. Define the authentication attributes:

   1. Select the check box if you wish to Obfuscate the user ID value post-attribution, within the platform.

   2. Click + Add Condition, and select and specify the location, key, operator, and value based on which you want Traceable to check the spans for a match. If a span satisfies the condition, Traceable further evaluates the remaining configurations.

   3. Select the Location and specify the key where Traceable can find the user ID. While Traceable specifies this configuration by default based on the commonly used values, you can modify it according to your requirements.

   4. Click + Add Value Transformation to add either of the following custom transformations:

      • Regex Capture Group — This transformation enables you to extract specific parts of a string or value that match the pattern you define.

      • Base64 Decoder — This transformation enables you to convert encoded Base64 data back to its decoded or original format.

      While Traceable pre-adds some default transformations, you can add custom transformations. Traceable evaluates these transformations in order, from top to bottom.

      Note

      While you can modify the values, if any, in the pre-added transformations, you cannot reorder them. You can only reorder custom transformations according to your requirements.

   5. Click Submit.

Token-based Authentication

The token-based authentication method uses a token to transmit the user ID and role information. When setting up this method, you must specify conditions for Traceable to extract and transform the JWT token and define attributes according to your requirements. This authentication method is secure and scalable for setting up user attribution as it embeds the user's ID and role within the token, which the server can easily verify.

To configure token-based authentication, complete the following steps:

1. Define the authentication scope:

   1. Specify the Name.

   2. (Optional) Specify a Description for the configuration.

   3. Select the Environment in which you wish to apply the configuration.

   4. Select the Services on which Traceable should apply the configuration. You can either select all or specific services from the drop-down according to your requirements.

   5. (Optional) Specify the URL Regex if you wish to provide a granular scope for user attribution.

   6. Click Next.

2. Define the conditions to extract and transform the JWT token:

   1. Click + Add Condition, and select and specify the location, key, operator, and value based on which you want Traceable to check the spans for a match. If a span satisfies the condition, Traceable further evaluates the remaining configurations.

   2. Select the Location and specify the key where Traceable can find the JWT token. While Traceable specifies this configuration by default based on the commonly used values, you can modify it according to your requirements.

   3. Click + Add Value Transformation to add either of the following custom transformations:

      • Regex Capture Group — This transformation enables you to extract specific parts of a string or value that match the pattern you define.

      • Base64 Decoder — This transformation enables you to convert encoded Base64 data back to its decoded or original format.

      • JSON Path — This transformation enables you to navigate and select a specific key within a nested JSON structure.

      While Traceable pre-adds some default transformations, you can add custom transformations. Traceable evaluates these transformations in order, from top to bottom.

      Note

      You can modify the values, if any, in the pre-added transformations and reorder them according to your requirements.

   4. Click Next.

3. Define the authentication attributes according to your requirements. From the list of available attributes, select the one(s) you wish to add. Depending on the attribute you select, complete the following steps:

   • User ID/User Role/Custom:

     1. Select the check box if you wish to Obfuscate the value post-attribution, within the platform.

     2. (For Custom only) Specify the Key (Attribute Key) you wish to use as part of the authentication process.

     3. Click + Add Condition, and select and specify the location, key, operator, and value based on which you want Traceable to check the spans for a match.

     4. Specify the Claim Location in Token (JSON Path) where Traceable can find the attribute.

     5. Click + Add Value Transformation to add either of the following custom transformations:

        • Regex Capture Group — This transformation enables you to extract specific parts of a string or value that match the pattern you define.

        • Base64 Decoder — This transformation enables you to convert encoded Base64 data back to its decoded or original format.

        • JSON Path — This transformation enables you to navigate and select a specific key within a nested JSON structure.

        You can also reorder the transformations according to your requirements. Traceable evaluates them in order, from top to bottom.

     Repeat the above steps to add one or more attributes, or complete the below steps to add the Auth Type attribute, according to your requirements.

   • Auth Type: Select the authentication type from the drop-down list according to your requirements. You can also create a new one according to your requirements.

4. Click Submit.

{
  "sub": "1234567890",
  "name": "John Doe",
  "iat": 1516239022,
  "given_name": "John",
  "family_name": "Doe",
  "nickname": "john.doe",
  "updated_at": "2023-11-10T15:14:03.670Z",
  "email": "john.doe@traceable.ai",
  "email_verified": true,
  "iat": 1234567890,
  "exp": 1234567890,
  "sid": "Yzz-j5abcdefg9j9-abcdefghijk1jcz"
}

{
  "iat": 1730913437,
  "exp": 1762449437,
  "aud": "www.traceable.ai",
  "user-id": "johndoe.com",
  "GivenName": "John",
  "Surname": "Doe",
  "Email": "jdoe@traceable.ai",
  "role": "Administrator"
}

{
  "name": "John Doe",
  "iat": 1516239022,
  "given_name": "John",
  "family_name": "Doe",
  "sub": "john.doe",
  "updated_at": "2023-11-10T15:14:03.670Z",
  "email": "john.doe@traceable.ai",
  "email_verified": true,
  "iat": 1234567890,
  "exp": 1234567890,
  "sid": "Yzz-j5abcdefg9j9-abcdefghijk1jcz"
}

Custom Authentication

The custom authentication method is useful when your application system uses a custom authentication scheme and you wish to define a custom logic and method for attributing users. This method is useful when basic and token-based authentication schemes do not satisfy your business requirements.

To configure custom authentication, complete the following steps:

1. Define the authentication scope:

   1. Specify the Name.

   2. (Optional) Specify a Description for the configuration.

   3. Select the Environment in which you wish to apply the configuration.

   4. Select the Services on which Traceable should apply the configuration. Depending on your requirements, you can select all or specific services from the drop-down menu.

   5. (Optional) Specify the URL Regex if you wish to provide a granular scope for user attribution.

   6. Click Next.

2. Define the authentication attributes according to your requirements. From the list of available attributes, select the one(s) you wish to add. Depending on the attribute you select, complete the following steps:

   Note

   You can add one attribute each for User ID, User Role, and Auth Type, along with multiple Custom attributes.

   • User ID/User Role/Custom:

     1. Select the check box if you wish to Obfuscate the value post-attribution, within the platform.

     2. (For Custom attributes only) Specify the Key (Attribute Key) you wish to attribute as part of the authentication.

     3. Click + Add Condition, and select and specify the location, key, operator, and value based on which you want Traceable to check the spans for a match.

     4. Select the Location and specify the key where Traceable can find the attribute.

     5. Click + Add Value Transformation to add either of the following custom transformations:

        • Regex Capture Group — This transformation enables you to extract specific parts of a string or value that match the pattern you define.

        • Base64 Decoder — This transformation enables you to convert encoded Base64 data back to its decoded or original format.

        • JSON Path — This transformation enables you to navigate and select a specific key within a nested JSON structure.

        • JWT Payload Claim — This transformation enables you to extract the attribute present in the JWT payload.

        You can also reorder the transformations according to your requirements. Traceable evaluates them in order, from top to bottom.

     Repeat the above steps to add one or more attributes, or complete the below steps to add the Auth Type attribute, according to your requirements.

   • Auth Type:

     Select the authentication type from the drop-down list according to your requirements. You can also create a new one according to your requirements.

3. Click Submit.

Once you have configured the rules, Traceable shows them on the User Attribution page. The following details are shown for each rule:

• Name — The name you specified while creating the rule.

• Scope — The scope you defined in the rule. This can have either of the following values:

  • System Wide — This value is shown when you define the rule for execution across all environments.

  • Custom — This value is shown when you define the rule for execution in specific environments.

• Authentication Scheme — The authentication type (Basic, Token-based, or Custom) you selected before creating the rule.

You can also enable or disable the rules using the toggle corresponding to it. Traceable also allows you to reorder the rules by dragging them. Based on the rule order, Traceable executes them from top to bottom. For more information on how rule ordering plays an important role in their execution, see Rule Processing.

Apart from the above, Traceable enables you to perform the following actions on a rule:

• Edit — To update a rule, do either of the following:

  • Click the rule you wish to edit. Traceable opens the configuration page where you can modify the details.

  • Click the Ellipse () icon corresponding to a rule and click Edit.

• Delete — To delete a rule, click the Ellipse () icon corresponding to a rule and click Delete.

  Note

  A deleted rule cannot be restored.

Rule Processing

Traceable processes user attribution rules by breaking them down into individual components based on the attributes. This means that a rule appears as a single entity on the User Attribution page, however Traceable deconstructs it into separate rules based on each attribute type (User ID, User Role, Auth Type, and Custom) before evaluating them internally. Traceable evaluates these rules based on their sequence in the user interface, meaning the topmost rule is evaluated first followed by the ones below.

Traceable follows an all-match and first-match approach for processing rules according to the attribute type:

• User ID/User Role/Custom — All rules for the relevant attribute are collectively sent to the backend and evaluated on a first-match basis, depending on their sequence. Traceable evaluates each rule in the sequence, as mentioned above, and stops at the first matching rule, disregarding any subsequent rules for that attribute. This makes rule ordering important, as the highest one in the sequence takes effect.

• Auth Type — All rules for this attribute are sent to the backend and executed on an all-match basis depending on their sequence. Instead of stopping at the first match, Traceable collects all relevant matches into an array and shows them on the platform.

This sequential rule-based processing ensures accurate and flexible user attribution, especially for complex configurations. You can customize the priority and application of each rule by arranging them on the User Attribution page according to your business requirements.