Session identification in Traceable allows you to track user activity across multiple requests by extracting and analyzing session IDs from API traffic. This identification enables the viewing of a user’s session and facilitate authentication, validation, and enforcement of protection policies for these users. Identifying sessions enables Traceable to evaluate user behavior and enforce protection effectively.

What will you Learn from this Topic?

By the end of this topic, you will understand:

What is Session Identification, and how is it useful for tracking user behavior and detection in your application ecosystem.
How to configure Session Identification rules using request/response fields, conditions, and transformations.
How to view and manage Session Identification rules.
How is the Session Identification Rule ID mapped, and how can you use it to validate your rules.

What is Session Identification?

Session identification is the process of extracting unique IDs from API traffic that represent a user’s session.

Where are the session IDs found?

Session IDs can be located in various parts of an API request or response, including headers, cookies, query parameters, and request or response bodies.

How does Traceable capture the IDs?

During a user's interaction with your application, the session ID remains constant across multiple API calls. Traceable captures these IDs from incoming requests as Client Session IDs, which are the actual values present in the traffic. Depending on the user behavior, Traceable processes these client session IDs in the following ways:

If the session remains active without a refresh, the Client Session ID is used as the Session ID.
If the user refreshes the session during an interaction, the Client Session ID changes. In this case, Traceable intelligently correlates the multiple Client Session IDs into a single Session ID that represents a continuous session.

This ensures seamless tracking of the user’s session, even if new IDs are generated, providing a more accurate view.

Traceable shows both Client Session IDs and Session ID on the Analytics → Explorer page. For more information, see Viewing Extracted Session IDs.

Why should you use Session Identification?

Setting up session identification and enabling rules provides you with the necessary visibility into the API interactions within user sessions in your application ecosystem. It helps you in the following ways:

Track User Behavior and Analytics — Understand and trace the sequence and how a user interacts with your APIs during a session.
Anomaly Detection — Identify risks and session misuse by reusing tokens post-session expiration.
Enforce Protection Policies — Use the session-based information to create and apply policies that detect threats, such as Broken Object-Level Authorization (BOLA).

How to set up Session Identification

To configure session identification, complete the following steps:

Step 1 — Define the Session Identification Rule Details

Navigate to Settings () → User Attribution → Session Identification tab, and click + Add Session Identification.
Specify the following details:
- Name — A name for rule identification.
- (Optional) Description — A description of what the rule does.
Define the Scope by selecting or specifying the following:
- Environment — The environment(s) where you want the rule to apply. Default: All Environments.
- Services — All or specific services where you want the rule to apply. Default: All Services.
  Note
  When you select All Services, Traceable automatically adds any new services added in the future to the scope.
- (Optional) URL Regexes — Granular scoping of session identification according to your requirements.

Step 2 — Define the Session Identifier(s)

Select the Request or Response where you want Traceable to find the session ID.
(Optional) Click + Add Condition to add one or more conditions that Traceable should evaluate before extracting the ID.
Note
If you add more than one condition, Traceable performs an AND operation between them, which means that all conditions must be satisifed before the next steps are evaluated.
Select the specific Location, Key, Operator, and Value from which Traceable can extract the session token.
(Optional) Click Add Value Transformation + to add either of the following custom transformations:
- Regex Capture Group — Enables you to extract specific parts of a string or value that match the pattern you define.
- Base64 Decoder — Enables you to convert encoded Base64 data back to its decoded or original format.
- JSON Path — Enables you to navigate and select a specific key within a nested JSON structure.
- JWT Payload Claim — Enables you to extract the attribute in the JWT payload.
(Optional) Select the Obfuscate Session Token Value check box to session ID post-extraction.
(Optional) Set Token Expiration to define session expiry:
1. JWT Based — Traceable automatically derives expiry from the JWT token’s exp attribute.
2. Attribute Based (For Response only):
  1. Select the specific Location, Key, Operator, and Value from which Traceable can extract the session expiry.
  2. Click Add Value Transformation + to add a custom transformation. The available options are similar to those listed in Step 4 above.
  3. Select the Token Expiration Format that Traceable can use to decode the token expiration:
    - Duration in Milliseconds — Specifies the lifetime duration of a session, for example, 60000 for 60 seconds. The session is valid for the specific milliseconds from the time it was first observed.
    - Duration in Seconds — Similar to the above, expressed in seconds, for example, 60 for 60 seconds. The session is valid for the specific seconds from the time it was first observed.
    - Timestamp Epoch in Milliseconds — Specifies the UNIX timestamp represented as milliseconds, for example, 1716297600000.
    - Timestamp Epoch in Seconds — Similar to the above, expressed in seconds, for example, 171629600.
