Skip to content

OAuth Transaction Tokens Best Current Practice

WG Working Group                                                 A. RAUT
Internet-Draft                                                    Amazon
Intended status: Informational                           21 January 2026
Expires: 25 July 2026

             OAuth Transaction Tokens Best Current Practice
                  draft-oauth-transactiontokens-bcp-01

Abstract

この文書は、draft-ietf-oauth-transaction-tokens で規定される OAuth 2.0 Transaction Tokens の実装およびデプロイに関する現時点の最良実践を示す。Transaction Tokens(Txn-Tokens)は、信頼ドメイン内のワークロードが、外部からのプログラムによるリクエストを処理する際に、ユーザーのアイデンティティおよび認可コンテキストをサービス境界をまたいで保持し、伝播できるようにする。本 BCP は、本番環境において安全かつ効果的に実装するために重要な、token service アーキテクチャ、サイズ管理、伝播パターン、検証戦略、運用監視といった実践的なデプロイ上の考慮事項を扱う。

About This Document

この注記は、RFC として公開する前に削除すること。

このドラフトの最新改訂版は、https://example.com/LATEST にある。この文書のステータス情報は、https://datatracker.ietf.org/doc/draft-oauth-transactiontokens-bcp/ で確認できる。

このドラフトのソースおよび issue tracker は、https://github.com/ashayraut/oauth-transactiontokens-best-current-practice にある。

Status of This Memo

この Internet-Draft は、BCP 78 および BCP 79 の規定に完全に準拠して提出されている。

Internet-Drafts は、Internet Engineering Task Force(IETF)の作業文書である。なお、他のグループも Internet-Drafts として作業文書を配布することがある。現在の Internet-Drafts の一覧は、https://datatracker.ietf.org/drafts/current/ にある。

Internet-Drafts は最大 6 か月間有効なドラフト文書であり、いつでも更新、置換、または廃止されることがある。これらを参考資料として用いたり、「work in progress」以外の形で引用したりすることは不適切である。

この Internet-Draft は 2026 年 7 月 25 日に失効する。

Copyright (c) 2026 IETF Trust および文書著者として特定された者。All rights reserved.

この文書は、この文書の公開日に有効な BCP 78 および IETF Trust の IETF Documents に関する法的規定に従う。これらの文書には、本書に関するあなたの権利および制限が記載されているため、注意深く確認すること。この文書から抽出される Code Components には、Trust Legal Provisions の Section 4.e に記載された Revised BSD License の文面を含めなければならず、また Revised BSD License に記載されたとおり無保証で提供される。

Table of Contents

1. Introduction

1.1. Background

マイクロサービスアーキテクチャに基づく現代の分散システムは、根本的な課題に直面している。すなわち、リクエストが複数のサービス境界を横断する際に、security context を維持することである。外部の actor が API リクエストを開始したとき、ユーザーのアイデンティティと認可コンテキストは保持され、そのリクエストの処理に関与するすべての下流の内部マイクロサービスで利用可能でなければならない。標準化された仕組みがなければ、組織は場当たり的な解決策に頼ることになり、それが security vulnerability、運用の複雑性、相互運用性の課題を招く。

OAuth 2.0 Transaction Tokens 仕様(draft-ietf-oauth-transaction-tokens)は、信頼ドメイン内の内部マイクロサービス間で安全にコンテキストを伝播できる token format と exchange protocol を定義することで、この課題に対処する。しかし、この仕様はプロトコルの仕組みに焦点を当てており、デプロイ実践までは対象としていない。実際の実装では、レイテンシ制約、token size の制限、schema の進化、伝播の信頼性、運用監視といった追加の課題に直面する。

1.2. Purpose of the BCP

この Best Current Practice 文書は、Txn-Token システムの本番デプロイから得られた知見に基づくガイダンスを実装者に提供する。これは、プロトコル仕様の範囲外ではあるが、デプロイ成功のために極めて重要な実践上の考慮事項を扱う。本書の推奨事項は、数百の内部マイクロサービスが複雑な呼び出し連鎖全体で security context の伝播を連携しなければならない大規模マイクロサービス環境における運用経験に基づいている。

