Merge branch 'main' into Sub-description

PieterKas · web-flow · commit a723cce89dfe · 2025-11-17T11:19:22.000Z
diff --git a/draft-ietf-oauth-transaction-tokens.md b/draft-ietf-oauth-transaction-tokens.md
@@ -155,7 +155,7 @@ A key aspect of the authorization context is the intent or purpose of the transa
 
 ## Creating Txn-Tokens
 
-### Initial Creation
+### Creation
 Txn-Tokens are typically created when a workload is invoked using an endpoint that is externally visible, and is authorized using a separate mechanism, such as an OAuth {{RFC6749}} access token. The externally visible endpoint exchanges the external authorization token for a transaction token before sending it to the workload. The transaction token may be obtained through a local interface, or it may be requested from a remote server.
 
 If the transaction token request is made via HTTP to a remote server, it MUST use {{RFC8693}} as described in this specification. To do this, it invokes a special Token Service (the Txn-Token Service) and provides context that is sufficient for it to generate a Txn-Token. The context information provided to the Txn-Token Service MAY include:
@@ -169,11 +169,6 @@ The Txn-Token Service responds to a successful invocation by generating a Txn-To
 
 If the requesting service does not have an inbound token that it can use in its request to the Txn-Token Service, it generates a self-signed JWT and passes that in the request in place of the external authorization token. This can be the case when the external authentication does not use an access token or when the requesting service is initiating a scheduled internal request on for itself or on behalf of a user of the system.
 
-### Replacement Txn-Tokens
-A service within a call chain may choose to replace the Txn-Token. This can typically happen if the service wants to add to the context of the current Txn-Token
-
-To get a replacement Txn-Token, a service will request a new Txn-Token from the Txn-Token Service and provide the current Txn-Token and other parameters in the request. The Txn-Token service must be careful about the types of replacement requests it supports to avoid undermining the entire value of Txn-Tokens.
-
 ## Txn-Token Lifetime
 Txn-Tokens are expected to be short-lived (on the order of minutes or less), and as a result MUST be used only for the expected duration of an external or internal invocation. If the token or other credential (e.g. self-signed JWT)  presented to the Txn-Token service when requesting a Txn-Token has an expiration time, then the Txn-Token Service MUST NOT issue a Txn-Token if the expiration time has passed. The lifetime of the Txn-Token itself MAY exceed the expiration time of the presented token. The expectation is that since Txn-Tokens are short lived and are authorizing a specific transaction, extending beyond the lifetime of the presented expiration time is not a security risk. If a long-running process such as a batch or offline task is involved, the mechanism used to perform the external or internal invocation still results in a short-lived Txn-Token.
 
@@ -225,65 +220,6 @@ Txn-Tokens prevent unauthorized or unintended invocations by allowing a workload
 6. Responses are provided to callers based on successful authorization by the invoked workloads
 7. External client is provided a response to the external invocation
 
