Transaction Tokens

2.1. What are Transaction Tokens?

Txn-Tokens are short-lived, signed JWTs [RFC7519] that assert the identity of a user or a workload and assert an authorization context. The authorization context provides information expected to remain constant during the execution of a call as it passes through multiple workloads.¶

2.2. Creating Txn-Tokens

2.3. Txn-Token Lifetime

Txn-Tokens are expected to be short-lived (order of minutes, e.g., 5 minutes), and as a result MAY be used only for the expected duration of an external invocation. If the token or other credential presented to the Txn-Token service when requesting a Txn-Token has an expiration time, then the Txn-Token MUST NOT exceed the lifetime of the originally presented token or credential. If a long-running process such as an batch or offline task is involved, it can use a separate mechanism to perform the external invocation, but the resulting Txn-Token is still short-lived.¶

2.4. Benefits of Txn-Tokens

Txn-Tokens help prevent spurious invocations by ensuring that a workload receiving an invocation can independently verify the user or workload on whose behalf an external call was made and any context relevant to the processing of the call. Through the presence of additional signatures on the Txn-Token, a workload receiving an invocation can also independently verify that specific workloads were within the path of the call before it was invoked.¶

2.5. Txn-Token Issuance and Usage Flows

     1    ┌──────────────┐    2      ┌──────────────┐
─────────▶│              ├───────────▶              │
          │   External   │           │  Txn-Token   │
     7    │   Endpoint   │    3      │   Service    │
◀─────────┤              ◀───────────│              │
          └────┬───▲─────┘           └──────────────┘
               │   │
             4 │   │ 6
          ┌────▼───┴─────┐
          │              │
          │   Internal   │
          │  µ-service   │
          │              │
          └────┬───▲─────┘
               │   │
               ▼   │
                 o
             5   o    6
                 o
               │   ▲
               │   │
          ┌────▼───┴─────┐
          │              │
          │   Internal   │
          │  µ-service   │
          │              │
          └──────────────┘

     1    ┌──────────────┐    2      ┌──────────────┐
─────────▶│              ├───────────▶              │
          │   External   │           │              │
     10   │   Endpoint   │    3      │              │
◀─────────┤              ◀───────────│              │
          └────┬───▲─────┘           │              │
               │   │                 │              │
             4 │   │ 9               │              │
          ┌────▼───┴─────┐           │              │
          │              │           │              │
          │   Internal   │           │              │
          │  µ-service   │           │              │
          │              │           │              │
          └────┬───▲─────┘           │  Txn-Token   │
               │   │                 │   Service    │
               ▼   │                 │              │
                 o                   │              │
             5   o    9              │              │
               │ o ▲                 │              │
               │   │                 │              │
               │   │                 │              │
          ┌────▼───┴─────┐    6      │              │
          │              ├───────────▶              │
          │   Internal   │           │              │
          │  µ-service   │    7      │              │
          │              ◀───────────│              │
          └────┬───▲─────┘           │              │
               │   │                 │              │
               ▼   │                 └──────────────┘
                 o
             8   o    9
                 o
               │   ▲
               │   │
          ┌────▼───┴─────┐
          │              │
          │   Internal   │
          │  µ-service   │
          │              │
          └──────────────┘

5.1. JWT Header

In the JWT Header:¶

• The typ claim MUST be present and MUST have the value txn_token.¶

• Key rotation of the signing key SHOULD be supported through the use of a kid claim.¶

Figure 3 is a non-normative example of the JWT Header of a Txn-Token¶

{
    "typ": "txn_token",
    "alg": "RS256",
    "kid": "identifier-to-key"
}

5.2. JWT Body Claims

The transaction token body follows the JWT format and includes existing JWT claims as well as defines new claims. These claims are described below:¶

iss:

OPTIONAL The iss claim as defined in [RFC7519] is not required as Txn-Tokens are bound to a single trust domain as defined by the aud claim and often the signing keys are known. The iss claim MUST be used in cases where the signing keys are not predetermined or it is desired that the Txn-Token Service signs with unique keys.¶

