RFC 8693: OAuth 2.0 トークン交換

RFC 8693	OAuth 2.0 トークン交換	2020年1月
Jones ほか	標準化過程	[ページ]

概要

この仕様は、OAuth 2.0 認可サーバーからセキュリティトークンを要求して取得する方法を定義することにより、HTTP および JSON ベースの Security Token Service (STS) のプロトコルを定義します。これには、なりすましおよび委任を使用するセキュリティトークンも含まれます。¶

セキュリティトークンとは、異種環境または異なるセキュリティドメイン間でのアイデンティティ情報およびセキュリティ情報の共有を容易にする情報の集合です。セキュリティトークンの例には、JSON Web Token (JWT) [JWT] および Security Assertion Markup Language (SAML) 2.0 アサーション [OASIS.saml-core-2.0-os] があります。セキュリティトークンは通常、完全性を確保するために署名され、場合によっては機密性を確保するために暗号化もされます。セキュリティトークンは、[RFC7521] のように、アサーションと呼ばれることもあります。¶

Security Token Service (STS) は、提供されたセキュリティトークンを検証し、それに応答して新しいセキュリティトークンを発行できるサービスであり、これによりクライアントは異種環境または異なるセキュリティドメインにあるリソースに適したアクセス資格情報を取得できます。 Web サービスのクライアントは、トークン交換のために STS と対話するプロトコルとして WS-Trust [WS-Trust] を使用してきました。 WS-Trust は XML と SOAP を使用しますが、現代の Web 開発の傾向は RESTful (Representational State Transfer) パターンおよび JSON へと移っています。 OAuth 2.0 Authorization Framework [RFC6749] および OAuth 2.0 Bearer Tokens [RFC6750] は、サードパーティーアプリケーションによる HTTP および RESTful リソースへのアクセスを認可するための一般的な標準として普及しています。従来の OAuth 2.0 の対話では、リソース所有者の認可を何らかの形で表現したものをアクセストークンと交換します。これは実際に極めて有用なパターンであることが実証されています。しかし、その入力と出力は、そのままではセキュリティトークン交換フレームワークを完全に収容するにはやや制約が強すぎます。¶

この仕様は OAuth 2.0 を拡張するプロトコルを定義し、クライアントが STS の役割を担う認可サーバーからセキュリティトークンを要求して取得できるようにします。 OAuth 2.0 と同様に、この仕様はクライアント開発者にとっての簡潔性を重視し、現代の開発環境でほぼ普遍的に利用可能な HTTP クライアントと JSON パーサーのみを必要とします。この仕様で定義する STS プロトコル自体は RESTful ではありません（STS は REST アプローチに特に適しているわけではありません）が、RESTful システムでの作業に慣れた開発者には馴染み深いはずの通信パターンとデータ形式を使用します。¶

トークン交換要求のための新しいグラントタイプと、トークンエンドポイントへのそのような要求に関連する固有のパラメーターを、この仕様で定義します。トークン交換応答はトークンエンドポイントからの通常の OAuth 2.0 応答であり、クライアントに情報を提供するために、ここで定義するいくつかの追加パラメーターを含みます。¶

トークン交換を要求するエンティティは、トークン交換の対話の文脈ではクライアントとみなされます。ただし、これはこのプロファイルの使用を従来の OAuth クライアントに限定するものではありません。たとえば OAuth リソースサーバーは、保護リソース要求で受信したアクセストークンを、バックエンドサービスの呼び出しに含めるのに適した新しいトークンと交換するため、トークン交換中にクライアントの役割を担うことができます。新しいトークンは、ダウンストリームサービス向けにより狭いスコープを持つアクセストークンである場合も、まったく異なる種類のトークンである場合もあります。¶

この仕様の範囲は、OAuth 2.0 を利用する STS 形式のトークン交換のための基本的な要求・応答プロトコルの定義に限定されます。委任セマンティクスを表現できるいくつかの新しい JWT クレームを定義しますが、トークン自体の具体的な構文、セマンティクス、セキュリティ特性（認可サーバーに提示されるものとクライアントが取得するものの両方）は明示的に範囲外であり、実装が配備される可能性のある信頼モデルについても要件を課しません。追加のプロファイルでは、関係する当事者や信頼の具体的な性質について、トークンの署名および／または暗号化が必要か、proof-of-possession 形式のトークンが要求または発行されるかなど、より詳細な要件を定めることができます。しかし、このような詳細は多くの場合、個々の配備の具体的なニーズに基づいて決定されるポリシーであり、それに応じて構成または実装されます。¶

取得したセキュリティトークンはさまざまな文脈で使用できますが、その具体的な内容もこの仕様の範囲外です。¶

1.1. 委任となりすましのセマンティクス

STS の一般的なユースケースの一つ（前節で触れたように）は、リソースサーバー A が要求元ユーザー B に代わってバックエンドサービス C を呼び出せるようにすることです。ローカルサイトのポリシーおよび認可インフラストラクチャによっては、A が自らの資格情報を使用して C にアクセスし、A が B に代わって行動していることを何らかの形で示す注記を付ける（「委任」）か、A に C への限定的なアクセス資格情報を付与しながら、B を認可されたエンティティとして引き続き識別する（「なりすまし」）ことが望ましい場合があります。委任となりすましは、複数の参加者が関与する他のシナリオでも有用な概念となり得ます。¶

