Transaction token

Edit online

Transaction tokens are specialized, limited-validity OAuth 2.0 tokens designed to provide secure authorization for service-to-service communication within a trust domain. Based on the IETF draft specification (draft-ietf-oauth-transaction-tokens), these tokens are signed JWTs that carry immutable context and authorization information for specific transactions.

Note: Transaction token is a requestable feature, VDEV-186514: Securing AI Agents. To request this feature, contact your IBM Sales representative or IBM contact and indicate your interest in enabling this capability. You can also create a support ticket with the feature number if you have the permission. IBM® Verify trial subscriptions cannot create support tickets.

About Transaction tokens

In modern microservice architectures, a single external request often triggers internal workflows involving multiple services. Transaction tokens address the security challenges in these scenarios by providing the following:
  • Immutable Transaction Context: The tctx (transaction context) claim contains transaction-specific information that cannot be modified throughout the call chain, preventing parameter tampering.
  • Complete Traceability: Each transaction token includes a unique transaction identifier (txn claim) that enables end-to-end tracking across all services involved in processing a request.
  • Workload Authorization: The req_wl (requester workload) claim maintains a chain of all workloads that have handled the transaction, enabling precise authorization decisions based on the call path.
  • Context Preservation: When a transaction token is used as a subject token in subsequent token exchanges (replacement tokens), the transaction context and identifier are preserved, ensuring consistency across the entire workflow.

Configuring Transaction token in IBM Verify

Transaction tokens can be requested through the standard OAuth 2.0 Token Exchange flow and can be configured by using either an STS client or an OpenID Connect application.
For STS clients
  1. Navigate to the Admin Console and select Applications > STS clients. Click Add STS client.
  2. In the Token exchange settings step, select Transaction token from the dropdown menu of Requested token.
    Note: Transaction tokens can also be configured as the subject token or actor token, depending on your use case.
  3. In the Requested token settings step, you can find an option to configure the Transaction context. This field accepts a CELx expression whose output is directly mapped to the tctx claim in the resulting transaction token. The expression must evaluate to a valid JSON object. For example, 
    {
  "amount": "100.00",
  "currency": "USD",
  "merchant_id": "requestContext.subject_token.email"
}
    Note: The Transaction context field is only visible when the Requested token is set to Transaction token. This field is not applicable for other token types.
  4. Configure the remaining required properties and click Save to create the STS client.
For Applications
  1. Navigate to the Admin Console and select Applications > Applications. Click Add application and select any of the OpenID Connect related application.
  2. In the Sign-on tab and navigate to the Token exchange section. Select Transaction token from the dropdown menu for Requested token.
    Note: Transaction tokens can also be configured as the subject token or actor token, depending on your use case.
  3. Configure the Transaction context as a CELx expression that evaluates to a valid JSON object. This is directly mapped to the tctx claim in the resulting transaction token.
    Note: The Transaction context field is only visible when the Requested token is set to Transaction token. This field is not applicable for other token types.
  4. Configure the remaining required properties and click Save to create the application.

Transaction context mapping

A distinguishing feature of transaction tokens is the tctx (transaction context) claim which is an immutable claim that defines the context of the transaction being performed. When a transaction token is used as a subject token in a subsequent token exchange flow, the resulting token preserves the same tctx claim, enabling complete traceability throughout the transaction lifecycle.

Transaction context generation logic

IBM Verify determines the tctx claim for a transaction token by using the following precedence rules:
  1. CELx Expression defined: If a Transaction context CELx expression is configured (as described in the preceding Step 4), the expression is evaluated and its result is used as the tctx claim.
  2. Request details provided: If no CELx expression is configured and the token exchange request includes a request_details parameter, the value of request_details is used as the tctx claim.
  3. No context available: If neither a CELx expression nor request_details is provided, the tctx claim is omitted from the Transaction token.

CELx expression examples

The following examples demonstrate Transaction context mapping CELx expressions for common scenarios:
Scenario 1: Defining a complete Transaction context
This example defines a complete JSON payload for the tctx claim. The subject and actor token claims are available in CELx as requestContext.subjectToken and requestContext.actorToken respectively: 
{
  "amount": "100.00",
  "currency": "USD",
  "merchant_id": "requestContext.subject_token.email"
}
Scenario 2: Enhancing request details with runtime values
The request_details parameter from the token exchange request is accessible in CELx expressions as requestContext.tctx. You can enhance this context by adding computed values at runtime: 
requestContext.tctx.put("requestingUserName", user.userName)
For complete CELx syntax documentation, see the Attribute functions guide.