Token-based Authentication User Attribution

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

What will you learn in this topic?

By the end of this topic, you will be able to:

• Understand how token-based authentication links API requests to authenticated users.

• Learn how to define the authentication scope for your environment and services.

• Learn how to extract and transform the JWT token from requests.

• Learn how to map JWT claims to authentication attributes for user attribution.

Understand token-based authentication user attribution

Token-based authentication user attribution helps you identify who is accessing your APIs by extracting identity claims from JWT or bearer tokens. It connects each request to a verified user and enriches it with contextual information such as role and scope, improving visibility, control, and threat analysis. The table below explains why you use it, when it applies, and how you can leverage it.

Steps to configure

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

Step 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.

Step 2 — Define the conditions to extract and transform the JWT token

1. (Optional) Click + Add Condition, then select and specify the location, key, operator, and value to use when Traceable checks 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 using commonly used values, you can modify it to suit your requirements.

3. (Optional) 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. Do one of the following according to your requirements:

   • If you use the default values Traceable defines, click Generate Preview in the Preview Attributes section on the right. This shows the payload and details Traceable extracts from the JWT token. You can also click View Details to see the values returned corresponding to each step above.

   • If you modified the values above, click Reload in the Preview Attributes section on the right. Post-reload, click Generate Preview to view the JWT Token extracted by Traceable. You can also click View Details to see the values returned corresponding to each attribute you configured above.

5. Click Next.

Step 3 — Define the authentication attributes

1. 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/User Scope/Custom:

     1. (Optional) Select the checkbox 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. (Optional) Click + Add Condition, then select and specify the location, key, operator, and value to use when Traceable checks spans for a match.

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

     5. (Optional) 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 steps below to add the Auth Type attribute, according to your requirements.

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

2. Generate the preview of the attribute value(s) by doing one of the following:

   • If you use the default values Traceable defines, click Generate Preview in the Preview Attributes section on the right. This shows the details generated in Step 2 above, and the value(s) extracted for the attributes. You can also click View Details to see the values returned corresponding to each attribute above.

   • If you modified the values above, click Reload in the Preview Attributes section on the right. Post-reload, click Generate Preview to view the details generated in Step 2 above, and the value(s) extracted for the attributes. You can also click View Details to see the values returned corresponding to each attribute you configured above.

3. Click Submit.

Examples and Demo

The following examples demonstrate how Traceable performs user attribution by extracting user identity claims from JWT tokens present in API requests:

{
  "name": "random", 
  "email": "random@txt.com",
  "sub": "demoAppUser",
  "iss": "demo-server",
  "jti": "987654b1-234b-5678-b2d4-d405c12345ab",
  "aud": "demo-app-users",
  "nbf": 1738644115
}

{
  "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"
}