プリンシパル A がプリンシパル B になりすます場合、A には定義された権利の文脈内で B が持つすべての権利が与えられ、その文脈内では B と区別できません。したがって、プリンシパル A がプリンシパル B になりすます場合、そのようなトークンを受け取るエンティティから見れば、実際には B とやり取りしていることになります。アイデンティティシステムの一部の構成員が、なりすましが行われていることを認識している場合もありますが、それは要件ではありません。実質的に、A が B になりすましている場合、トークンによって認可された権利の文脈において A は B です。A が B になりすます能力は、トークンの内容または帯域外の仕組みによって、スコープや時間が制限されたり、さらには一回限りの使用に制限されたりする場合があります。¶

委任のセマンティクスはなりすましのセマンティクスとは異なりますが、両者は密接に関連しています。委任のセマンティクスでは、プリンシパル A は B とは別個の自らのアイデンティティを保持し、B が自らの権利の一部を A に委任している場合でも、行われるあらゆる操作は B を代表する A によって行われることが明示的に理解されます。ある意味で、A は B の代理人です。¶

委任となりすましがすべての状況を包含するわけではありません。たとえば、プリンシパルが自らのために直接行動する場合、委任もなりすましも関与しません。しかし、これらはトークン交換でより一般的に用いられるセマンティクスであるため、この仕様ではより直接的に扱われます。¶

委任のセマンティクスは通常、トークンの主要なサブジェクトと、そのサブジェクトから権利の一部を委任されたアクターの両方に関する情報を含めることで、トークン内に表現されます。このようなトークンは、複数のサブジェクトに関する情報から構成されるため、複合トークンと呼ばれることがあります。通常、要求では subject_token がトークンの要求対象となる当事者のアイデンティティを表し、actor_token は発行されるトークンのアクセス権が委任される当事者のアイデンティティを表します。認可サーバーによって発行される複合トークンには、両方の当事者に関する情報が含まれます。複合トークンをいつ、そして実際に発行するかどうかは、認可サーバーと適用されるポリシーおよび構成の裁量に委ねられます。¶

複合トークンをどのように表現するか、さらにはそのようなトークンを発行するかどうかの詳細は、実装の詳細およびトークンの種類に依存します。JWT ではない複合トークンの表現は、この仕様の範囲外です。ただし、actor_token 要求パラメーターは、望ましいアクターに関する情報を提供する手段を提供し、JWT の act クレームは委任チェーンを表現できます。¶

1.2. 要件表記と規約

この文書におけるキーワード「しなければならない」、「してはならない」、「必須」、「しなければならない」、「してはならない」、「するべきである」、「するべきではない」、「推奨」、「非推奨」、「してもよい」、および「任意」は、ここに示すようにすべて大文字で現れる場合にのみ、 BCP 14 [RFC2119] [RFC8174] に記述されているとおりに解釈されます。¶

1.3. 用語

この仕様では、OAuth 2.0 [RFC6749] で定義される「アクセストークンタイプ」、「認可サーバー」、「クライアント」、「クライアント識別子」、「リソースサーバー」、「トークンエンドポイント」、「トークン要求」、「トークン応答」という用語、および JSON Web Token (JWT) [JWT] で定義される「Base64url エンコーディング」、「クレーム」、「JWT クレームセット」という用語を使用します。¶

2. トークン交換の要求と応答

2.1. 要求

クライアントは、第 4.5節 of [RFC6749] で定義された拡張グラントタイプの仕組みを使用して、認可サーバーのトークンエンドポイントにトークン要求を行うことにより、セキュリティトークンを要求します。¶

認可サーバーに対するクライアント認証は、OAuth 2.0 が提供する通常の仕組みを使用して行われます。第 2.3.1節 of [RFC6749] はクライアントのパスワードベース認証を定義していますが、クライアント認証は拡張可能であり、他の仕組みも使用できます。たとえば、[RFC7523] は Bearer JSON Web Token (JWT) [JWT] を使用するクライアント認証を定義しています。サポートされるクライアント認証方法、および認証されていない、または識別されていないクライアントを許可するかどうかは、認可サーバーの裁量による配備上の決定です。クライアント認証を省略すると、侵害されたトークンを所持する者であれば誰でも、STS を介してそのトークンを他のトークンへ利用できることに注意してください。したがって、クライアント認証により、どのエンティティが他のエンティティになりすましたり、他のエンティティから委任を受けたりすることを許可されるかについて、 STS が追加の認可チェックを行えるようになります。¶

クライアントは、HTTP POST メソッドを使用して、拡張グラントタイプによるトークン交換要求をトークンエンドポイントに行います。次のパラメーターは、付録 B of [RFC6749] に記述されているとおり、UTF-8 の文字エンコーディングを使用した application/x-www-form-urlencoded 形式で HTTP 要求のエンティティ本体に含められます。¶