この BCP の対象は次のとおりである。

  • Transaction Token Services を実装する組織
  • Txn-Token サポートを組み込む内部マイクロサービス開発者
  • 認可システムを設計する security architect
  • token 伝播を監視する運用チーム

2. Conventions and Definitions

この文書中のキーワード「MUST」、「MUST NOT」、「REQUIRED」、「SHALL」、「SHALL NOT」、「SHOULD」、「SHOULD NOT」、「RECOMMENDED」、「NOT RECOMMENDED」、「MAY」、および「OPTIONAL」は、すべて大文字で記載されている場合に限り、BCP 14 [RFC2119] [RFC8174] に記載されたとおりに解釈される。

この文書中のキーワード「MUST」、「MUST NOT」、「REQUIRED」、「SHALL」、「SHALL NOT」、「SHOULD」、「SHOULD NOT」、「RECOMMENDED」、「MAY」、および「OPTIONAL」は、RFC 2119 に記載されたとおりに解釈される。この文書では、draft-ietf-oauth-transaction-tokens における「Transaction Token」(Txn-Token)、「Transaction Token Service」、「trusted domain」、および「authorization context」といった用語を用いる。

3. Best Current Practices

3.1. Transaction Token Service Implementation

3.1.1. Service Architecture

組織は、token 発行、token 置換、およびその他の Txn-Token 関連機能を提供する Transaction Token Service(TTS)を構築するべきである。組織は、外部 actor の認証と認可を行う authorization service が、認証および認可リクエストの一部として Transaction Token を取得するために TTS を呼び出し、さらにそれと一緒に Txn-Token を渡すアーキテクチャを優先するべきである。こうすることで、外部 endpoint から TTS への明示的な呼び出しを避けられ、外部サービス側のコード変更も少なくて済む。さらに、token を置換したいすべての内部マイクロサービスは、TTS に直接接続するべきである。このアーキテクチャは、authorization service がすべての TTS 機能を担う案と、外部サービスが TTS に接続しなければならない案との間で、適切なバランスを取るものである。

3.1.2. Context Selection

Transaction Token Services は、draft-ietf-oauth-transaction-tokens で定義される必須 claims をすべて含めなければならない。しかし、services はすべての optional context をデフォルトで含めるべきではない。transaction context(tctx)や custom claims のような optional context は、明示的に要求された場合にのみ追加しなければならない。

組織は、特定の optional context を持つ Txn-Tokens を要求するためのインターフェースを提供する client library を用意するべきである。このアプローチにより、token の肥大化を防ぎつつ、各サービスが必要な context を取得できるようになる。解析エラー、形式違反、または利用不可によって optional context を追加できない場合でも、Transaction Token Service は token 発行を失敗させてはならない。代わりに、その特定の context を含めないまま token を発行するべきであり、運用監視のためにその状況をログに記録してもよい。

3.2. Token Size Management

3.2.1. Size Limits

Transaction Token Services は、4KB を超える token を発行してはならない。HTTP 仕様は最大 header size を義務付けていないが、一般的な web server 実装では Denial of Service 攻撃を防ぐために制限が設けられている。Apache はデフォルトで 8KB の最大 header size を採用しているが、組織は同じリクエスト内の他の headers も考慮しなければならない。Txn-Tokens に 4KB の上限を設けることで、十分な余裕を確保しつつ、運用上の問題を防げる。

組織は、token size が上限に近づく傾向を検知するため、token size の監視を実装するべきである。サイズ制限に継続的に近づく services は、context の過剰な包含か、または context relocation 戦略の必要性を示している。

3.2.2. Context Relocation

authorization context が 4KB を超える場合、Transaction Token Services は relocation endpoint を実装するべきである。この service は、サイズ超過した context を、Txn-Token identifier を primary key として別の data store に保存する。Txn-Token 自体には、移動された context への参照のみを含める。

