OAuth Transaction Tokens Best Current Practice
draft-araut-oauth-transactiontokens-bcp-00
This document is an Internet-Draft (I-D).
Anyone may submit an I-D to the IETF.
This I-D is not endorsed by the IETF and has no formal standing in the
IETF standards process.
| Document | Type | Active Internet-Draft (individual) | |
|---|---|---|---|
| Author | Ashay Raut | ||
| Last updated | 2026-07-19 | ||
| Replaces | draft-oauth-transactiontokens-bcp | ||
| RFC stream | (None) | ||
| Intended RFC status | (None) | ||
| Formats | |||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-araut-oauth-transactiontokens-bcp-00
WG Working Group A. RAUT
Internet-Draft Amazon
Intended status: Informational 20 July 2026
Expires: 21 January 2027
OAuth Transaction Tokens Best Current Practice
draft-araut-oauth-transactiontokens-bcp-00
Abstract
This document provides best current practices for implementing and
deploying OAuth 2.0 Transaction Tokens as specified in draft-ietf-
oauth-transaction-tokens. Transaction Tokens (Txn-Tokens) enable
workloads in a trusted domain to preserve and propagate user identity
and authorization context across service boundaries during the
processing of external programmatic requests. This BCP addresses
practical deployment considerations including token service
architecture, size management, propagation patterns, validation
strategies, and operational monitoring that are essential for secure
and effective implementation in production environments.
About This Document
This note is to be removed before publishing as an RFC.
The latest revision of this draft can be found at
https://example.com/LATEST. Status information for this document may
be found at https://datatracker.ietf.org/doc/draft-araut-oauth-
transactiontokens-bcp/.
Source for this draft and an issue tracker can be found at
https://github.com/ashayraut/oauth-transactiontokens-best-current-
practice.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
RAUT Expires 21 January 2027 [Page 1]
Internet-Draft OAuth Transaction Tokens Best Current Pr July 2026
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on 21 January 2027.
Copyright Notice
Copyright (c) 2026 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components
extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Background . . . . . . . . . . . . . . . . . . . . . . . 3
1.2. Purpose of the BCP . . . . . . . . . . . . . . . . . . . 4
2. Conventions and Definitions . . . . . . . . . . . . . . . . . 4
3. Best Current Practices . . . . . . . . . . . . . . . . . . . 4
3.1. Context Selection . . . . . . . . . . . . . . . . . . . . 5
3.2. Token Size Management . . . . . . . . . . . . . . . . . . 5
3.2.1. Context Relocation . . . . . . . . . . . . . . . . . 5
3.3. Token Lifetime and Expiration . . . . . . . . . . . . . . 6
3.4. Schema Governance . . . . . . . . . . . . . . . . . . . . 7
3.4.1. Backward Compatibility . . . . . . . . . . . . . . . 7
3.5. Token Propagation . . . . . . . . . . . . . . . . . . . . 7
3.5.1. Propagation Denylist . . . . . . . . . . . . . . . . 8
3.5.2. Propagation Libraries . . . . . . . . . . . . . . . . 9
3.5.3. Multi-Language Propagation Considerations . . . . . . 9
3.5.4. Cross-Thread Propagation . . . . . . . . . . . . . . 10
3.5.5. Propagation Reliability . . . . . . . . . . . . . . . 11
3.5.6. Placeholder Token Design . . . . . . . . . . . . . . 12
3.5.7. Token Mix-up Prevention . . . . . . . . . . . . . . . 13
3.5.8. Token Leak Detection . . . . . . . . . . . . . . . . 13
3.5.9. Trust Boundary Handling . . . . . . . . . . . . . . . 14
3.5.10. Runtime Disable Switch . . . . . . . . . . . . . . . 15
3.5.11. Cache Considerations . . . . . . . . . . . . . . . . 16
3.6. Token Validation . . . . . . . . . . . . . . . . . . . . 16
3.6.1. Key and Schema Caching . . . . . . . . . . . . . . . 16
RAUT Expires 21 January 2027 [Page 2]
Internet-Draft OAuth Transaction Tokens Best Current Pr July 2026
3.6.2. Error Handling . . . . . . . . . . . . . . . . . . . 18
3.6.3. Fallback Policies . . . . . . . . . . . . . . . . . . 18
3.6.4. Verification Strategy Modes . . . . . . . . . . . . . 18
3.7. Telemetry and Monitoring . . . . . . . . . . . . . . . . 20
3.7.1. Telemetry Aggregation . . . . . . . . . . . . . . . . 20
3.7.2. Key Metrics . . . . . . . . . . . . . . . . . . . . . 20
3.7.3. Token Validation Audit Trail . . . . . . . . . . . . 20
3.8. Key Management . . . . . . . . . . . . . . . . . . . . . 21
3.9. Batch Processing Pattern . . . . . . . . . . . . . . . . 21
3.9.1. Initiation (Pausing the Transaction) . . . . . . . . 22
3.9.2. Rehydration (Resuming the Transaction) . . . . . . . 22
3.9.3. Async Context Preservation . . . . . . . . . . . . . 22
3.9.4. Message Transport . . . . . . . . . . . . . . . . . . 23
4. Security Considerations . . . . . . . . . . . . . . . . . . . 23
4.1. Token Mix-up Prevention . . . . . . . . . . . . . . . . . 23
4.2. Trust Boundary Controls . . . . . . . . . . . . . . . . . 23
4.3. Cache Security . . . . . . . . . . . . . . . . . . . . . 23
4.4. Fallback Mechanisms . . . . . . . . . . . . . . . . . . . 24
4.5. Token Lifetime . . . . . . . . . . . . . . . . . . . . . 24
4.6. External Propagation . . . . . . . . . . . . . . . . . . 24
4.7. Batch Processing Security Consideration . . . . . . . . . 24
4.7.1. Token Constraining . . . . . . . . . . . . . . . . . 24
4.7.2. Data Mutability and Consent . . . . . . . . . . . . . 24
4.7.3. Infinite Exchange Prevention . . . . . . . . . . . . 24
4.8. Token Format Identification . . . . . . . . . . . . . . . 25
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25
6. References . . . . . . . . . . . . . . . . . . . . . . . . . 25
6.1. Informative References . . . . . . . . . . . . . . . . . 25
7. Normative References . . . . . . . . . . . . . . . . . . . . 25
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 25
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 25
1. Introduction
1.1. Background
Modern distributed systems built on microservice architectures face a
fundamental challenge: maintaining security context as requests
traverse multiple service boundaries. When an external actor
initiates an API request, the user identity and authorization context
must be preserved and made available to all downstream internal
microservices involved in processing that request. Without a
standardized mechanism, organizations resort to ad-hoc solutions that
introduce security vulnerabilities, operational complexity, and
interoperability challenges.
RAUT Expires 21 January 2027 [Page 3]
Internet-Draft OAuth Transaction Tokens Best Current Pr July 2026
The OAuth 2.0 Transaction Tokens specification (draft-ietf-oauth-
transaction-tokens) addresses this challenge by defining a token
format and exchange protocol that enables secure context propagation
across internal microservices within trusted domains. However, the
specification focuses on protocol mechanics rather than deployment
practices. Real-world implementations face additional challenges
including latency constraints, token size limitations, schema
evolution, propagation reliability, and operational monitoring.
1.2. Purpose of the BCP
This Best Current Practice document provides implementers with
guidance derived from production deployments of Txn-Token systems.
It addresses practical considerations that fall outside the scope of
the protocol specification but are critical for successful
deployment. The recommendations in this document are based on
operational experience with large-scale microservice environments
where hundreds of internal microservices must coordinate security
context propagation across complex call chains.
This BCP is intended for: - Organizations implementing Transaction
Token Services - internal microservice developers integrating Txn-
Token support - Security architects designing authorization systems -
Operations teams monitoring token propagation
2. Conventions and Definitions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119. This
document uses terminology from draft-ietf-oauth-transaction-tokens
including "Transaction Token" (Txn-Token), "Transaction Token
Service", "trusted domain", and "authorization context".
3. Best Current Practices
## Transaction Token Service Implementation ### Service Architecture
Organizations SHOULD setup Transaction Token Service (TTS) which
hosts functionality to issue token, replace token and other Txn-Token
related functionality. Organizations SHOULD prefer architectures
where the authorization service that authenticates and authorizes
external actors, invokes the TTS for getting Transaction Token as
RAUT Expires 21 January 2027 [Page 4]
Internet-Draft OAuth Transaction Tokens Best Current Pr July 2026
part of authentication and authorization requests and pass Txn-token
as well with it. This way, it avoids an explicit calls from external
endpoint to TTS and lesser code changes in external services.
Additionally, all internal microservices that want to replace tokens
SHOULD connect directly to TTS. This architecture strikes balance
between the options to either have authorization service host all TTS
functionality or external services needing to connect TTS.
3.1. Context Selection
Transaction Token Services MUST include all mandatory claims defined
in draft-ietf-oauth-transaction-tokens. However, services SHOULD NOT
include all optional contexts by default. Optional contexts such as
transaction context (tctx) or custom claims MUST be added only when
explicitly requested.
Organizations SHOULD provide client libraries that offer interfaces
for requesting Txn-Tokens with specific optional contexts. This
approach prevents token bloat while ensuring that services can obtain
the context they require. When an optional context cannot be added
due to parsing errors, format violations, or unavailability, the
Transaction Token Service MUST NOT fail the token issuance. Instead,
it SHOULD issue the token without that specific context and MAY log
the condition for operational monitoring.
3.2. Token Size Management
### Size Limits Transaction Token Services MUST NOT issue tokens
larger than 4KB. While HTTP specifications do not mandate maximum
header sizes, common web server implementations impose limits to
prevent Denial of Service attacks. Apache defaults to 8KB maximum
header size, but organizations must account for other headers in the
same request. A 4KB limit for Txn-Tokens provides reasonable
headroom while preventing operational issues.
Organizations SHOULD implement monitoring on token size to detect
trends toward the limit. Services that consistently approach size
limits indicate either excessive context inclusion or the need for
context relocation strategies.
3.2.1. Context Relocation
When authorization context exceeds 4KB, Transaction Token Services
SHOULD implement a relocation endpoint. The service stores oversized
contexts in a separate data store using the Txn-Token identifier as
the primary key. The Txn-Token itself contains only a reference to
the relocated context.
RAUT Expires 21 January 2027 [Page 5]
Internet-Draft OAuth Transaction Tokens Best Current Pr July 2026
Client libraries for token validation SHOULD transparently handle
context relocation. When an internal microservice requests a context
that has been relocated, the library fetches it from the relocation
endpoint. This pattern mirrors Policy Information Points in
Attribute-Based Access Control (ABAC) systems where additional
attributes are retrieved at runtime.
Context relocation introduces additional latency and failure modes.
Organizations SHOULD treat relocation as an exception rather than the
normal case. Monitoring SHOULD track relocation frequency to
identify services that consistently require excessive context.
3.3. Token Lifetime and Expiration
Transaction tokens SHOULD have a time-to-live of less than 5 minutes.
Organizations SHOULD determine appropriate lifetimes by working
backward from latency Service Level Agreements (SLAs) defined for
external endpoints.
Short token lifetimes reduce the window for token compromise and
limit the impact of token mix-up scenarios. However, lifetimes must
accommodate the longest expected call chains in the SOA.
Organizations SHOULD measure actual request processing times and set
token lifetimes to exceed the 99th percentile by a reasonable margin.
While the TTS MAY support per-use-case token lifetimes, organizations
SHOULD prefer a single uniform lifetime across all use cases. Per-
use-case lifetimes add configuration complexity and make it harder to
reason about expiration behavior across call chains. A uniform
lifetime simplifies operations and enables centralized tracking of
expired tokens.
When tokens expire during request processing, services MUST NOT
automatically request new tokens. Expired tokens indicate either
excessively long call chains or performance problems that require
investigation. Services SHOULD fail requests with expired tokens and
emit telemetry for operational monitoring. Organizations SHOULD
track token expiration centrally to identify which services or call
chains consistently produce expired tokens and why — enabling
targeted investigation rather than blanket lifetime increases.
RAUT Expires 21 January 2027 [Page 6]
Internet-Draft OAuth Transaction Tokens Best Current Pr July 2026
3.4. Schema Governance
### Context Visibility Organizations MUST govern the contexts added
to Txn-Tokens. Once a context appears in a Txn-Token, it becomes
visible to all services in the call chain. Services may develop
dependencies on these contexts in ways not anticipated by the context
provider. This phenomenon follows Hyrum's Law: with sufficient
consumers, all observable behaviors of a system will be depended upon
by somebody.
Before adding a new context to Txn-Tokens, organizations MUST
consider the implications of making that context universally visible.
If a context represents an identifier or concept known only to
services early in the call chain, adding it to the Txn-Token exposes
it to all downstream services. Those services may develop business
logic dependencies on the context, not just security dependencies.
When the format or semantics of a widely-visible context must change,
the organization faces a painful migration process. All services
that depend on the context must be identified, updated, and deployed.
Organizations SHOULD prefer adding new contexts with different names
rather than changing existing contexts when semantic changes are
required.
3.4.1. Backward Compatibility
Organizations MUST implement backward compatibility tests for Txn-
Token contexts. Automated tests SHOULD verify that changes to
context format or structure do not break existing consumers. These
tests SHOULD run as part of the continuous integration pipeline for
the Transaction Token Service.
Backward compatibility testing becomes increasingly important as the
number of services consuming Txn-Tokens grows. Without automated
verification, format changes risk cascading failures across the SOA.
3.5. Token Propagation
### Propagation Control Organizations MUST prevent Txn-Tokens from
propagating outside the trusted domain. While tokens contain
encrypted sensitive data, organizations SHOULD implement explicit
controls to block external propagation. Propagation libraries MUST
detect when an internal microservice attempts to include a Txn-Token
in a request to an external endpoint and MUST remove the token from
that request.
RAUT Expires 21 January 2027 [Page 7]
Internet-Draft OAuth Transaction Tokens Best Current Pr July 2026
This defense-in-depth approach protects against misconfiguration and
implementation errors. Even if token encryption remains secure,
preventing external propagation eliminates entire classes of
potential vulnerabilities.
3.5.1. Propagation Denylist
In addition to preventing external propagation, organizations SHOULD
maintain a denylist of internal services that MUST NOT participate in
token propagation. This addresses scenarios where specific services
within the trusted domain should not receive or forward tokens due to
architectural constraints, security requirements, or known
incompatibilities.
3.5.1.1. Use Cases for Denylisting
* Services undergoing decommissioning that cannot be updated to
handle tokens correctly
* Internal services that proxy to external endpoints (defense in
depth)
* Services with known token handling bugs that cannot be immediately
fixed
* Shared infrastructure services where token propagation creates
unintended authorization coupling
3.5.1.2. Implementation
The denylist SHOULD be: - Evaluated before any token propagation
logic executes - Configured at service startup (not changeable per-
request) - Checked case-insensitively against the service's canonical
identifier - Applied as a fail-safe — denylisted services return no-
op results for all propagation operations
When a service is on the denylist, propagation libraries MUST: - Not
extract tokens from incoming requests - Not attach tokens to outgoing
requests - Not generate placeholder tokens - Log that propagation was
skipped due to denylist membership
RAUT Expires 21 January 2027 [Page 8]
Internet-Draft OAuth Transaction Tokens Best Current Pr July 2026
3.5.2. Propagation Libraries
Organizations SHOULD provide standardized propagation libraries that
handle token lifecycle within an internal microservice workload
processing. These libraries MUST extract the Txn-Token from the
incoming HTTP header, store it in request-scoped memory, add the
token to outgoing request headers, and clear it from memory when
request processing completes.
Standardized libraries provide several benefits. First, they enforce
propagation controls including external blocking to avoid the token
flowing outside your trust boundary. Second, they can be used to
consistently emit telemetry about token initiation, propagation, and
validation. Third, they provide a centralized point for implementing
fallback behaviors when tokens are missing.
3.5.3. Multi-Language Propagation Considerations
Different programming languages have fundamentally different
concurrency models that affect propagation library design.
Organizations supporting polyglot architectures MUST account for
these differences.
3.5.3.1. Language-Specific Token Storage
+==========+=====================+===============================+
| Language | Recommended Storage | Cross-Async Behavior |
| | Mechanism | |
+==========+=====================+===============================+
| Java | ThreadLocal + | Requires explicit StateCaptor |
| | framework-specific | or framework agent for cross- |
| | transaction context | thread propagation |
+----------+---------------------+-------------------------------+
| Python | ContextVar | Natively propagates across |
| | | async/await boundaries — no |
| | | explicit cross-thread logic |
| | | needed |
+----------+---------------------+-------------------------------+
| NodeJS | AsyncLocalStorage | Natively propagates across |
| | | async callbacks and promises |
| | | — no explicit cross-thread |
| | | logic needed |
+----------+---------------------+-------------------------------+
| Go | context.Context | Propagates naturally via |
| | | context passing — no thread- |
| | | local issues |
+----------+---------------------+-------------------------------+
RAUT Expires 21 January 2027 [Page 9]
Internet-Draft OAuth Transaction Tokens Best Current Pr July 2026
Table 1
3.5.3.2. Feature Parity Expectations
Not all languages need identical feature sets. Organizations SHOULD
prioritize:
+=============================+=============================+
| Capability | Priority |
+=============================+=============================+
| Token storage + propagation | *Required* in all languages |
+-----------------------------+-----------------------------+
| Domain allowlist | *Required* in all languages |
+-----------------------------+-----------------------------+
| Disable switch | *Required* in all languages |
+-----------------------------+-----------------------------+
| Token validation | High priority (Java first, |
| | others as needed) |
+-----------------------------+-----------------------------+
| Token issuance | Server-side only — language |
| | of TTS |
+-----------------------------+-----------------------------+
| Async preservation | Based on async workload |
| | patterns per language |
+-----------------------------+-----------------------------+
Table 2
3.5.3.3. Telemetry Consistency
Despite different implementations, all language SDKs MUST emit
semantically equivalent metrics with consistent naming conventions.
This enables cross-language monitoring dashboards and comparable
adoption tracking.
3.5.4. Cross-Thread Propagation
Modern services use thread pools, async executors, and non-blocking
frameworks where request processing spans multiple threads. Token
storage based on thread-local variables does NOT automatically
propagate to child threads. Organizations MUST address this.
RAUT Expires 21 January 2027 [Page 10]
Internet-Draft OAuth Transaction Tokens Best Current Pr July 2026
3.5.4.1. The Problem
When a service spawns child threads (via thread pools, async
executors, or reactive frameworks), the token in the parent thread's
storage is not automatically inherited. Without explicit
propagation, child threads have no token — breaking the
authentication chain for any downstream calls they make.
3.5.4.2. Solution: Capture-Restore Pattern
Propagation libraries SHOULD implement a state capture pattern:
Parent Thread Child Thread | | +-- Capture: snapshot current
token | | | | +-- Restore: set captured token | | into child's
storage | | | +-- Execute: child runs with | | propagated token | | |
+-- Cleanup: clear child's storage | | (prevent leak to next task)
3.5.4.3. Key Behaviors
* The captured token is a *snapshot* at capture time — subsequent
changes on the parent thread are NOT reflected in the child
* Null/empty tokens SHOULD be propagated gracefully (no error)
* Cleanup MUST always run regardless of success or failure (prevents
leaks on reused pool threads)
* The capture mechanism SHOULD be auto-discovered (e.g., via service
loader or framework hooks) — no explicit wiring by service
developers
3.5.4.4. Fire-and-Forget Pattern
For fire-and-forget async patterns (where the parent thread completes
and responds before the child finishes): - Parent thread clearing its
storage at request end MUST NOT affect the child thread's copy - The
token storage implementation MUST support reference semantics where
the child retains access even after the parent's cleanup - This is a
critical design consideration — naive "clear all" implementations
will break fire-and-forget
3.5.5. Propagation Reliability
Organizations SHOULD monitor propagation success rates across the
SOA. Unless propagation success reaches 100% for a given call chain,
services cannot reliably enforce authorization policies based on Txn-
Token contents. Services MUST implement reasonable fallback
behaviors when tokens are absent.
RAUT Expires 21 January 2027 [Page 11]
Internet-Draft OAuth Transaction Tokens Best Current Pr July 2026
Propagation libraries MAY implement automatic token initiation when
an incoming request lacks a Txn-Token. The library requests a
placeholder token from the Transaction Token Service indicating that
no context was received at the current service. This placeholder
enables downstream services to identify where propagation broke in
the call chain, facilitating operational debugging.
3.5.6. Placeholder Token Design
Placeholder tokens serve as diagnostic markers that identify WHERE
propagation broke in a call chain. They are NOT authorization tokens
and MUST NOT be used for access decisions.
3.5.6.1. Placeholder Token Contents
Placeholder tokens SHOULD contain: - issuerServiceName — the service
that generated the placeholder (where the break was detected) -
clientName — the upstream caller that failed to propagate a real
token - issuedAt — timestamp of generation - reasonCode — why the
real token is missing
3.5.6.2. Reason Codes
+========================+======================================+
| Code | Meaning |
+========================+======================================+
| TOKEN_NOT_PRESENT | No token in incoming request headers |
+------------------------+--------------------------------------+
| TOKEN_GENERATION_ERROR | Token generation/issuance failed |
+------------------------+--------------------------------------+
| UNSUPPORTED_REGION | Service is in a region that doesn't |
| | support Txn-Tokens |
+------------------------+--------------------------------------+
| UNKNOWN | Reason could not be determined |
+------------------------+--------------------------------------+
Table 3
3.5.6.3. Placeholder Token Properties
* Placeholder tokens MUST NOT be cryptographically signed — they
have no security value
* Validators encountering placeholder tokens SHOULD emit per-issuer
metrics to identify which services are generating them
RAUT Expires 21 January 2027 [Page 12]
Internet-Draft OAuth Transaction Tokens Best Current Pr July 2026
* APIs that extract details from placeholder tokens SHOULD be
explicitly named to signal unreliability (e.g.,
getUnsafePlaceholderDetails())
* Placeholder tokens SHOULD be distinguishable from real tokens via
a format version identifier (O(1) check, no full decode needed)
3.5.6.4. Auto-Generation at Potential Entry Points
Services that might be the first in a call chain (potential
initiators) SHOULD automatically generate a placeholder token if no
token arrives. This distinguishes "I am the entry point and no token
was issued" from "someone upstream broke propagation."
3.5.7. Token Mix-up Prevention
Token mix-up represents the most severe propagation risk. Mix-up
occurs when a token intended for one request is incorrectly attached
to a different request. If token T1 is meant for request R1 and
token T2 for request R2, but T2 is sent with R1 due to a propagation
bug, actors may access data they are not authorized to see.
Token mix-up scenarios are difficult to detect because they may not
cause obvious failures. The request succeeds but with incorrect
authorization context. Organizations MUST implement request-scoped
token storage in propagation libraries to prevent mix-up. Tokens
MUST be associated with specific request contexts and MUST NOT be
stored in shared or global state.
Organizations SHOULD implement testing strategies that deliberately
attempt to cause token mix-up under concurrent load. These tests
verify that propagation libraries correctly isolate tokens across
concurrent requests.
3.5.8. Token Leak Detection
Beyond preventing mix-up during concurrent requests, organizations
MUST implement leak detection at request boundaries. A "leak" occurs
when a token from a previous request remains in storage when a new,
unrelated request arrives — meaning one request's credentials could
bleed into another's authorization context.
3.5.8.1. Detection Mechanism
At the start of every incoming request, propagation libraries SHOULD
check whether a leftover Txn-Token is already present in request-
scoped storage before the new request's token is stored:
RAUT Expires 21 January 2027 [Page 13]
Internet-Draft OAuth Transaction Tokens Best Current Pr July 2026
New request arrives -> Check: is a token already in storage? -> YES
-> Leak detected! Log safe identifiers + emit metric -> NO -> Clean
state, proceed normally
3.5.8.2. Detection vs Prevention
Leak detection is distinct from leak prevention: - *Detection*:
Identifies that a leak occurred (observability) - *Prevention*:
Mechanisms that ensure cleanup happens (see request lifecycle
cleanup)
Both are required. Detection catches cases where prevention
mechanisms fail.
3.5.8.3. Metrics
Organizations SHOULD emit a binary metric at request start: - Value 0
= clean state (no leftover token) - Value 1 = leak detected (token
from previous request still present)
Detection SHOULD log safe, non-sensitive identifiers of both the
leftover token and the incoming token for debugging — never raw token
values.
3.5.8.4. Remediation
Upon detecting a leak, propagation libraries SHOULD override the
leaked token with the correct incoming token. Detection is
observability-only — it SHOULD NOT block or fail the request. The
incoming request's token takes precedence.
3.5.9. Trust Boundary Handling
When requests cross trust boundaries within the organization,
propagation libraries MUST either block token propagation or replace
token contents with appropriately scoped contexts. Organizations
SHOULD define trust boundaries explicitly and configure propagation
libraries with boundary detection logic.
At trust boundaries, services MAY request new Txn-Tokens from the
Transaction Token Service with contexts appropriate for the target
trust domain. This approach maintains context propagation while
respecting security boundaries.
RAUT Expires 21 January 2027 [Page 14]
Internet-Draft OAuth Transaction Tokens Best Current Pr July 2026
3.5.10. Runtime Disable Switch
Organizations MUST provide a runtime kill switch that can disable
token propagation without requiring service restarts. In production
incidents where token propagation is contributing to failures,
operators need immediate relief.
3.5.10.1. Requirements
* Each propagation solution (e.g., per framework integration) SHOULD
have an independent disable switch
* Disable switches SHOULD be configurable via JVM system properties,
environment variables, or dynamic configuration
* Changes SHOULD take effect within a bounded interval (e.g., 180
seconds maximum polling interval)
* All solutions MUST default to ENABLED on initialization
* Disabling propagation SHOULD NOT cause request failures — requests
proceed without tokens
3.5.10.2. Operational Behavior When Disabled
When the disable switch is active: - Incoming token extraction
returns empty (tokens in headers are ignored) - Outgoing request
header injection is skipped - Token storage operations become no-ops
- Telemetry SHOULD still emit metrics indicating the disabled state
3.5.10.3. Safety Constraints
* Disable switches SHOULD require explicit opt-in registration
before polling takes effect
* A disabled propagation path MUST NOT generate errors or exceptions
— it simply becomes invisible
* Organizations SHOULD alert when a disable switch has been active
for extended periods (indicating a forgotten workaround)
RAUT Expires 21 January 2027 [Page 15]
Internet-Draft OAuth Transaction Tokens Best Current Pr July 2026
3.5.11. Cache Considerations
The introduction of Txn-token provides more information now to the
entire microservice architecture graph. There are Services in the
graph that cache data to avoid calling dependent services multiple
times. Now, they SHOULD consider Txn-Token contexts to be included
in the cache keys. If not included, there is a risk that incorrect
data is vended out or cache hit is impacted because the dependent
services might be using the Txn-Token contexts for computing the
results which might get cached.
Organizations SHOULD provide guidance to workload developers on cache
key construction when Txn-Tokens are involved. Cache invalidation
strategies MUST account for context changes that affect cached data.
3.6. Token Validation
### Validation Libraries Organizations SHOULD provide standardized
validation libraries that handle signature verification, decryption,
and token parsing. These libraries SHOULD synchronize cryptographic
keys in the background, ensuring that services always have current
keys for verification and decryption.
Validation libraries SHOULD decode Txn-Tokens into strongly-typed
objects appropriate for the implementation language. This approach
prevents parsing errors and provides compile-time verification of
context access patterns.
3.6.1. Key and Schema Caching
Validation libraries MUST cache cryptographic keys and token schemas
locally. Remote lookups on every validation request introduce
unacceptable latency.
3.6.1.1. Key Caching Requirements
* Keys MUST be pre-fetched into local cache before validation
requests arrive
* Background refresh SHOULD run on a daemon thread at a fixed
interval (e.g., every 1 hour) with jitter (+/-10%) to avoid
thundering herd
* Cache miss for a required key SHOULD NOT trigger a synchronous
remote fetch — the token validation fails fast with a clear error
code
RAUT Expires 21 January 2027 [Page 16]
Internet-Draft OAuth Transaction Tokens Best Current Pr July 2026
* Multiple concurrent keys MUST be supported to enable zero-downtime
rotation (old key and new key both valid during transition)
3.6.1.2. Schema Caching Requirements
* Schemas define how token contexts are decoded. They MUST be
cached locally.
* Background refresh interval SHOULD be longer than key refresh
(e.g., every 6 hours) since schemas change less frequently
* A fresh schema parser instance SHOULD be used per deserialization
to avoid cross-contamination between independently evolving
schemas
* Schema not in cache at validation time -> fail with a specific
error code (e.g., MISSING_SCHEMA) — do NOT block waiting for a
fetch
3.6.1.3. Key Refresh Resilience
* Background refresh failures MUST be caught and logged — they MUST
NOT terminate the refresh scheduler
* If the key management service is down, the last successfully
fetched keys remain valid until they expire
* Organizations SHOULD alert on consecutive refresh failures
exceeding a threshold
3.6.1.4. Environment-Specific Strategies
+=======================+=========================================+
| Environment | Strategy |
+=======================+=========================================+
| Long-running services | Background daemon thread with scheduled |
| | refresh |
+-----------------------+-----------------------------------------+
| Serverless / Lambda | Eager fetch on cold start; no |
| | background thread (short-lived process) |
+-----------------------+-----------------------------------------+
| Edge / resource- | Configurable refresh intervals with |
| constrained | larger TTLs |
+-----------------------+-----------------------------------------+
Table 4
RAUT Expires 21 January 2027 [Page 17]
Internet-Draft OAuth Transaction Tokens Best Current Pr July 2026
3.6.2. Error Handling
Validation libraries SHOULD emit standardized error codes for common
failure conditions including expired tokens, malformed tokens, and
signature verification failures. These error codes enable consistent
operational monitoring across the SOA.
3.6.3. Fallback Policies
Services SHOULD NOT automatically fail requests when Txn-Tokens are
missing or invalid. Organizations MUST define fallback policies that
balance security with user experience. Fallback policies MAY include
serving redacted data, limiting functionality, or requesting step-up
authentication.
The appropriate fallback depends on the sensitivity of the requested
operation. Services accessing highly sensitive data MAY require
valid Txn-Tokens and fail requests when tokens are absent. Services
providing less sensitive functionality SHOULD implement graceful
degradation.
3.6.4. Verification Strategy Modes
Organizations deploying Txn-Token validation MUST support at least
three progressive enforcement modes that can be configured per-
service and per-request:
RAUT Expires 21 January 2027 [Page 18]
Internet-Draft OAuth Transaction Tokens Best Current Pr July 2026
+==========================+=======================+===============+
| Mode | Behavior | Use Case |
+==========================+=======================+===============+
| SHADOW_MODE | Token is decoded and | Initial |
| | validated but | rollout, |
| | failures are only | testing, |
| | logged — never | measuring |
| | enforced. Requests | impact before |
| | always proceed. | enforcement |
+--------------------------+-----------------------+---------------+
| TOKEN_PRESENCE_MODE | Token must be present | Intermediate |
| | in the request but no | enforcement — |
| | cryptographic | ensures |
| | verification is | propagation |
| | performed. Absence | works before |
| | causes failure. | trusting |
| | | content |
+--------------------------+-----------------------+---------------+
| STRICT_VERIFICATION_MODE | Full cryptographic | Production |
| | verification. | enforcement |
| | Invalid or missing | after |
| | tokens cause request | confidence is |
| | rejection. | established |
+--------------------------+-----------------------+---------------+
Table 5
Organizations SHOULD default to SHADOW_MODE when first deploying
validation and progressively tighten enforcement. The default mode
SHOULD be configurable at both the service level and per-request
level (e.g., based on API sensitivity or client identity).
Validation libraries SHOULD emit distinct metrics for each mode so
organizations can track: - How many requests WOULD fail under
stricter enforcement - Per-client and per-error-code failure rates in
shadow mode - Readiness percentage before promoting to stricter
enforcement
Error logs during shadow mode SHOULD be sampled (e.g., 50%) to
prevent log flooding while still providing visibility into issues.
Organizations MUST document and communicate enforcement promotion
timelines to downstream service teams. Surprise enforcement changes
cause outages.
RAUT Expires 21 January 2027 [Page 19]
Internet-Draft OAuth Transaction Tokens Best Current Pr July 2026
3.7. Telemetry and Monitoring
### Adoption Monitoring Transaction token adoption in large SOA
environments takes time. Organizations SHOULD implement
comprehensive telemetry to monitor adoption progress, propagation
reliability, and validation patterns.
When organizations provide standardized libraries for token
initiation, propagation, and validation, telemetry logic SHOULD be
embedded in those libraries. This approach ensures consistent
telemetry across all services without requiring individual workload
implementations.
3.7.1. Telemetry Aggregation
Services SHOULD aggregate telemetry locally before transmitting to
centralized monitoring systems. Local aggregation reduces network
overhead and enables higher-frequency sampling without overwhelming
monitoring infrastructure.
Centralized monitoring systems SHOULD store telemetry in data
warehouses that support analytical queries. Organizations SHOULD
implement automated monitors that alert on significant changes in
propagation rates, validation failures, or token expiration rates.
3.7.2. Key Metrics
Organizations SHOULD monitor the following key metrics: - Token
initiation rate by service - Propagation success rate by call chain -
Token expiration rate during request processing - Validation failure
rate by error type - Token size distribution - Context relocation
frequency
These metrics provide visibility into Txn-Token health across the SOA
and enable rapid identification of deployment issues.
3.7.3. Token Validation Audit Trail
Beyond operational telemetry, organizations MUST implement token
validation audit logging that creates an audit trail for every token
validation attempt.
RAUT Expires 21 January 2027 [Page 20]
Internet-Draft OAuth Transaction Tokens Best Current Pr July 2026
3.7.3.1. When to Log
A security event MUST be generated after *every* validation attempt —
regardless of success or failure. This includes: - Successful token
validation (identity confirmed) - Failed validation (expired,
malformed, bad signature) - Placeholder token encountered - Token
absent when required
3.7.3.2. What to Log
Security event entries SHOULD include: - *Initiator identity* — the
application/service that originally issued the token - *Subject
identity* — the authenticated entity (end user, system) the token
represents - *Requester line of business* — organizational context -
*Customer/entity identifier* — if present in the token - *Token type*
— real token vs placeholder vs auto-generated - *Validation status* —
success, failure code, or skip reason - *Timestamp and request
identifier*
For placeholder tokens, log the issuer service name and upstream
client name to trace propagation breaks.
3.7.3.3. Failure Resilience
Security event logging failures MUST NOT interrupt request
processing. If the logging system is unavailable: - Emit a metric
counting missed security events - Sample error logs (e.g., 50%) to
avoid flooding - Never propagate the logging failure to callers
3.8. Key Management
Organizations MUST implement secure key management practices for Txn-
Token cryptographic operations. Key management SHOULD follow the
guidelines in RFC 4107 "Guidelines for Cryptographic Key Management".
Transaction Token Services MUST support key rotation without service
disruption. Validation libraries MUST support multiple concurrent
keys to enable zero-downtime rotation. Organizations SHOULD automate
key rotation on a regular schedule.
3.9. Batch Processing Pattern
OAuth Transaction Tokens are designed to propagate security context
through a call chain within a trust domain. To maintain a high
security posture without the overhead of a global revocation
infrastructure, these tokens are short-lived (typically minutes). In
many modern architectures, a transaction may be asynchronous. For
example, a request may be placed on a message queue (e.g., Kafka,
RAUT Expires 21 January 2027 [Page 21]
Internet-Draft OAuth Transaction Tokens Best Current Pr July 2026
RabbitMQ) and processed by a worker service hours or days later. By
the time the worker resumes the transaction, the original Transaction
Token has expired.
Batch Token (Voucher): A long-lived, opaque, or encrypted token
representing the transaction context during a period of rest.
Initiator: The internal microservice that receives a Transaction
Token and requests a Batch Token before an asynchronous pause.
Rehydrator: The internal microservice that takes a Batch Token and
exchanges it for a fresh, short-lived Transaction Token to resume
processing.
3.9.1. Initiation (Pausing the Transaction)
When a internal microservice determines that a transaction will
exceed the TTL of the current Transaction Token (TraT), it SHOULD
request a Batch Token from the Transaction Token Service (TTS). The
request to the TTS SHOULD include: * The current valid TraT. * The
intended "use case ID" or "namespace" to constrain the token.
The TTS returns a Batch Token with a TTL suitable for the
asynchronous delay (e.g., 24 hours to 7 days).
3.9.2. Rehydration (Resuming the Transaction)
When a worker service (the Rehydrator) picks up the task, it MUST NOT
use the Batch Token directly to call downstream services. Instead,
it MUST exchange the Batch Token at the TTS for a fresh TraT. The
TTS SHALL: 1. Verify the Batch Token's signature and expiration. 2.
Validate that the Rehydrator is authorized for the specific "use case
ID" or "namespace" embedded in the Batch Token. 3. Issue a new,
short-lived TraT containing the original claims (e.g., subject,
original requester IP).
3.9.3. Async Context Preservation
When preserving token contexts across asynchronous boundaries,
organizations MUST use server-side signed preservation via the TTS.
The TTS issues an ECDSA-signed preservation context that provides
tamper detection and centralized audit. Client-side unsigned
preservation MUST NOT be used — all async context preservation
requires cryptographic integrity guarantees.
RAUT Expires 21 January 2027 [Page 22]
Internet-Draft OAuth Transaction Tokens Best Current Pr July 2026
3.9.4. Message Transport
For message-based async (SQS, SNS, Kafka), preserved context SHOULD
be transported as a message attribute rather than embedded in the
message body: - Attribute name SHOULD be standardized (e.g., x-
transaction-token-preservation-context) - Data type: String
(Base64-encoded binary) - Idempotency: if the attribute already
exists on the message, preserve the existing value (no overwrite) -
Message attribute limits (e.g., SQS max 10 attributes) MUST be
respected — if the limit is reached, the failure SHOULD be logged but
the original message MUST still be sent
3.9.4.1. Batch Token Scoping Enhancements
Batch Tokens (Vouchers) SHOULD include: - A maximum chain depth
counter to prevent infinite rehydration loops - A total transaction
lifetime that cannot be extended beyond a hard maximum regardless of
rehydration count - Namespace/use-case scoping so that a batch token
obtained for one async workflow cannot be rehydrated in a different
workflow context
4. Security Considerations
4.1. Token Mix-up Prevention
Token mix-up represents a critical security risk. Organizations MUST
implement request-scoped token storage and MUST test for mix-up
scenarios under concurrent load. Token mix-up can result in
unauthorized data access without obvious system failures, making it
particularly dangerous.
4.2. Trust Boundary Controls
Organizations MUST define trust boundaries explicitly and MUST
implement controls that prevent inappropriate token propagation
across those boundaries. Failure to control propagation at trust
boundaries can expose sensitive contexts to unauthorized services.
4.3. Cache Security
Services that cache data based on Txn-Token contexts face security
risks if cache keys do not incorporate all relevant contexts.
Organizations MUST provide guidance on secure cache key construction
and MUST audit caching services for correct context handling.
RAUT Expires 21 January 2027 [Page 23]
Internet-Draft OAuth Transaction Tokens Best Current Pr July 2026
4.4. Fallback Mechanisms
While fallback mechanisms improve availability, they can introduce
security vulnerabilities if not carefully designed. Organizations
MUST ensure that fallback policies do not inadvertently grant
excessive access when Txn-Tokens are absent. Fallback policies
SHOULD be explicitly documented and reviewed by security teams.
4.5. Token Lifetime
Short token lifetimes reduce the window for token compromise but may
cause operational issues if set too aggressively. Organizations MUST
balance security considerations with operational requirements when
setting token lifetimes.
4.6. External Propagation
Preventing Txn-Tokens from leaving the trusted domain is critical.
Organizations MUST implement multiple layers of defense including
library-level controls, network-level filtering, and monitoring for
external propagation attempts.
4.7. Batch Processing Security Consideration
4.7.1. Token Constraining
Batch Tokens MUST be sender-constrained or scoped to specific
namespaces. This prevents a compromised service from "stealing" a
Batch Token from a queue and successfully minting a Transaction Token
for an unrelated flow.
4.7.2. Data Mutability and Consent
Asynchronous delays increase the risk that the underlying
authorization context has changed (e.g., a user has revoked consent).
The TTS SHOULD perform a "freshness check" during rehydration for
claims marked as mutable or sensitive.
4.7.3. Infinite Exchange Prevention
To prevent a transaction from living indefinitely through repeated
rehydrations, the TTS SHOULD implement a maximum chain depth or total
transaction lifetime counter within the token metadata.
RAUT Expires 21 January 2027 [Page 24]
Internet-Draft OAuth Transaction Tokens Best Current Pr July 2026
4.8. Token Format Identification
Validation libraries MUST be able to quickly identify token type
(real token vs placeholder vs handle) without performing full
decryption. This enables: - Fast-path rejection of placeholder
tokens in strict enforcement mode - Per-type metrics without
expensive decode operations - Efficient routing to format-specific
decoders
5. IANA Considerations
This document has no IANA actions.
6. References
## Normative References RFC2119
(https://datatracker.ietf.org/doc/html/rfc2119) Bradner, S., "Key
words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC
2119, DOI 10.17487/RFC2119, March 1997.
TXNTOKENS (https://www.ietf.org/archive/id/draft-ietf-oauth-
transaction-tokens-06.html) Tulshibagwale, A., Hardt, D., and G.
Fletcher, "OAuth 2.0 Transaction Tokens", draft-ietf-oauth-
transaction-tokens-06 (work in progress).
6.1. Informative References
RFC4107 (https://datatracker.ietf.org/doc/html/rfc4107) Bellovin, S.
and R. Housley, "Guidelines for Cryptographic Key Management", BCP
107, RFC 4107, DOI 10.17487/RFC4107, June 2005.
7. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/rfc/rfc2119>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.
Acknowledgments
TODO acknowledge.
Author's Address
RAUT Expires 21 January 2027 [Page 25]
Internet-Draft OAuth Transaction Tokens Best Current Pr July 2026
ASHAY RAUT
Amazon
Email: asharaut@amazon.com
RAUT Expires 21 January 2027 [Page 26]