grant_type: 必須。値 urn:ietf:params:oauth:grant-type:token-exchange は、トークン交換が実行されていることを示します。¶
resource: 任意。クライアントが要求したセキュリティトークンを使用する予定の対象サービスまたはリソースを示す URI です。これにより認可サーバーは、発行するトークンのタイプや内容を決定したり、トークンを暗号化するかどうか、またどのように暗号化するかを決定したりするなど、対象に応じた適切なポリシーを適用できます。多くの場合、クライアントは対話するシステムの論理的構成を知らず、トークンを使用する予定のサービスの URI だけを知っています。 resource パラメーターにより、クライアントはトークン交換要求内で、通常は https URL として位置を指定し、そのリソースへのアクセスに使用するのと同じ形式で、発行されたトークンをどこで使用する予定かを認可サーバーに示せます。認可サーバーは通常、リソース URI 値から適切なポリシーへマッピングする機能を持ちます。resource パラメーターの値は、第 4.3節 of [RFC3986] で指定されている絶対 URI でなければならず、クエリコンポーネントを含んでもよいですが、フラグメントコンポーネントを含んではなりません。複数の resource パラメーターを使用して、発行されたトークンが列挙された複数のリソースで使用されることを意図していることを示せます。 resource パラメーターの追加の背景情報および用途については、 [OAUTH-RESOURCE] を参照してください。¶
audience: 任意。クライアントが要求したセキュリティトークンを使用する予定の対象サービスの論理名です。これは resource パラメーターと同様の目的を果たしますが、クライアントが対象サービスの論理名を提供します。その名前を解釈するには、値がクライアントと認可サーバーの双方に理解できるものである必要があります。OAuth クライアント識別子、SAML エンティティ識別子 [OASIS.saml-core-2.0-os]、および OpenID Connect 発行者識別子 [OpenID.Core] は、 audience パラメーターの値として使用できるものの例です。ただし、特定の認可サーバーで使用される audience 値は、意図した種類の値として正しく解釈されるよう、そのサーバー内で一意でなければなりません。複数の audience パラメーターを使用して、発行されたトークンが列挙された複数のオーディエンスで使用されることを意図していることを示せます。audience パラメーターと resource パラメーターは、論理名とリソース URI を組み合わせて複数の対象サービスを示すために併用できます。¶
scope: 任意。第3.3節 of [RFC6749] で定義されている、空白で区切られた大文字小文字を区別する文字列のリストであり、クライアントが、トークンを使用するサービスまたはリソースの文脈において、要求するセキュリティトークンの望ましいスコープを指定できるようにします。スコープの値と関連するセマンティクスはサービス固有であり、関連するサービス文書に記述されることが想定されます。¶
requested_token_type: 任意。要求するセキュリティトークンのタイプを示す、第3節で記述されている識別子です。要求するタイプが指定されていない場合、発行されるトークンタイプは認可サーバーの裁量に委ねられ、 resource または audience パラメーターで示されるサービスまたはリソースの要件に関する知識によって決定されることがあります。¶
subject_token: 必須。要求の対象となる当事者のアイデンティティを表すセキュリティトークンです。通常、このトークンのサブジェクトは、要求への応答として発行されるセキュリティトークンのサブジェクトになります。¶
subject_token_type: 必須。 subject_token パラメーター内のセキュリティトークンのタイプを示す、第3節で記述されている識別子です。¶
actor_token: 任意。行為者のアイデンティティを表すセキュリティトークンです。通常、これは要求されたセキュリティトークンの使用を認可され、サブジェクトに代わって行動する当事者です。¶
actor_token_type: actor_token パラメーター内のセキュリティトークンのタイプを示す、第3節で記述されている識別子です。 actor_token パラメーターが要求に存在する場合は必須ですが、それ以外の場合は含めてはなりません。¶

要求を処理する際、認可サーバーは、示されたトークンタイプに適した検証手順を実行しなければならず、アクタートークンが存在する場合は、その示されたトークンタイプに対しても適切な検証手順を実行しなければなりません。特定のトークンの有効性基準および詳細は、この文書の範囲外であり、それぞれのトークンタイプとその内容に固有です。¶

一回限りの使用またはトークンタイプ固有のその他のセマンティクスがない限り、トークン交換を実行する行為は、サブジェクトトークンまたはアクタートークンの有効性に影響しません。さらに、交換は一回限りのイベントであり、入力トークンと出力トークンの間に強い結び付きを作成しないため、（たとえば）出力トークンの有効期限が入力トークンの有効期限の影響を受ける場合はあっても、入力トークンの更新または延長が出力トークンのプロパティに反映されることは想定されません。トークン失効イベントを伝播することが適切または望ましい場合もあります。ただし、これは STS プロトコルの一般的な特性ではなく、特定の実装、トークンタイプ、または配備に固有のものです。¶

2.1.1. リソース、オーディエンス、スコープの関係

トークンを要求するとき、クライアントは audience および resource パラメーターを使用して、そのトークンを使用する予定の望ましい対象サービスを示すことができ、また scope パラメーターを使用して要求するトークンの望ましいスコープを示すことができます。このような要求のセマンティクスは、クライアントが要求したすべての対象サービスで使用可能な、要求されたスコープを持つトークンを要求しているということです。実質的に、トークンに要求されるアクセス権は、すべての対象サービスにおけるすべてのスコープの直積です。¶