-### Replacement Txn-Token Flow {#replacement-flow}
-
-An intermediate service may decide to obtain a replacement Txn-Token from the Txn-Token service. That flow is described below in {{fig-arch-replacement}}
-
-~~~ ascii-art
-
-     1    +--------------+    2      +--------------+
---------->│              │---------->│              │
-          │   External   │           │              │
-     10   │   Endpoint   │    3      │              │
-<---------│              │<----------│              │
-          +--------------+           │              │
-               │   ^                 │              │
-             4 v   │ 9               │              │
-          +--------------+           │              │
-          │              │           │              │
-          │   Internal   │           │              │
-          │   Workload   │           │              │
-          │              │           │              │
-          +--------------+           │  Txn-Token   │
-               │   ^                 │   Service    │
-               v   │                 │              │
-                 o                   │              │
-             5   o    9              │              │
-               │ o ^                 │              │
-               │   │                 │              │
-               v   │                 │              │
-          +--------------+    6      │              │
-          │              │---------->│              │
-          │   Internal   │           │              │
-          │   Workload   │    7      │              │
-          │              │<----------│              │
-          +--------------+           │              │
-               │   ^                 │              │
-               v   │                 +--------------+
-                 o
-             8   o    9
-                 o
-               │   ^
-               v   │
-          +--------------+
-          │              │
-          │   Internal   │
-          │   Workload   │
-          │              │
-          +--------------+
-~~~
-{: #fig-arch-replacement title="Replacement Txn-Token Flow"}
-
-In the diagram above, steps 1-5 are the same as in {{basic-flow}}
-
-{:start="6"}
-
-6. An intermediate service determines that it needs to obtain a Replacement Txn-Token. It requests a Replacement Txn-Token from the Txn-Token Service. It passes the incoming Txn-Token in the request, along with any additional context it needs to send the Txn-Token Service.
-7. The Txn-Token Service responds with a replacement Txn-Token
-8. The service that requested the Replacement Txn-Token uses that Txn-Token for downstream call authorization
-9. Responses are provided to callers based on successful authorization by the invoked workloads
-10. External client is provided a response to the external invocation
-
 ### Internally Initiated Txn-Token Flow
 
 An internal workload may need to initiate a transaction not on the basis of a current external request, but as part of a scheduled task or in reaction to a specific condition. The transaction may be requested on behalf of the identity of the requesting workload or as an impersonation on behalf of a specific user chosen based on information accessible to the workload.
@@ -321,7 +257,7 @@ An internal workload may need to initiate a transaction not on the basis of a cu
 ~~~
 {: #fig-arch-internal title="Internally Initiated Txn-Token Flow"}
 
-In the diagram above, steps 5-6 are the same as in {{basic-flow}}.  The flow can also be used to replace steps 1-4 in the {{replacement-flow}}}
+In the diagram above, steps 5-6 are the same as in {{basic-flow}}.
 
 {:start="1"}
 
@@ -330,8 +266,6 @@ In the diagram above, steps 5-6 are the same as in {{basic-flow}}.  The flow can
 3. Txn-Token Service authorizes the requester and then mints a Txn-Token that provides immutable context for the transaction and returns it to the requester
 4. The originating microservice then contacts another internal microservice and provides the Txn-Token as authorization
 
-
-
 # Notational Conventions
 
 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
@@ -357,7 +291,6 @@ Call Chain:
 Transaction Token (Txn-Token):
 : A signed JWT with a short lifetime, providing immutable information about the user or workload, certain parameters of the call, and specific contextual attributes of the call. The Txn-Token is used to authorize subsequent calls in the call chain.
 
-
 Transaction Token Service (Txn-Token Service):
 : A special service within the Trust Domain that issues Txn-Tokens to requesting workloads. Each Trust Domain using Txn-Tokens MUST have exactly one logical Txn-Token Service.
 
@@ -413,6 +346,9 @@ JWT claims as well as defines new claims. These claims are described below:
 `rctx`:
 : OPTIONAL A JSON object that describes the environmental context of the requested transaction.
 
+`req_wl`:
+: REQUIRED. A StringOrURI value that identifies the workload that requested the Txn-Token.
+
 ### Scope claim {#scope-claim}
 The `scope` claim captures, as narrowly as possible, the purpose of this particular transaction. The values used for this claim are defined by the Transaction Token Service as representative of the authorization model defined by the Trust Domain. The value may be literately and semantically different from, and represent an intent narrower, than a scope value issued to an external client. How a given deployment represents the authorization model within the Trust Domain is at its discretion and not prescribed by this specification.
 
@@ -423,7 +359,19 @@ The JSON value of the `rctx` claim MAY include any values the Txn-Token Service
 
 * `req_ip` The IP address of the requester. This MAY be the end-user or a robotic process that requested the Transaction
 * `authn` The authentication method used to identify the requester. Its value is a string that uniquely identifies the method used.
-* `req_wl` The requesting workload. A string that uniquely identifies the computational entity that requested the Txn-Token. This entity MUST be within the Trust Domain of the Txn-Token. If a replacement Txn-Token has been requested, then this claim will be an array of string representing the different workloads that have requested Txn-Tokens as part of the transaction processing.
+* `req_wl` The requesting workload. A string that uniquely identifies the computational entity that requested the Txn-Token. This entity MUST be within the Trust Domain of the Txn-Token.
+
+The following is a non-normative example of an `rctx` claim initiated by an external call:
+
+~~~ json
+{
+    "rctx": {
+      "req_ip": "69.151.72.123", // env context of external call
+      "authn": "urn:ietf:rfc:6749", // env context of external call
+      "req_wl": [ "apigateway.trust-domain.example", "workload3.trust-domain.example" ]
+    }
+}
+~~~
 
 ### Transaction Context {#transaction-context}
 The Txn-Token SHOULD contain an `tctx` claim. The value of this claim is a JSON object that contains name/value pairs (wherein the value could itself be an object), which together assert the details that remain immutable through the call-chain where this Txn-Token is used.
@@ -446,22 +394,6 @@ The following is a non-normative example of an `tctx` claim initiated by an exte
 }
 ~~~
 