iat:

REQUIRED The issued at time of the Txn-Token as defined in [RFC7519]¶

aud:

REQUIRED This claim, defined in [RFC7519], contains the trust domain in which the Txn-Token is valid¶

exp:

REQUIRED Expiry time of the Txn-Token as defined in [RFC7519]¶

txn:

REQUIRED A unique transaction identifier as defined in Section 2.2 of [RFC8417]. When used in the transaction token, it identifies the entire call chain.¶

sub:

REQUIRED A unique identifier for the subject as defined by the aud trust domain. Unlike OpenID Connect, the sub claim is NOT associated with the iss claim.¶

purp:

REQUIRED A String defining the purpose or intent of this transaction.¶

azd:

OPTIONAL A JSON object that conatains values that remain immutable throughout the call chain.¶

rctx:

OPTIONAL A JSON object that describes the environmental context of the requested transaction.¶

{
    "rctx": {
      "req_ip": "69.151.72.123", // env context of external call
      "authn": "urn:ietf:rfc:6749", // env context of the external call
      "req_wl": [ "apigateway.trust-domain.example", "workload3.trust-domain.example" ]
}

{
    "iat": "1686536226000",
    "aud": "trust-domain.example",
    "exp": "1686536526000",
    "txn": "97053963-771d-49cc-a4e3-20aad399c312",
    "sub": "d084sdrt234fsaw34tr23t",
    "rctx": {
      "req_ip": "69.151.72.123", // env context of external call
      "authn": "urn:ietf:rfc:6749", // env context of the external call
      "req_wl": "apigateway.trust-domain.example" // the internal entity that requested the Txn-Token
    },
    "purp" : "trade.stocks",
    "azd": {
        "action": "BUY", // parameter of external call
        "ticker": "MSFT", // parameter of external call
        "quantity": "100", // parameter of external call
        "user_level": "vip" // computed value not present in external call
    }
}

7.1. Txn-Token Request

A workload requesting a Txn-Token must provide the Transaction Token Service with proof of its identity (client authentication), the purpose of the Txn-Token and optionally any additional context relating to the transaction being performed. Most of these elements are provided by the OAuth 2.0 Token Exchange specification and the rest are defined as new parameters. Additionally, this profile defines a new token type URN urn:ieft:params:oauth:token-type:txn-token which is used by the requesting workload to identify that it is requesting the Txn-Token Response to contain a Txn-Token.¶

To request a Txn-Token the workload invokes the OAuth 2.0 [RFC6749] token endpoint with the following parameters: * grant_type REQUIRED. The value MUST be set to urn:ietf:params:oauth:grant-type:token-exchange * audience REQUIRED. The value MUST be set to the Trust Domain name * scope REQUIRED. A space-delimited list of case-sensitive strings where the value(s) MUST represent the specific purpose or intent of the transaction. * requested_token_type REQUIRED. The value MUST be urn:ietf:params:oauth:token-type:txn-token * subject_token REQUIRED. The value MUST represent the subject of the transaction. This could be an OAuth access_token received by an API Gateway, a JWT assertion constructed by a workload initiating a transaction or a simple string value all identified by subject_token_type. * subject_token_type REQUIRED. The value MUST indicate the type of the token or value present in the subject_token parameter¶

The following additional parameters MAY be present in a Txn-Token Request:¶

• request_context OPTIONAL. This parameter contains a base64url encoded JSON object which represents the context of this transaction. The parameter SHOULD be present and how the Transaction Token Service uses this parameter is out of scope for this specification.¶

• request_details OPTIONAL. This parameter contains a base64url encoded JSON object which represents additional details of the transaction that MUST remain immutable throughout the processing of the transaction by multiple workloads.¶

The requesting workload MUST authenticate its identity to the Transaction Token Service. The exact client authentication mechanism used is outside the scope of this specification.¶

Figure 5 shows a non-normative example of a Txn-Token Request.¶

POST /txn-token-service/token_endpoint HTTP 1.1
Host: txn-token-service.trust-domain.example
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
&requested_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Atxn-token
&audience=http%3A%2F%2Ftrust-domain.example
&scope=finance.watchlist.add
&subject_token=eyJhbGciOiJFUzI1NiIsImtpZC...kdXjwhw
&subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aaccess_token
&request_context=eyAiaXBfYWRkcmVzcyI6ICIxMjcuMC4wLjEiLCAiY2xpZW50IjogIm1vYmlsZS1hcHAiLCAiY2xpZW50X3ZlcnNpb24iOiAidjExIiB9

7.2. Txn-Token Request Processing

When the Transaction Token Service receives a Txn-Token Request it MUST validate the requesting workload client authentication and determine if that workload is authorized to obtain the Txn-Tokens with the requested values. The authorization policy for determining such issuance is out of scope for this specification.¶

Next, the Transaction Token Service MUST validate the subject_token and determine the value to specify as the sub of the issued Txn-Token. The Txn-Token Service MUST ensure the sub value is unique within the trust domain defined by the aud claim.¶

The Transaction Token Service MUST set the iat claim to the time of issuance of the Txn-Token. The Transaction Token Service MUST set the aud claim to a Trust Domain of the Transaction Token Service. If the Transaction Token Service supports multiple trust domains, then it MUST determine the correct aud value for this request. The Transaction Token Service MUST set the exp claim to the expiry time of the Txn-Token. The Transaction Token Service MUST set the txn claim to a unique ID specific to this transaction.¶

The Transaction Token Service MAY set the iss claim of the Txn-Token to a value defining the entity that signed the Txn-Token. This claim MUST be ommitted if not set.¶

The Transaction Token Service MUST evaluate the value specified in the scope parameter of the request to determine the purp claim of the issued Txn-Token.¶

If a request_context parameter is present in the Txn-Token Request, the data SHOULD be added to the rctx object of the Txn-Token. In addition, the Transaction Token Service SHOULD add the authenticated requesting workload identifier in the rctx object as the req_wl claim.¶

If a request_details parameter is present in the Txn-Token Request, then the Transaction Token Service SHOULD propagate the data from the request_details object into the claims in the azd object as authorized by the Transaction Token Service authorization policy for the requesting client.¶

The Transaction Token Service MAY provide additional processing and verification that is outside the scope of this specification.¶

7.3. Txn-Token Response

A successful response to a Txn-Token Request by a Transaction Token Service is called a Txn-Token Response. If the Transaction Token Service responds with an error, the error response is as described in Section 5.2 of [RFC6749]. The following describes required values of a Txn-Token Response:¶

• The token_type value MUST be set to N_A per guidance in OAuth 2.0 Token Exchange [RFC8693]¶

• The access_token value MUST be the Txn-Token JWT¶

• The issued_token_type value MUST bet set to urn:ieft:params:oauth:token-type:txn-token¶

• The response MUST NOT include the values expires_in, refresh_token and scope¶

Figure 6 shows a non-normative example of a Txn-Token Response.¶

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache, no-store

{
  "token_type": "N_A",
  "issued_token_type": "urn:ieft:params:oauth:token-type:txn-token",
  "access_token": "eyJCI6IjllciJ9...Qedw6rx"
}

7.4. Creating Replacement Txn-Tokens

A workload within a call chain may request the Transaction Token Server to replace a Txn-Token.¶

Workloads MAY request replacement Txn-Tokens in order to change (add to, remove or modify) the asserted values within a Txn-Token.¶

The values of the sub and aud claims MUST remain unchanged in a replacement Txn-Token. If the claim rctx is present in the original Txn-Token, then it MUST be present and unchanged in the replacement Txn-Token except for the req_wl claim which MUST be updated to include the requesting workload identifier.¶

7.5. Mutual Authentication of the Txn-Token Request

A Txn-Token Service MUST ensure that it authenticates any workloads requesting Txn-Tokens. In order to do so:¶

• It MUST name a limited, pre-configured set of workloads that MAY request Txn-Tokens¶

• It MUST individually authenticate the requester as being one of the named requesters¶

• It SHOULD rely on mechanisms, such as [Spiffe] or some other means of performing MTLS [RFC8446], to securely authenticate the requester¶

• It SHOULD NOT rely on insecure mechanisms, such as long-lived shared secrets to authenticate the requesters¶

The requesting workload MUST have a pre-configured location for the Transaction Token Service. It SHOULD rely on mechanisms, such as [Spiffe], to securely authenticate the Transaction Token Service before making a Txn-Token Request.¶

8.1. Txn-Token HTTP Header

A workload that invokes another workload using HTTP and needs to present a Txn-Token to the invoked workload MUST use the HTTP Header Txn-Token to communicate the Txn-Token. The value of this header MUST be the JWT that represents the Txn-Token.¶

9.1. Txn-Token Lifetime

A Txn-Token is not resistant to replay attacks. A long-lived Txn-Token therefore represents a risk if it is stored in a file, discovered by an attacker, and then replayed. For this reason, a Txn-Token lifetime must be kept short, not exceeding the lifetime of a call-chain. Even for long-running "batch" jobs, a longer lived access token should be used to initiate the request to the batch endpoint. It then obtains short-lived Txn-Tokens that may be used to authorize the call to downstream services in the call-chain.¶

Because Txn-Tokens are short-lived, the Txn-Token response from the Txn-Token service does not contain the refresh_token field. A Txn-Token cannot be issued by presenting a refresh_token.¶

The expires_in and scope fields of the OAuth 2.0 Token Exchange specification [RFC8693] are also not used in Txn-Token responses. The expires_in is not required since the issued token has an exp field, which indicates the token lifetime. The scope field is omitted from the request and therefore omitted in the response.¶

9.2. Access Tokens

When creating Txn-Tokens, the Txn-Token MUST NOT contain the Access Token presented to the external endpoint. If an Access Token is included in a Txn-Token, an attacker may extract the Access Token from the Txn-Token, and replay it to any Resource Server that can accept that Access Token. Txn-Token expiry does not protect against this attack since the Access Token may remain valid even after the Txn-Token has expired.¶

9.3. Client Authentication

How requesting clients authenticate to the Transaction Token Service is out of scope for this specification. However, if using the actor_token and actor_token_type parameters of the OAuth 2.0 Token Exchange specification, both parameters MUST be present in the request. The actor_token MUST autenticate the identity of the requesting workload.¶

10.1. Obsfucation of Personal Information

Some rctx claims may be considered personal information in some jurisdictions and if so their values need to be obsfucated. For example, originating IP address (req_ip) is often considerd personal information and in that case must be protected through some obsfucation method (e.g. SHA256).¶

11.1. OAuth Registry Contents

• Name: txn_token¶

• Description: JWT of type Transaction Token¶

• Additional Token Endpoint Response Parameters: none¶

• HTTP Authentication Schemes: TLS [RFC8446]¶

• Change Controller: IESG¶

• Specification Document: Section Section 5.1 of this specificaiton¶

11.2. JWT Registry Contents

• Claim Name: azd¶

  • Claim Description: The authorization context details¶

  • Change Controller: IESG¶

  • Specification Document: Section Section 5.2 of this specification¶

• Claim Name: rctx¶

  • Claim Description: The requester context¶

  • Change Controller: IESG¶

  • Specification Document: Section Section 5.2.1 of this specification¶

• Claim Name: purp¶

  • Claim Description: The purpose of the transaction¶

  • Change Controller: IESG¶

  • Specification Document: Section Section 5.2 of this specification¶