認可サーバーは、いかなるトークン要求についても応じる意思がない、または応じることができない場合がありますが、非常に広範なアクセス権が要求されている場合、応じられない要求となる可能性は著しく高くなります。したがって、配備内のシステム間の関係について具体的な知識がない場合、クライアントは要求するアクセスの広さ、特に対象サービスの数について慎重に判断するべきです。認可サーバーは、第2.2.2節で定義された invalid_target エラーコードを使用して、クライアントが同時に多すぎる対象サービスへのアクセスを要求したことを通知できます。¶

2.2. 応答

認可サーバーは、第5節 of [RFC6749] で指定されているとおり、トークンエンドポイントからの通常の OAuth 2.0 応答でトークン交換要求に応答します。追加の詳細と説明を次の各小節で示します。¶

2.2.1. 成功応答

要求が有効であり、認可サーバーのすべてのポリシーおよびその他の基準を満たす場合、 [RFC8259] で指定された "application/json" メディアタイプと HTTP 200 ステータスコードを使用して、HTTP 応答のエンティティ本体に次のパラメーターを追加することにより、成功したトークン応答を構築します。パラメーターは、それぞれをトップレベルに追加して JavaScript Object Notation (JSON) 構造へシリアライズされます。パラメーター名と文字列値は JSON 文字列として含められます。数値は JSON 数値として含められます。パラメーターの順序は重要ではなく、変わる場合があります。¶

access_token: 必須。トークン交換要求への応答として認可サーバーによって発行されるセキュリティトークンです。第5.1節 of [RFC6749] の access_token パラメーターは、ここでは要求されたトークンを運ぶために使用され、これにより、このトークン交換プロトコルはトークンエンドポイント向けに定義された既存の OAuth 2.0 の要求および応答の構造を使用できます。識別子 access_token は歴史的な理由で使用されており、発行されるトークンは OAuth アクセストークンである必要はありません。¶
issued_token_type: 必須。発行されるセキュリティトークンの表現を示す、第3節で記述されている識別子です。¶
token_type: 必須。第7.1節 of [RFC6749] で指定されている、発行されたアクセストークンの使用方法を指定する、大文字小文字を区別しない値です。これは、保護されたリソースにアクセスするためにアクセストークンをどのように使用するかについての情報をクライアントに提供します。たとえば、[RFC6750] で指定された Bearer という値は、発行されたセキュリティトークンがベアラートークンであり、クライアントがトークン自体の内容以外に適格性を証明する追加の証拠なしで、そのまま提示できることを示します。このパラメーターの意味は、発行されたセキュリティトークンの表現を宣言する issued_token_type パラメーターの意味とは異なることに注意してください。「トークンタイプ」という用語は、通常、セキュリティトークンの構造的または構文的な表現を意味するために使用され、この仕様のすべての *_token_type パラメーターでもその意味で使用されています。発行されたトークンがアクセストークンではない、またはアクセストークンとして使用できない場合、 token_type 値 N_A を使用して、その文脈では OAuth 2.0 の token_type 識別子が適用されないことを示します。¶
expires_in: 推奨。認可サーバーによって発行されたトークンの有効期間を秒単位で示します。多くの場合、クライアントはトークンの内容を調べる意図や能力を持たず、このパラメーターは、トークンタイプに依存しない一貫した形で、トークンがどの程度の期間有効であると見込めるかを示します。たとえば、値 1800 は、応答が生成された時点から 30 分後にトークンが期限切れになることを示します。¶
scope: 発行されたセキュリティトークンのスコープがクライアントによって要求されたスコープと同一である場合は任意であり、それ以外の場合は必須です。¶
refresh_token: 任意。ある一時的な資格情報（subject_token）を、別の文脈で使用する別の一時的な資格情報（発行されるトークン）と交換する場合、通常、リフレッシュトークンは発行されません。トークン交換のクライアントが、元の資格情報が有効でなくなった後でもリソースにアクセスする能力を必要とする場合（たとえば、クライアントとのアクティブなセッションを維持しているユーザーが存在しない、ユーザー不在またはオフラインのシナリオ）には、リフレッシュトークンを発行できます。この仕様のプロファイルまたは配備では、 urn:ietf:params:oauth:grant-type:token-exchange グラントタイプの要求への応答として、クライアントがどの条件でリフレッシュトークンを期待すべきかを明確に文書化するべきです。¶

2.2.2. エラー応答

要求自体が有効でない場合、または subject_token もしくは actor_token のいずれかが何らかの理由で無効であるか、ポリシーに基づいて受け入れられない場合、認可サーバーは、第 5.2節 of [RFC6749] で指定されているとおり、エラー応答を構築しなければなりません。 error パラメーターの値は、 invalid_request エラーコードでなければなりません。¶

認可サーバーが、resource または audience パラメーターで示された対象サービスに対してトークンを発行する意思がない、または発行できない場合、エラー応答では invalid_target エラーコードを使用するべきです。¶

認可サーバーは、第 5.2節 of [RFC6749] で説明されている error_description を使用して、エラーの理由に関する追加情報を含めてもよいです。¶

必要に応じて、他のエラーコードも使用できます。¶

2.3. トークン交換の例