-#### Requesting Workload Identifier
-
-It is useful to be able to track the set of workloads that have requested a Txn-Token. The `req_wl` claim allows for tracking this information even through requests for a replacement Txn-Token. By default, the `req_wl` is a string representing the original workload entity that requested the Txn-Token. However, if a workload within the path of servicing the transaction requests a replacement Txn-Token, then the Transaction Token Service will append the new requesting workload as a subsequent array element in the `req_wl` claim. This provides a "pathing" mechanism to track which services have requested replacement Txn-Tokens. If there is only a single value the `req_wl` will be a string. If there is more than a single value, then `req_wl` will be represented by an array of strings.
-
-The following is a non-normative example of an `rctx` claim initiated by an external call:
-
-~~~ json
-{
-    "rctx": {
-      "req_ip": "69.151.72.123", // env context of external call
-      "authn": "urn:ietf:rfc:6749", // env context of external call
-      "req_wl": [ "apigateway.trust-domain.example", "workload3.trust-domain.example" ]
-    }
-}
-~~~
-
 ### Example
 The figure below {{figleaftxtokenbody}} shows a non-normative example of the JWT body of a Txn-Token initiated by an external call:
 
@@ -613,29 +545,6 @@ Cache-Control: no-store
 ~~~
 {: #figtxtokenresponse title="Example: Txn-Token Response"}
 
-## Creating Replacement Txn-Tokens
-A workload within a call chain may request the Transaction Token Service 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 `txn`, `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.
-
-### Txn-Token Service Responsibilities
-When issuing replacement Txn-Tokens, a Txn-Token Service:
-
-* MAY enable modifications to asserted values that reduce the scope of permitted actions
-* MAY enable additional asserted values
-* MUST NOT enable modification to asserted values that expand the scope of permitted actions
-* MUST NOT modify `sub` and `aud` values of the Txn-Token in the request
-* MUST NOT remove any of the existing requesting workload identifiers from the `req_wl` field in the `rctx` claim of the Txn-Token
-* MUST NOT issue replacement Txn-token with lifetime exceeding the lifetime of the originally presented token
-
-### Replacement Txn-Token Request
-To request a replacement Txn-Token, the requester makes a Txn-Token Request as described in {{txn-token-request}} but includes the Txn-Token to be replaced as the value of the `subject_token` parameter and sets the `subject_token_type` parameter to the value `urn:ietf:params:oauth:token-type:txn_token`. The `scope` value in the replacement request, if different from that in the original Txn-Token, MUST NOT increase the granted authorization beyond that of the original Txn-Token.
-
-### Replacement Txn-Token Response
-A successful response by the Txn-Token Service to a Replacement Txn-Token Request is a Txn-Token Response as described in {{txn-token-response}}
-
 ## Mutual Authentication of the Txn-Token Request {#Mutual-Authentication}
 A Transaction Token Service and requesting workload MUST authenticate each other (mutual authentication). Workloads MUST authenticate the Transaction Token Service to ensure that they do not disclose sensitive information, such as OAuth access tokens, to a rogue Transaction Token Service. A Transaction Token Service MUST authenticate a workload to ensure the workload is authorized to request a transaction token.
 
@@ -667,11 +576,8 @@ A service requesting a Txn-Token SHOULD provide an incoming token if it has one
 ## Use of 'actor_token'
 If using the `actor_token` and `actor_token_type` parameters of the OAuth 2.0 Token Exchange specification {{RFC8693}}, both parameters MUST be present in the request. The `actor_token` can authenticate the identity of the requesting workload.
 
-## Replacement Tokens
-Validation of a replacement Txn-Token, as well as any Txn-Token, is critical to the security of the entire transaction invocation sequence. Only Txn-Tokens issued by a trusted Transaction Token Service may be trusted, so verification of the Txn-Token signature is required. For replacement transaction tokens, not only must the JWT signature be verified but also the workload identity of the workload requesting the replacement Txn-Token.
-
 ## Scope Processing
-The authorization model within a Trust Domain boundary may be quite different from the authorization model (e.g. OAuth scopes) used with clients external to the Trust Domain. This makes managing unintentional scope increase a critical aspect of the Transaction Token Service. The Transaction Token Service MUST ensure that the requested `scope` of the Txn-Token is equal or less than the scope(s) identified in the `subject_token`. This is also true of requesting a replacement Txn-Token. The Transaction Token Service MUST ensure there is no unintentional privilege escalation in authorization scope.
+The authorization model within a Trust Domain boundary may be quite different from the authorization model (e.g. OAuth scopes) used with clients external to the Trust Domain. This makes managing unintentional scope increase a critical aspect of the Transaction Token Service. The Transaction Token Service MUST ensure that the requested `scope` of the Txn-Token is equal or less than the scope(s) identified in the `subject_token`.
 
 ## Unique Transaction Identifier
 A transaction token conveys user identity and authorization context across workloads in a call chain. The `txn` claim is a unique identifier that, when logged by the Transaction Token Service and workloads, enables discovery and auditing of successful and failed transactions. The `txn` value SHOULD be unique within the Trust Domain.
@@ -693,6 +599,22 @@ The Transaction Token Service may need to rotate signing keys. When doing so, it
 ## Transaction Tokens Are Not Authentication Credentials
 A workload MUST NOT use a transaction token to authenticate itself to another workload, service or the transaction token service. Transaction tokens represents information relevant to authorization decisions and are not workload identity credentials. Authentication between the workload and the transaction token service is described in {{Mutual-Authentication}}. The mechanisms used by workloads to authenticate to other workloads, services or system components is out of scope of this specification.
 
+## Replacing Transaction Tokens
+A service within a call chain may choose to replace the Txn-Token. This can typically happen if the service wants to change (add to, remove, or modify) the context of the current Txn-Token
+
+To get a replacement Txn-Token, a service will request a new Txn-Token from the Txn-Token Service and provide the current Txn-Token and other parameters in the request.
+
+### Txn-Token Service Responsibilities
+A Txn-Token Service MUST exercise caution when issugin replacement Txn-Tokens, since replacing Txn-Tokens with arbitrary values negates the primary purpose of having Txn-Tokens. When issuing replacement Txn-Tokens, a Txn-Token Service:
+
+* MAY enable modifications to asserted values that reduce the scope of permitted actions
+* MAY enable additional asserted values
+* MUST NOT enable modification to asserted values that expand the scope of permitted actions
+* MUST NOT modify `txn`, `sub`, and `aud` values of the Txn-Token in the request
+* MUST NOT remove any of the existing requesting workload identifiers from the `req_wl` field in the `rctx` claim of the Txn-Token
+* SHOULD NOT issue replacement Txn-token with lifetime exceeding the lifetime of the originally presented token
+* MUST append the workload identifier of the workload requesting the replacement to the `req_wl` value using the character `,` as the separator between individual workload identifiers.
+
 # Privacy Considerations {#Privacy}
 
 ## Obfuscation of Personal Information
@@ -798,6 +720,7 @@ The authors would like to thank the contributors and the OAuth working group mem
 * Removed the requirement to encode parameters in based64url format
 * Rename the `purpose` claim to `scope`
 * Enhanced the description of the `sub` claim addressing issue #225
+* Removed references to replacing transaction tokens, and added a note in the Security Considerations to clarify replacement concerns.
 
 ## Since Draft 05
 {:numbered="false"}