token 検証用の client library は、context relocation を透過的に処理するべきである。内部マイクロサービスが relocation 済みの context を要求した場合、その library は relocation endpoint からそれを取得する。このパターンは、追加属性を実行時に取得する Attribute-Based Access Control(ABAC)システムの Policy Information Points に似ている。

context relocation は、追加のレイテンシと障害モードを持ち込む。組織は relocation を通常系ではなく例外として扱うべきである。relocation の頻度を監視し、過剰な context を継続的に必要とする services を特定するべきである。

3.3. Token Lifetime and Expiration

Transaction tokens の time-to-live は 5 分未満にするべきである。組織は、外部 endpoint に対して定義された latency Service Level Agreements(SLAs)から逆算して、適切な lifetime を決定するべきである。

短い token lifetime は、token が侵害された場合の利用可能時間を短縮し、token mix-up シナリオの影響も限定する。しかし、その lifetime は SOA における最長の想定呼び出し連鎖を収容できなければならない。組織は実際のリクエスト処理時間を測定し、99 パーセンタイル値を適切な余裕をもって上回るように token lifetime を設定するべきである。

リクエスト処理中に token が失効した場合、services は新しい token を自動的に要求してはならない。失効した token は、呼び出し連鎖が長すぎるか、性能上の問題があることを示しており、調査が必要である。services は失効した token を伴うリクエストを失敗させ、運用監視のための telemetry を出力するべきである。

3.4. Schema Governance

3.4.1. Context Visibility

組織は、Txn-Tokens に追加される contexts を統制しなければならない。ある context が Txn-Token に現れた瞬間、それは呼び出し連鎖上のすべてのサービスから見えるようになる。services は、context 提供者が想定していない形でその context に依存するようになる可能性がある。この現象は Hyrum's Law に従う。すなわち、十分な数の利用者がいれば、システムの観測可能な振る舞いは誰かに依存される。

新しい context を Txn-Tokens に追加する前に、組織はその context が普遍的に可視になることの影響を考慮しなければならない。もしその context が呼び出し連鎖の初期段階の services だけが知っている identifier や概念を表すなら、それを Txn-Token に追加すると、すべての下流 services に露出することになる。そうした services は、その context に対して security 上だけでなく business logic 上の依存を持つようになるかもしれない。

広く可視な context の形式または意味を変更しなければならない場合、組織は痛みを伴う移行プロセスに直面する。その context に依存するすべての services を特定し、更新し、デプロイしなければならない。意味的な変更が必要な場合、組織は既存 context を変更するのではなく、異なる名前の新しい context を追加することを優先するべきである。

3.4.2. Backward Compatibility

組織は、Txn-Token contexts に対する backward compatibility テストを実装しなければならない。自動テストは、context format や structure の変更が既存の consumer を壊さないことを検証するべきである。これらのテストは、Transaction Token Service の continuous integration pipeline の一部として実行されるべきである。

Txn-Tokens を利用する services の数が増えるほど、backward compatibility テストの重要性は高まる。自動検証がなければ、format の変更が SOA 全体に cascading failure を引き起こす危険がある。

3.5. Token Propagation

3.5.1. Propagation Control

組織は、Txn-Tokens が trusted domain の外に伝播するのを防がなければならない。tokens には暗号化された機密データが含まれているが、組織は外部伝播を遮断する明示的な制御を実装するべきである。Propagation libraries は、内部マイクロサービスが外部 endpoint へのリクエストに Txn-Token を含めようとしたことを検知し、そのリクエストから token を除去しなければならない。

この多層防御のアプローチは、設定ミスや実装ミスから保護する。token の暗号化自体が安全であったとしても、外部伝播を防ぐことで、潜在的 vulnerability の一群そのものを排除できる。

3.5.2. Propagation Libraries

組織は、内部マイクロサービスのワークロード処理における token lifecycle を扱う標準化された propagation library を提供するべきである。これらの libraries は、受信 HTTP header から Txn-Token を取り出し、request-scope の memory に保存し、送信リクエストの header に token を追加し、リクエスト処理完了時に memory から消去しなければならない。