次の例は、OAuth リソースサーバーが交換中にクライアントの役割を担う、仮想的なトークン交換を示しています。リソースサーバーは、保護リソース要求で受信したアクセストークンを、バックエンドサービスの呼び出しに使用する新しいトークンと交換します（例中の余分な改行とインデントは表示目的のみです）。¶

図1は、第 2.1節 of [RFC6750] で指定されているとおり、 Authorization ヘッダーに OAuth アクセストークンを含む保護リソース要求をリソースサーバーが受信する様子を示しています。¶

 GET /resource HTTP/1.1
 Host: frontend.example.com
 Authorization: Bearer accVkjcJyb4BWCxGsndESCJQbdFMogUC5PbRDqceLTC

図1: 保護リソース要求

図2では、リソースサーバーがトークン交換のクライアントの役割を担い、図1の要求から得たアクセストークンを、第2.1節で指定された要求を使用して認可サーバーへ送信します。 subject_token パラメーターの値にはアクセストークンが入り、 subject_token_type パラメーターの値は、それが OAuth 2.0 アクセストークンであることを示します。クライアントの役割を担うリソースサーバーは、 HTTP Basic 認証方式を使用して、自身の識別子とシークレットで認可サーバーに対して認証します。 resource パラメーターは、発行されたトークンが使用されるバックエンドサービス <https://backend.example.com/api> の位置を示します。¶

 POST /as/token.oauth2 HTTP/1.1
 Host: as.example.com
 Authorization: Basic cnMwODpsb25nLXNlY3VyZS1yYW5kb20tc2VjcmV0
 Content-Type: application/x-www-form-urlencoded

 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
 &resource=https%3A%2F%2Fbackend.example.com%2Fapi
 &subject_token=accVkjcJyb4BWCxGsndESCJQbdFMogUC5PbRDqceLTC
 &subject_token_type=
  urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aaccess_token

図2: トークン交換要求

認可サーバーは、クライアント資格情報と、トークン交換要求で提示された subject_token を検証します。 resource パラメーターから、認可サーバーは要求に適用すべき適切なポリシーを決定でき、 <https://backend.example.com> での使用に適したトークンを発行します。図3に示される応答の access_token パラメーターには、新しいトークンが含まれます。このトークン自体は 1 分間有効なベアラー OAuth アクセストークンです。たまたまこのトークンは JWT ですが、その構造と形式はクライアントにとって不透明であるため、issued_token_type は、それがアクセストークンであることだけを示します。¶

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

 {
  "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjllciJ9.eyJhdWQiOiJo
    dHRwczovL2JhY2tlbmQuZXhhbXBsZS5jb20iLCJpc3MiOiJodHRwczovL2FzLmV
    4YW1wbGUuY29tIiwiZXhwIjoxNDQxOTE3NTkzLCJpYXQiOjE0NDE5MTc1MzMsIn
    N1YiI6ImJkY0BleGFtcGxlLmNvbSIsInNjb3BlIjoiYXBpIn0.40y3ZgQedw6rx
    f59WlwHDD9jryFOr0_Wh3CGozQBihNBgnXEQgU85AI9x3KmsPottVMLPIWvmDCM
    y5-kdXjwhw",
  "issued_token_type":
      "urn:ietf:params:oauth:token-type:access_token",
  "token_type":"Bearer",
  "expires_in":60
 }

図3: トークン交換応答

その後、リソースサーバーは、新たに取得したアクセストークンを使用して、図 4に示すようにバックエンドサーバーへ要求を行うことができます。¶

 GET /api HTTP/1.1
 Host: backend.example.com
 Authorization: Bearer eyJhbGciOiJFUzI1NiIsImtpZCI6IjllciJ9.eyJhdWQ
    iOiJodHRwczovL2JhY2tlbmQuZXhhbXBsZS5jb20iLCJpc3MiOiJodHRwczovL2
    FzLmV4YW1wbGUuY29tIiwiZXhwIjoxNDQxOTE3NTkzLCJpYXQiOjE0NDE5MTc1M
    zMsInN1YiI6ImJkY0BleGFtcGxlLmNvbSIsInNjb3BlIjoiYXBpIn0.40y3ZgQe
    dw6rxf59WlwHDD9jryFOr0_Wh3CGozQBihNBgnXEQgU85AI9x3KmsPottVMLPIW
    vmDCMy5-kdXjwhw

図4: バックエンドの保護リソース要求

追加の例は付録 A にあります。¶

4. JSON Web Token クレームとイントロスペクション応答パラメーター

トークン内で委任を表現する仕組み、および委任またはなりすましを行う認可を表現する仕組みが定義されていることは有用です。ここで説明するトークン交換プロトコルはどの種類のトークンでも使用できますが、この節では、特に JWT および OAuth 2.0 Token Introspection [RFC7662] 応答でそのようなセマンティクスを表現するクレームを定義します。他の種類のトークンについても同様の定義は可能ですが、この仕様の範囲外です。¶

iss、sub、 exp など、ここでは定義されていないものの例や説明で使用されるクレームは、 [JWT] で定義されていることに注意してください。¶

4.1. "act"（アクター）クレーム