Click + Add Identifier at the top of the section and add more identifiers according to your requirements.

Step 3 — Review and Save

At the bottom of the page, click Review.
Verify the details you specified in Steps 1 and 2 above.
At the bottom of the page, click Submit.

To view the session identification rule you created, see the section below.

Viewing and Managing Session Identification Rules

The following list highlights the available information and action for each session identification rule that you configure:

Viewing Extracted Session IDs

You can view the extracted Client Session IDs and Session ID in the Analytics → Explorer → Endpoint Traces → Results section.

Traceable provides two ways to access the IDs:

Table Columns — View the Client Session IDs and Session ID columns directly in the Results table. If these columns are not visible by default, click any column header, select Edit Columns, and add the required columns.
Trace Attributes — Expand any trace entry and navigate to the Attributes tab under it. The extracted session ID is shown under the key format: traceableai.session.<rule_id>.<session_identifier_index>.id.
For information on how Traceable maps this field, see Identification Rule Mapping.

Note
If multiple client session IDs are extracted, Traceable shows them in both the Table Columns and the Attributes tab.

Identification Rule Mapping

This section discusses the following:

Difference between session identifiers and session IDs.
How Traceable correlates the identification rule, session identifiers, and session ID, along with an example.
How and where can you view the mapped session IDs

Understanding Session Identifiers and Session IDs

In Session Identification, session identifiers and session IDs are important parameters that define how Traceable maps user activity across API calls.

A session identifier defines where Traceable should search in the API traffic to extract session-related data. This can be a specific location, such as a header, a cookie, or a query parameter within the request or response. You can define one or more session identifiers while creating a session identification rule. For more information, see How to set up Session Identification.

A session ID is the actual value that Traceable extracts from the location defined in the session identifier. The following section discusses how Traceable

For example, if you configure a session identifier having the location as the Authorization header, Traceable extracts the session ID from the incoming traffic. This can be a value such as e1ab12d3-123d-e2de-a12f-d1ab5cde789f. Traceable uses these session IDs to correlate and track user activity.

How Traceable Maps Session IDs

Each session identification rule configured in Traceable is assigned a unique Rule ID, which is visible on the Session Identification page. This Rule ID helps you trace how Traceable extracts and highlights session IDs.

When you create a rule with multiple session identifiers, Traceable assigns an index value to each identifier in the following manner:

The first session identifier is assigned the index 0.
The second identifier is assigned the index 1.
The third identifier is assigned the index 2.

This indexing continues incrementally for each identifier you add to a rule. This index acts as a reference for you to trace the identifier using which Traceable extracted the session ID.

Once you create a rule, Traceable uses a standardized format to map the extracted session IDs. The mapping is as follows:

traceableai.session.<rule_id>.<session_identifier_index>.id

In the above mapping:

<rule_id> is the unique rule ID for the session identification rule.
<session_identifier_index> is the index of the session identifier within the above rule.

You can view these mapped session IDs in the Analytics → Explorer page. For more information, see Viewing Extracted Session IDs.

Session ID Mapping Example

Consider a session identification rule with the following Rule ID:

fd012c51-7891-45f8-bfd9-e5ea1023e7b2

This rule contains three session identifiers:

Index 0 — The Request Header key equals authorization_token
Index 1 — The Response Cookie key equals SESS_ID
Index 2 — The Request Parameter key equals S_ID

When Traceable extracts a Session ID using the Response Cookie (index 1), the corresponding attribute field is shown as:

traceableai.session.fd012c51-7891-45f8-bfd9-e5ea1023e7b2.1.id

The value of this field is the session ID Traceable captured from the API traffic, such as e1ab12d3-123d-e2de-a12f-d1ab5cde789f.

How is Rule Mapping Helpful?

Traceable’s mapping of session IDs helps you:

Trace each session ID to the specific rule and identifier that captured it.
Debug and refine rules according to your requirements.
Correlate the sessions across API traffic for analysis and threat detection.

product

personas

learn

company