標準化された libraries にはいくつかの利点がある。第一に、外部遮断を含む propagation controls を強制できるため、token が trust boundary の外へ流れるのを防げる。第二に、token の開始、伝播、検証に関する telemetry を一貫して出力するために利用できる。第三に、token が欠落している場合の fallback behavior を実装するための集中ポイントを提供する。

3.5.3. Propagation Reliability

組織は、SOA 全体にわたる propagation success rate を監視するべきである。ある呼び出し連鎖における propagation success が 100% に達しない限り、services は Txn-Token の内容に基づく認可ポリシーを信頼して適用できない。tokens が存在しない場合に備え、services は合理的な fallback behavior を実装しなければならない。

Propagation libraries は、受信リクエストに Txn-Token がない場合、自動的に token の開始を実装してもよい。その library は、現在の service に context が渡されなかったことを示す placeholder token を Transaction Token Service に要求する。この placeholder により、下流 services は呼び出し連鎖のどこで propagation が壊れたかを特定でき、運用上のデバッグが容易になる。

3.5.4. Token Mix-up Prevention

token mix-up は、伝播における最も深刻なリスクである。mix-up は、あるリクエスト向けの token が誤って別のリクエストに付与されたときに発生する。たとえば token T1 が request R1 用、token T2 が request R2 用であるにもかかわらず、propagation bug により R1 に T2 が送られると、actor は本来閲覧権限のないデータにアクセスできてしまう可能性がある。

token mix-up のシナリオは、明白な障害を引き起こさないことがあるため検知が難しい。リクエスト自体は成功するが、誤った authorization context で処理される。組織は、mix-up を防ぐために propagation libraries に request-scope の token storage を実装しなければならない。tokens は特定の request context に紐付けられなければならず、共有状態やグローバル状態に保存してはならない。

組織は、並行負荷下で意図的に token mix-up を起こそうとするテスト戦略を実装するべきである。これらのテストにより、propagation libraries が並行リクエスト間で tokens を正しく分離できていることを検証できる。

3.5.5. Trust Boundary Handling

リクエストが組織内の trust boundary をまたぐ場合、propagation libraries は token の伝播を遮断するか、あるいは適切にスコープされた contexts に token contents を置き換えなければならない。組織は trust boundaries を明示的に定義し、boundary detection logic を propagation libraries に設定するべきである。

trust boundary 上では、services は対象となる trust domain に適した contexts を持つ新しい Txn-Tokens を Transaction Token Service に要求してもよい。このアプローチにより、security boundary を尊重しつつ context 伝播を維持できる。

3.5.6. Cache Considerations

Txn-token の導入により、マイクロサービスアーキテクチャ全体のグラフに、これまで以上に多くの情報が渡るようになる。このグラフ内には、依存サービスへの複数回の呼び出しを避けるためにデータをキャッシュする Services が存在する。今後、それらは cache key に Txn-Token contexts を含めることを考慮するべきである。含めない場合、誤ったデータが返されたり、依存サービスが結果計算に Txn-Token contexts を使っていることで、本来キャッシュされるべき結果が適切にヒットしなかったりするリスクがある。

組織は、Txn-Tokens が関わる場合の cache key 構築について、ワークロード開発者向けのガイダンスを提供するべきである。cache invalidation 戦略は、キャッシュされたデータに影響する context の変更を考慮しなければならない。

3.6. Token Validation

3.6.1. Validation Libraries

組織は、signature verification、復号、token parsing を扱う標準化された validation library を提供するべきである。これらの libraries は、cryptographic keys をバックグラウンドで同期し、services が常に検証および復号のための最新の keys を保持できるようにするべきである。

Validation libraries は、Txn-Tokens を実装言語に適した strongly-typed objects に decode するべきである。このアプローチにより parsing error を防ぎ、context access pattern に対するコンパイル時検証が可能になる。

3.6.2. Error Handling

Validation libraries は、expired token、malformed token、signature verification failure を含む一般的な障害条件に対して、標準化された error code を出力するべきである。これらの error code によって、SOA 全体で一貫した運用監視が可能になる。

3.6.3. Fallback Policies