act（アクター）クレームは、 JWT 内で委任が発生したことを表現し、権限を委任された行為者を識別する手段を提供します。act クレームの値は JSON オブジェクトであり、その JSON オブジェクトのメンバーはアクターを識別するクレームです。 act クレームを構成するクレームは、アクターを識別し、場合によってはアクターに関する追加情報を提供します。たとえば、 iss と sub の2つのクレームの組み合わせが、アクターを一意に識別するために必要となる場合があります。¶

ただし、act クレーム内のクレームはアクターのアイデンティティのみに関係し、トップレベルのクレームと同じように、包含する JWT の有効性には関係しません。したがって、アイデンティティ以外のクレーム（たとえば exp、nbf、 aud）は、 act クレーム内で使用しても意味がないため、使用しません。¶

図5は、JWT クレームセット内の act（アクター）クレームを示しています。トークン自体のクレームは user@example.com に関するものですが、act クレームは admin@example.com が現在のアクターであることを示します。¶

 {
   "aud":"https://consumer.example.com",
   "iss":"https://issuer.example.com",
   "exp":1443904177,
   "nbf":1443904077,
   "sub":"user@example.com",
   "act":
   {
     "sub":"admin@example.com"
   }
 }

図5: アクタークレーム

ある act クレームを別のクレーム内にネストすることで、委任チェーンを表現できます。最も外側の act クレームは現在のアクターを表し、ネストされた act クレームは以前のアクターを表します。最も古いアクターが最も深くネストされます。ネストされた act クレームは、最初の要求とサブジェクトから、現在のアクターに到達するまでに行われたさまざまな委任の段階をつなぐ履歴として機能します。この意味で、現在のアクターは認可／委任の履歴全体を含むものとみなされ、ここで説明するネスト構造に自然につながります。¶

アクセス制御ポリシーを適用する目的では、トークンの利用者は、トークンのトップレベルのクレームと、act クレームによって現在のアクターとして識別される当事者のみを考慮しなければなりません。ネストされた act クレームによって識別される以前のアクターは、情報提供のみを目的としており、アクセス制御の判断で考慮してはなりません。¶

図6の次の例は、 JWT クレームセット内にネストされた act（アクター）クレームを示しています。トークン自体のクレームは user@example.com に関するものですが、act クレームは、システム <https://service16.example.com> が現在のアクターであり、 <https://service77.example.com> が以前のアクターであったことを示します。このようなトークンは、service16 が service77 からの呼び出しでトークンを受信し、 service26 を呼び出すのに適したトークンと交換した結果として生成され、認可サーバーが新たに発行したトークン内にその状況を記録する場合があります。¶

 {
   "aud":"https://service26.example.com",
   "iss":"https://issuer.example.com",
   "exp":1443904100,
   "nbf":1443904000,
   "sub":"user@example.com",
   "act":
   {
     "sub":"https://service16.example.com",
     "act":
     {
       "sub":"https://service77.example.com"
     }
   }
 }

図6: ネストされたアクタークレーム

OAuth トークンイントロスペクション応答のトップレベルメンバーとして含まれる場合、 act は、同名のクレームと同じセマンティクスおよび形式を持ちます。¶

4.2. "scope"（スコープ）クレーム

scope クレームの値は、第 3.3節 of [RFC6749] で説明されている形式で、トークンに関連付けられたスコープを空白で区切ったリストを含む JSON 文字列です。¶

図7は、 JWT クレームセット内の scope クレームを示します。¶

 {
   "aud":"https://consumer.example.com",
   "iss":"https://issuer.example.com",
   "exp":1443904177,
   "nbf":1443904077,
   "sub":"dgaf4mvfs75Fci_FL3heQA",
   "scope":"email profile phone address"
 }

図7: スコープクレーム

OAuth 2.0 Token Introspection [RFC7662] はすでに、トークンに関連付けられたスコープを伝えるための scope パラメーターを定義しています。¶

4.3. "client_id"（クライアント識別子）クレーム

client_id クレームは、トークンを要求した OAuth 2.0 [RFC6749] クライアントのクライアント識別子を運びます。¶

図8の次の例は、JWT クレームセット内の client_id クレームを示し、識別子が "s6BhdRkqt3" である OAuth 2.0 クライアントを表しています。¶

 {
   "aud":"https://consumer.example.com",
   "iss":"https://issuer.example.com",
   "exp":1443904177,
   "sub":"user@example.com",
   "client_id":"s6BhdRkqt3"
 }

図8: クライアント識別子クレーム

OAuth 2.0 Token Introspection [RFC7662] はすでに、トークンを要求した OAuth 2.0 クライアントのクライアント識別子として client_id パラメーターを定義しています。¶

4.4. "may_act"（認可されたアクター）クレーム

may_act クレームは、ある当事者がアクターとなり、別の当事者に代わって行動することを認可されていることを表明します。このクレームは、たとえば subject_token がトークン交換要求でトークンエンドポイントに提示されたときに使用でき、サブジェクトトークン内の may_act クレームを認可サーバーが使用して、クライアント（または actor_token で識別される当事者）が、要求された委任またはなりすましを行うことを認可されているかどうかを判断できます。クレーム値は JSON オブジェクトであり、その JSON オブジェクトのメンバーは、クレームを含む JWT によって識別される当事者のために行動する資格があると表明された当事者を識別するクレームです。 may_act クレームを構成するクレームは、認可されたアクターを識別し、場合によっては追加情報を提供します。たとえば、iss と sub の2つのクレームの組み合わせが、認可されたアクターを一意に識別するために必要な場合があり、 email クレームは、その当事者に関する追加の有用な情報を提供するために使用できます。¶