Txn-Tokens が欠落している、または無効である場合に、services は自動的にリクエストを失敗させるべきではない。組織は、security と user experience のバランスを取る fallback policy を定義しなければならない。fallback policy には、マスクしたデータを返すこと、機能を制限すること、または step-up authentication を要求することが含まれてもよい。

適切な fallback は、要求された操作の機微性に依存する。高度に機微なデータにアクセスする services は、有効な Txn-Tokens を必須とし、token がない場合にリクエストを失敗させてもよい。機微性の低い機能を提供する services は、段階的に機能を落とす graceful degradation を実装するべきである。

3.7. Telemetry and Monitoring

3.7.1. Adoption Monitoring

大規模 SOA 環境における transaction token の導入には時間がかかる。組織は、導入の進捗、伝播の信頼性、検証パターンを監視するために、包括的な telemetry を実装するべきである。

組織が token の開始、伝播、検証のための標準化された libraries を提供する場合、telemetry logic はそれらの libraries に組み込むべきである。このアプローチにより、個々のワークロード実装に依存せず、すべての services で一貫した telemetry を確保できる。

3.7.2. Telemetry Aggregation

services は、telemetry を centralized monitoring systems に送信する前にローカルで集約するべきである。ローカル集約により network overhead を削減でき、監視基盤に過負荷をかけずに、より高頻度のサンプリングが可能になる。

centralized monitoring systems は、分析クエリをサポートする data warehouse に telemetry を保存するべきである。組織は、伝播率、検証失敗、token expiration rate の大きな変化を警告する自動 monitor を実装するべきである。

3.7.3. Key Metrics

組織は、次の主要 metrics を監視するべきである。

  • サービスごとの token initiation rate
  • 呼び出し連鎖ごとの propagation success rate
  • リクエスト処理中の token expiration rate
  • error type ごとの validation failure rate
  • token size distribution
  • context relocation frequency

これらの metrics は、SOA 全体における Txn-Token の健全性を可視化し、デプロイ上の問題を迅速に特定できるようにする。

3.8. Key Management

組織は、Txn-Token の cryptographic operations に対して安全な key management 実践を実装しなければならない。key management は、RFC 4107「Guidelines for Cryptographic Key Management」の指針に従うべきである。

Transaction Token Services は、サービス中断なしに key rotation をサポートしなければならない。Validation libraries は、ゼロダウンタイムで rotation を可能にするため、複数の concurrent keys をサポートしなければならない。組織は、定期スケジュールで key rotation を自動化するべきである。

3.9. Batch Processing pattern

OAuth Transaction Tokens は、trust domain 内の呼び出し連鎖を通じて security context を伝播するよう設計されている。グローバルな失効基盤を持つオーバーヘッドなしに高い security posture を維持するため、これらの tokens は短命である(通常は数分)。現代的な多くのアーキテクチャでは、transaction は非同期であり得る。たとえば、リクエストが message queue(例: Kafka、RabbitMQ)に置かれ、数時間後または数日後に worker service によって処理される場合がある。worker が transaction を再開する時点では、元の Transaction Token はすでに失効している。

Batch Token(Voucher): 静止期間中の transaction context を表す長寿命の opaque あるいは暗号化 token。
Initiator: Transaction Token を受け取り、非同期停止の前に Batch Token を要求する内部マイクロサービス。
Rehydrator: Batch Token を受け取り、それを新しい短命の Transaction Token に交換して処理を再開する内部マイクロサービス。

3.9.1. Initiation (Pausing the Transaction)

内部マイクロサービスが、transaction が現在の Transaction Token(TraT)の TTL を超えると判断した場合、それは Transaction Token Service(TTS)に Batch Token を要求するべきである。TTS へのリクエストには、次を含めるべきである。

  • 現在有効な TraT
  • token を制約するための意図された「use case ID」または「namespace」

TTS は、非同期遅延に適した TTL(例: 24 時間から 7 日)を持つ Batch Token を返す。

3.9.2. Rehydration (Resuming the Transaction)

worker service(Rehydrator)がタスクを取得したとき、それは下流 services を呼び出すために Batch Token を直接使ってはならない。代わりに、それは Batch Token を TTS に提示し、新しい TraT と交換しなければならない。TTS は次を行わなければならない。

  1. Batch Token の signature と expiration を検証する。
  2. Rehydrator が、Batch Token に埋め込まれた特定の「use case ID」または「namespace」に対して認可されていることを検証する。
  3. 元の claims(例: subject、元のリクエスタの IP)を含む、新しい短命の TraT を発行する。

4. Security Considerations

4.1. Token Mix-up Prevention

token mix-up は重大な security risk である。組織は request-scope の token storage を実装しなければならず、並行負荷下で mix-up シナリオをテストしなければならない。token mix-up は、明白なシステム障害なしに unauthorized data access を招く可能性があるため、特に危険である。

4.2. Trust Boundary Controls

組織は trust boundaries を明示的に定義しなければならず、それらの境界を越えた不適切な token 伝播を防ぐ制御を実装しなければならない。trust boundary での伝播制御に失敗すると、機密 context が認可されていない services に露出する可能性がある。

4.3. Cache Security

Txn-Token contexts に基づいてデータをキャッシュする services は、cache keys に関連するすべての contexts が組み込まれていない場合、security risk に直面する。組織は安全な cache key 構築に関するガイダンスを提供しなければならず、正しい context handling が行われているかを caching services について監査しなければならない。

4.4. Fallback Mechanisms

fallback mechanism は可用性を高める一方で、慎重に設計されないと security vulnerability を招く可能性がある。組織は、Txn-Tokens が存在しない場合に fallback policy が意図せず過剰な access を与えないことを保証しなければならない。fallback policy は明示的に文書化し、security team によるレビューを受けるべきである。

4.5. Token Lifetime

短い token lifetime は token compromise の利用可能期間を短縮するが、過度に短く設定すると運用上の問題を引き起こす可能性がある。組織は、token lifetime を設定する際、security 上の考慮事項と運用要件のバランスを取らなければならない。

4.6. External Propagation

Txn-Tokens が trusted domain の外に出ないようにすることは極めて重要である。組織は、library-level の制御、network-level の filtering、外部伝播の試行に対する monitoring を含む複数層の防御を実装しなければならない。

4.7. Batch processing security consideration

4.7.1. Token Constraining

Batch Tokens は sender-constrained であるか、特定の namespace にスコープされていなければならない。これにより、侵害された service が queue から Batch Token を「盗み」、無関係な flow 用の Transaction Token を正常に発行してしまうことを防げる。

非同期遅延により、基礎となる authorization context が変更されているリスクが高まる(例: ユーザーが同意を取り消した)。TTS は、mutable または sensitive とマークされた claims について、rehydration 時に「freshness check」を行うべきである。

4.7.3. Infinite Exchange Prevention

繰り返しの rehydration により transaction が無期限に存続することを防ぐため、TTS は token metadata 内で最大 chain depth または total transaction lifetime counter を実装するべきである。

5. IANA Considerations

この文書に IANA actions はない。

6. References

6.1. Normative References

RFC2119 Bradner, S., 「Key words for use in RFCs to Indicate Requirement Levels」, BCP 14, RFC 2119, DOI 10.17487/RFC2119, 1997 年 3 月。

TXNTOKENS Tulshibagwale, A., Hardt, D., and G. Fletcher, 「OAuth 2.0 Transaction Tokens」, draft-ietf-oauth-transaction-tokens-06(work in progress)。

6.2. Informative References

RFC4107 Bellovin, S. and R. Housley, 「Guidelines for Cryptographic Key Management」, BCP 107, RFC 4107, DOI 10.17487/RFC4107, 2005 年 6 月。

7. Normative References

[RFC2119] Bradner, S., 「Key words for use in RFCs to Indicate Requirement Levels」, BCP 14, RFC 2119, DOI 10.17487/RFC2119, 1997 年 3 月。

[RFC8174] Leiba, B., 「Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words」, BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2017 年 5 月。

Acknowledgments

TODO acknowledge.

Author's Address

ASHAY RAUT
Amazon

Email: asharaut@amazon.com