ただし、may_act クレーム内のクレームは、その当事者のアイデンティティのみに関係し、トップレベルのクレームと同じように、包含する JWT の有効性には関係しません。したがって、exp、nbf、aud などのクレームは、may_act クレーム内で使用しても意味がないため、使用しません。¶

図9は、 JWT クレームセット内の may_act クレームを示します。トークン自体のクレームは user@example.com に関するものですが、may_act クレームは、 admin@example.com が user@example.com に代わって行動することを認可されていることを示します。¶

 {
   "aud":"https://consumer.example.com",
   "iss":"https://issuer.example.com",
   "exp":1443904177,
   "nbf":1443904077,
   "sub":"user@example.com",
   "may_act":
   {
     "sub":"admin@example.com"
   }
 }

図9: 認可されたアクタークレーム

OAuth トークンイントロスペクション応答のトップレベルメンバーとして含まれる場合、 may_act は同名のクレームと同じセマンティクスおよび形式を持ちます。¶

付録 A. 追加のトークン交換例

次の各節では、なりすましと委任をそれぞれ示す 2つのトークン交換例を示します（余分な改行とインデントは表示目的のみです）。¶

A.1. なりすましトークン交換の例

A.1.1. トークン交換要求

次のトークン交換要求では、クライアントはなりすましのセマンティクスを持つトークンを要求しています（subject_token のみで actor_token がない場合、委任は不可能です）。クライアントは認可サーバーに、論理名 urn:example:cooperation-context を持つ対象サービスで使用するトークンが必要であることを伝えます。¶

 POST /as/token.oauth2 HTTP/1.1
 Host: as.example.com
 Content-Type: application/x-www-form-urlencoded

 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
 &audience=urn%3Aexample%3Acooperation-context
 &subject_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwc
   zovL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXI
   uZXhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTA2MDAsIm5iZiI6MTQ0MTkwOTAwMCwic
   3ViIjoiYmRjQGV4YW1wbGUubmV0Iiwic2NvcGUiOiJvcmRlcnMgcHJvZmlsZSBoaXN
   0b3J5In0.PRBg-jXn4cJuj1gmYXFiGkZzRuzbXZ_sDxdE98ddW44ufsbWLKd3JJ1VZ
   hF64pbTtfjy4VXFVBDaQpKjn5JzAw
 &subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt

図10: トークン交換要求

A.1.2. サブジェクトトークンのクレーム

前の要求の subject_token は JWT であり、デコードされた JWT クレームセットをここに示します。この JWT は、特定の時間範囲内に認可サーバーによって処理されることを意図しています。 JWT のサブジェクト（bdc@example.net）は、新しいトークンが代わりに要求される当事者です。¶

  {
    "aud":"https://as.example.com",
    "iss":"https://original-issuer.example.net",
    "exp":1441910600,
    "nbf":1441909000,
    "sub":"bdc@example.net",
    "scope":"orders profile history"
  }

図11: サブジェクトトークンのクレーム

A.1.3. トークン交換応答

下に示すトークン交換応答の access_token パラメーターには、クライアントが要求した新しいトークンが含まれています。応答のその他のパラメーターは、そのトークンが 1時間で期限切れになるベアラーアクセストークンであることを示しています。¶

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

 {
  "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjcyIn0.eyJhdWQiOiJ1cm4
    6ZXhhbXBsZTpjb29wZXJhdGlvbi1jb250ZXh0IiwiaXNzIjoiaHR0cHM6Ly9hcy5l
    eGFtcGxlLmNvbSIsImV4cCI6MTQ0MTkxMzYxMCwic3ViIjoiYmRjQGV4YW1wbGUub
    mV0Iiwic2NvcGUiOiJvcmRlcnMgcHJvZmlsZSBoaXN0b3J5In0.rMdWpSGNACTvnF
    uOL74sYZ6MVuld2Z2WkGLmQeR9ztj6w2OXraQlkJmGjyiCq24kcB7AI2VqVxl3wSW
    nVKh85A",
  "issued_token_type":
    "urn:ietf:params:oauth:token-type:access_token",
  "token_type":"Bearer",
  "expires_in":3600
 }

図12: トークン交換応答

A.1.4. 発行済みトークンのクレーム

発行されたトークンのデコード済み JWT クレームセットを下に示します。新しい JWT は認可サーバーによって発行され、論理名 urn:example:cooperation-context で知られるシステムエンティティによって、有効期限より前の任意の時点で処理されることを意図しています。 JWT のサブジェクト（sub）は、要求に使用されたトークンのサブジェクトと同じであり、これによりクライアントは、トークンを使用することで、論理名 urn:example:cooperation-context で知られるシステムエンティティに対して、そのサブジェクトになりすますことが実質的に可能になります。¶

  {
    "aud":"urn:example:cooperation-context",
    "iss":"https://as.example.com",
    "exp":1441913610,
    "sub":"bdc@example.net",
    "scope":"orders profile history"
  }

図13: 発行済みトークンのクレーム

A.2. 委任トークン交換の例

A.2.1. トークン交換要求

次のトークン交換要求では、クライアントはトークンを要求し、 subject_token と actor_token の両方を提供しています。クライアントは認可サーバーに、論理名 urn:example:cooperation-context を持つ対象サービスで使用するトークンが必要であることを伝えます。認可サーバーのポリシーにより、発行されるトークンは複合トークンとなります。¶

 POST /as/token.oauth2 HTTP/1.1
 Host: as.example.com
 Content-Type: application/x-www-form-urlencoded

 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
 &audience=urn%3Aexample%3Acooperation-context
 &subject_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwc
   zovL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXI
   uZXhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTAwNjAsInNjb3BlIjoic3RhdHVzIGZlZ
   WQiLCJzdWIiOiJ1c2VyQGV4YW1wbGUubmV0IiwibWF5X2FjdCI6eyJzdWIiOiJhZG1
   pbkBleGFtcGxlLm5ldCJ9fQ.4rPRSWihQbpMIgAmAoqaJojAxj-p2X8_fAtAGTXrvM
   xU-eEZHnXqY0_AOZgLdxw5DyLzua8H_I10MCcckF-Q_g
 &subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt
 &actor_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJhdWQiOiJodHRwczo
   vL2FzLmV4YW1wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9vcmlnaW5hbC1pc3N1ZXIuZ
   XhhbXBsZS5uZXQiLCJleHAiOjE0NDE5MTAwNjAsInN1YiI6ImFkbWluQGV4YW1wbGU
   ubmV0In0.7YQ-3zPfhUvzje5oqw8COCvN5uP6NsKik9CVV6cAOf4QKgM-tKfiOwcgZ
   oUuDL2tEs6tqPlcBlMjiSzEjm3yBg
 &actor_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt

図14: トークン交換要求

A.2.2. サブジェクトトークンのクレーム

前の要求の subject_token は JWT であり、デコードされた JWT クレームセットをここに示します。この JWT は、特定の有効期限より前に認可サーバーによって処理されることを意図しています。 JWT のサブジェクト（user@example.net）は、新しいトークンが代わりに要求される当事者です。¶

  {
    "aud":"https://as.example.com",
    "iss":"https://original-issuer.example.net",
    "exp":1441910060,
    "scope":"status feed",
    "sub":"user@example.net",
    "may_act":
    {
      "sub":"admin@example.net"
    }
  }

図15: サブジェクトトークンのクレーム

A.2.3. アクタートークンのクレーム

前の要求の actor_token は JWT であり、デコードされた JWT クレームセットをここに示します。この JWT も、特定の有効期限より前に認可サーバーによって処理されることを意図しています。 JWT のサブジェクト（admin@example.net）は、要求されているセキュリティトークンを行使するアクターです。¶

  {
    "aud":"https://as.example.com",
    "iss":"https://original-issuer.example.net",
    "exp":1441910060,
    "sub":"admin@example.net"
  }

図16: アクタートークンのクレーム

A.2.4. トークン交換応答

下に示すトークン交換応答の access_token パラメーターには、クライアントが要求した新しいトークンが含まれています。応答のその他のパラメーターは、そのトークンが 1時間で期限切れになる JWT であり、発行されたトークンがアクセストークンではないため、アクセストークンタイプが適用されないことを示しています。¶

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

 {
  "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjcyIn0.eyJhdWQiOiJ1cm4
    6ZXhhbXBsZTpjb29wZXJhdGlvbi1jb250ZXh0IiwiaXNzIjoiaHR0cHM6Ly9hcy5l
    eGFtcGxlLmNvbSIsImV4cCI6MTQ0MTkxMzYxMCwic2NvcGUiOiJzdGF0dXMgZmVlZ
    CIsInN1YiI6InVzZXJAZXhhbXBsZS5uZXQiLCJhY3QiOnsic3ViIjoiYWRtaW5AZX
    hhbXBsZS5uZXQifX0.3paKl9UySKYB5ng6_cUtQ2qlO8Rc_y7Mea7IwEXTcYbNdwG
    9-G1EKCFe5fW3H0hwX-MSZ49Wpcb1SiAZaOQBtw",
  "issued_token_type":"urn:ietf:params:oauth:token-type:jwt",
  "token_type":"N_A",
  "expires_in":3600
 }

図17: トークン交換応答

A.2.5. 発行済みトークンのクレーム

発行されたトークンのデコード済み JWT クレームセットを下に示します。新しい JWT は認可サーバーによって発行され、論理名 urn:example:cooperation-context で知られるシステムエンティティによって、有効期限より前の任意の時点で処理されることを意図しています。 JWT のサブジェクト（sub）は、要求に使用された subject_token のサブジェクトと同じです。 JWT のアクター（act）は、要求に使用された actor_token のサブジェクトと同じです。これは委任を示し、 admin@example.net を、user@example.net に代わって行動する権限を委任された現在のアクターとして識別します。¶

  {
    "aud":"urn:example:cooperation-context",
    "iss":"https://as.example.com",
    "exp":1441913610,
    "scope":"status feed",
    "sub":"user@example.net",
    "act":
    {
      "sub":"admin@example.net"
    }
  }

図18: 発行済みトークンのクレーム