RFC 8693: OAuth 2.0 トークン交換

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

概要

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

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

Security Token Service (STS) は、提供されたセキュリティトークンを検証し、それに応答して新しいセキュリティトークンを発行できるサービスであり、これによりクライアントは、異種環境またはセキュリティドメインをまたいだリソースに対する適切なアクセス資格情報を取得できる。 Web Service クライアントは、トークン交換のために 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 の相互作用では、リソース所有者認可の何らかの表現をアクセストークンと交換するが、これは実際に非常に有用なパターンであることが証明されている。しかし、その入力と出力は、そのままではセキュリティトークン交換フレームワークを完全に収容するにはやや制約が強すぎる。¶

本仕様は、STS の役割を担う認可サーバーからクライアントがセキュリティトークンを要求し取得できるようにする、 OAuth 2.0 を拡張するプロトコルを定義する。 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 の一般的なユースケースの 1 つ (前のセクションで示唆したように) は、リソースサーバー A が、要求ユーザー B の代理としてバックエンドサービス C を呼び出せるようにすることである。ローカルサイトポリシーおよび認可インフラストラクチャに応じて、A が B の代理として動作していることを何らかの形で示す注釈とともに、自身の資格情報を用いて C にアクセスすること ("委任")、または A に C への限定されたアクセス資格情報を付与するが、それが引き続き B を認可されたエンティティとして識別すること ("なりすまし") が望ましい場合がある。委任となりすましは、複数の参加者が関わる他のシナリオでも有用な概念となり得る。¶

プリンシパル A がプリンシパル B になりすます場合、A は定義された権利コンテキストの範囲内で B が持つすべての権利を与えられ、そのコンテキストでは B と区別できない。したがって、プリンシパル A がプリンシパル B になりすます場合、そのようなトークンを受け取るエンティティに関する限り、それらは実際には B とやり取りしていることになる。アイデンティティシステムの一部の構成員が、なりすましが行われていることを認識している可能性はあるが、それは要件ではない。あらゆる意図と目的において、A が B になりすましている場合、A はトークンによって認可された権利のコンテキスト内では B である。A が B になりすます能力は、トークンの内容または帯域外メカニズムによって、スコープまたは時間、さらには 1 回限りの使用制限に限定されることがある。¶

委任セマンティクスは、なりすましセマンティクスとは異なるが、両者は密接に関連している。委任セマンティクスでは、プリンシパル A は B とは別個の自身のアイデンティティを引き続き持ち、B がその権利の一部を A に委任した可能性はあるものの、行われるあらゆるアクションは、B を代表する A によって行われていることが明示的に理解される。ある意味で、A は B のエージェントである。¶

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

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

複合トークンを表現する具体的な方法、さらにはそのようなトークンが発行されるかどうかは、実装の詳細とトークンの種類に依存する。JWT ではない複合トークンの表現は、本仕様の範囲外である。ただし、actor_token リクエストパラメーターは、望まれるアクターに関する情報を提供する手段を提供し、JWT の act クレームは委任の連鎖の表現を提供できる。¶

1.2. 要件表記および規約

本文書におけるキーワード "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", および "OPTIONAL" は、ここに示すようにすべて大文字で現れる場合に限り、 BCP 14 [RFC2119] [RFC8174] に記述されるとおりに解釈される。¶

1.3. 用語

本仕様は、OAuth 2.0 [RFC6749] で定義される "access token type", "authorization server", "client", "client identifier", "resource server", "token endpoint", "token request", および "token response" という用語、ならびに JSON Web Token (JWT) [JWT] で定義される "Base64url Encoding", "Claim", および "JWT Claims Set" という用語を使用する。¶

2. トークン交換リクエストおよびレスポンス

2.1. リクエスト

クライアントは、[RFC6749] のセクション 4.5 で定義される拡張グラントタイプメカニズムを用いて、認可サーバーのトークンエンドポイントへトークンリクエストを行うことにより、セキュリティトークンを要求する。¶

認可サーバーに対するクライアント認証は、OAuth 2.0 によって提供される通常のメカニズムを用いて行われる。 [RFC6749] のセクション 2.3.1 はクライアントのパスワードベース認証を定義しているが、クライアント認証は拡張可能であり、他のメカニズムも可能である。たとえば、[RFC7523] は bearer JSON Web Tokens (JWTs) [JWT] を用いたクライアント認証を定義している。サポートされるクライアント認証方法、および認証されていない、または識別されていないクライアントを許可するかどうかは、認可サーバーの裁量による展開上の決定である。クライアント認証を省略すると、侵害されたトークンを所有する誰でも、そのトークンを STS 経由で他のトークンへ活用できることに注意されたい。したがって、クライアント認証により、他のエンティティになりすます、または他のエンティティから委任を受けることが許可されるエンティティに関して、 STS による追加の認可チェックが可能となる。¶

クライアントは、HTTP POST メソッドを使用し、拡張グラントタイプを伴ってトークンエンドポイントへトークン交換リクエストを行う。以下のパラメーターは、[RFC6749] の付録 B に記述されるとおり、UTF-8 の文字エンコーディングを用いた application/x-www-form-urlencoded 形式で HTTP リクエスト entity-body に含められる。¶

grant_type: REQUIRED. 値 urn:ietf:params:oauth:grant-type:token-exchange は、トークン交換が実行されていることを示す。¶
resource: OPTIONAL. クライアントが要求されたセキュリティトークンを使用しようとする対象サービスまたはリソースを示す URI。これにより、認可サーバーは、発行されるトークンの種別と内容を決定したり、トークンを暗号化するかどうか、およびどのように暗号化するかを決定したりするなど、対象に応じて適切なポリシーを適用できる。多くの場合、クライアントは相互作用するシステムの論理的構成を知らず、トークンを使用しようとするサービスの URI だけを知っている。 resource パラメーターにより、クライアントは、発行されたトークンを使用しようとする場所を認可サーバーに示すことができる。これは通常、https URL として、トークン交換リクエスト内でそのリソースにアクセスする際に使用されるのと同じ形式で場所を提供することによって行われる。認可サーバーは通常、リソース URI 値から適切なポリシーへマッピングする能力を持つ。resource パラメーターの値は、 [RFC3986] のセクション 4.3 で指定される絶対 URI でなければならず (MUST)、クエリコンポーネントを含んでもよい (MAY) が、フラグメントコンポーネントを含んではならない (MUST NOT)。発行されたトークンが列挙された複数のリソースで使用されることを示すために、複数の resource パラメーターを使用できる。 resource パラメーターの追加の背景および使用法については [OAUTH-RESOURCE] を参照されたい。¶
audience: OPTIONAL. クライアントが要求されたセキュリティトークンを使用しようとする対象サービスの論理名。これは resource パラメーターと同様の目的を果たすが、クライアントが対象サービスの論理名を提供する点が異なる。その名前の解釈には、値がクライアントと認可サーバーの双方に理解されるものである必要がある。 OAuth クライアント識別子、SAML エンティティ識別子 [OASIS.saml-core-2.0-os]、および OpenID Connect Issuer Identifier [OpenID.Core] は、 audience パラメーター値として使用され得るものの例である。ただし、特定の認可サーバーで使用される audience 値は、意図された値の種別として適切に解釈されることを保証するために、そのサーバー内で一意でなければならない。発行されたトークンが列挙された複数の audience で使用されることを示すために、複数の audience パラメーターを使用できる。 audience および resource パラメーターは、論理名とリソース URI が混在する複数の対象サービスを示すために併用できる。¶
scope: OPTIONAL. [RFC6749] のセクション 3.3 で定義される、スペース区切りで大文字小文字を区別する文字列のリストであり、クライアントが、トークンが使用されるサービスまたはリソースの文脈において、要求するセキュリティトークンの望ましいスコープを指定できるようにする。スコープの値と関連するセマンティクスはサービス固有であり、関連するサービスドキュメントに記述されることが期待される。¶
requested_token_type: OPTIONAL. セクション 3 に記述される、要求されたセキュリティトークンの種別の識別子。要求される種別が指定されていない場合、発行されるトークン種別は認可サーバーの裁量によるものであり、 resource または audience パラメーターによって示されるサービスまたはリソースの要件に関する知識によって決定されることがある。¶
subject_token: REQUIRED. リクエストが行われる相手方の代理となる当事者のアイデンティティを表すセキュリティトークン。通常、このトークンの subject は、リクエストへの応答として発行されるセキュリティトークンの subject となる。¶
subject_token_type: REQUIRED. セクション 3 に記述される識別子であり、 subject_token パラメーター内のセキュリティトークンの種別を示す。¶
actor_token: OPTIONAL. 動作する当事者のアイデンティティを表すセキュリティトークン。通常、これは要求されたセキュリティトークンを使用し、subject の代理として動作することを認可された当事者である。¶
actor_token_type: セクション 3 に記述される識別子であり、 actor_token パラメーター内のセキュリティトークンの種別を示す。これは、リクエストに actor_token パラメーターが存在する場合に REQUIRED であるが、それ以外の場合は含めてはならない (MUST NOT)。¶

リクエストの処理において、認可サーバーは、示されたトークン種別に対して適切な検証手続きを実行しなければならず (MUST)、 actor token が存在する場合には、その示されたトークン種別に対しても適切な検証手続きを実行しなければならない。特定のトークンの有効性基準および詳細は、本文書の範囲外であり、それぞれのトークン種別およびその内容に固有である。¶

1 回限りの使用またはトークン種別に固有のその他のセマンティクスがない場合、トークン交換を実行する行為は、subject token または actor token の有効性に影響を与えない。さらに、交換は 1 回限りのイベントであり、入力トークンと出力トークンの間に密接なリンクを作成しない。そのため、たとえば出力トークンの有効期限が入力トークンの有効期限の影響を受けることはあっても、入力トークンの更新または延長が出力トークンのプロパティに反映されることは期待されない。トークン失効イベントを伝播することが適切または望ましい場合は依然としてあり得る。しかし、それは STS プロトコルの一般的な性質ではなく、特定の実装、トークン種別、または展開に固有のものとなる。¶

2.1.1. Resource、Audience、Scope の関係

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

認可サーバーは、任意のトークンリクエストを満たすことを望まない、または満たせない場合があるが、非常に広範なアクセス権が求められている場合には、満たせないリクエストとなる可能性が大幅に高くなる。そのため、展開におけるシステム間の関係に関する具体的な知識がない場合、クライアントは要求するアクセスの広さ、特に対象サービスの数に慎重であるべきである。認可サーバーは、クライアントが同時に過度に多くの対象サービスへのアクセスを要求したことを通知するために、セクション 2.2.2 で定義される invalid_target エラーコードを使用できる。¶

2.2. レスポンス

認可サーバーは、[RFC6749] のセクション 5 で指定されるとおり、トークンエンドポイントからの通常の OAuth 2.0 レスポンスでトークン交換リクエストに応答する。追加の詳細および説明は、以下のサブセクションで提供される。¶

2.2.1. 成功レスポンス

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

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

2.2.2. エラーレスポンス

リクエスト自体が有効でない場合、または subject_token または actor_token のいずれかが何らかの理由で無効であるか、ポリシーに基づいて受け入れ不能である場合、認可サーバーは、 [RFC6749] のセクション 5.2 で指定されるエラーレスポンスを構築しなければならない (MUST)。 error パラメーターの値は、 invalid_request エラーコードでなければならない (MUST)。¶

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

認可サーバーは、[RFC6749] のセクション 5.2 で説明されるように、 error_description を使用して、エラーの理由に関する追加情報を含めてもよい (MAY)。¶

他のエラーコードも、適切に使用してよい。¶

2.3. トークン交換の例

以下の例は、OAuth リソースサーバーが交換中にクライアントの役割を担う仮想的なトークン交換を示す。リソースサーバーは、保護リソースリクエストで受け取ったアクセストークンを、バックエンドサービスを呼び出すために使用する新しいトークンと交換する (例における余分な改行およびインデントは表示目的のみである)。¶

図 1 は、[RFC6750] のセクション 2.1 で指定されるとおり、 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 分間有効な bearer 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_Wh3CGozQBihNBhnXEQgU85AI9x3KmsPottVMLPIWvmDCM
    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_Wh3CGozQBihNBhnXEQgU85AI9x3KmsPottVMLPIW
    vmDCMy5-kdXjwhw

図 4: バックエンド保護リソースリクエスト

追加の例は付録 A にある。¶

4. JSON Web Token クレームおよびイントロスペクションレスポンスパラメーター

トークン内で委任を表現するため、また委任またはなりすましの認可を表現するための定義済みメカニズムを持つことは有用である。ここで記述されるトークン交換プロトコルは任意の種類のトークンとともに使用できるが、このセクションでは、 JWT および OAuth 2.0 Token Introspection [RFC7662] レスポンスにおいて、そのようなセマンティクスを具体的に表現するためのクレームを定義する。他の種類のトークンに対する同様の定義も可能であるが、本仕様の範囲外である。¶

ここで確立されていないが、例および説明で使用される iss, sub, exp などのクレームは、[JWT] によって定義されることに注意されたい。¶

4.1. "act" (Actor) クレーム

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

しかし、act クレーム内のクレームは actor のアイデンティティにのみ関係し、トップレベルのクレームと同じ方法で、それを含む JWT の有効性には関係しない。したがって、非アイデンティティクレーム (例: exp, nbf, および aud) は act クレーム内で使用されても意味がないため、使用されない。¶

図 5 は、JWT Claims Set 内の act (actor) クレームを示す。トークン自体のクレームは user@example.com に関するものであり、act クレームは admin@example.com が現在の actor であることを示す。¶

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

図 5: Actor クレーム

ある act クレームを別の act クレーム内にネストすることにより、委任の連鎖を表現できる。最も外側の act クレームは現在の actor を表し、ネストされた act クレームは以前の actor を表す。最も古い actor は最も深くネストされる。ネストされた act クレームは、最初のリクエストおよび subject から、現在の actor に到達する前に行われたさまざまな委任ステップまでを接続する履歴の痕跡として機能する。この意味で、現在の actor は、ここで記述するネスト構造へ自然につながる全体の認可/委任履歴を含むものと見なされる。¶

アクセス制御ポリシーを適用する目的では、トークンの消費者は、トークンのトップレベルクレームと、act クレームによって現在の actor として識別される当事者のみを考慮しなければならない (MUST)。ネストされた act クレームによって識別される以前の actor は情報提供のみであり、アクセス制御決定で考慮されてはならない。¶

図 6 の以下の例は、JWT Claims Set 内のネストされた act (actor) クレームを示す。トークン自体のクレームは user@example.com に関するものであり、act クレームは、システム <https://service16.example.com> が現在の actor であり、 <https://service77.example.com> が以前の actor であったことを示す。このようなトークンは、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: ネストされた Actor クレーム

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

4.2. "scope" (Scopes) クレーム

scope クレームの値は、 [RFC6749] のセクション 3.3 に記述される形式で、トークンに関連付けられたスコープのスペース区切りリストを含む JSON 文字列である。¶

図 7 は、 JWT Claims Set 内の scope クレームを示す。¶

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

図 7: Scopes クレーム

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

4.3. "client_id" (Client Identifier) クレーム

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

図 8 の以下の例は、JWT Claims Set 内の 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: Client Identifier クレーム

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

4.4. "may_act" (Authorized Actor) クレーム

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

しかし、may_act クレーム内のクレームはその当事者のアイデンティティにのみ関係し、トップレベルクレームと同じ方法で、それを含む JWT の有効性には関係しない。したがって、exp, nbf, および aud のようなクレームは、may_act クレーム内で使用されても意味がないため、使用されない。¶

図 9 は、 JWT Claims Set 内の 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: Authorized Actor クレーム

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 クレーム

前のリクエストの subject_token は JWT であり、デコードされた JWT Claims Set がここに示されている。JWT は特定の時間枠内で認可サーバーによって消費されることを意図している。 JWT の subject (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: Subject Token クレーム

A.1.3. トークン交換レスポンス

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

 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 Claims Set を以下に示す。新しい JWT は認可サーバーによって発行され、論理名 urn:example:cooperation-context で知られるシステムエンティティによって、その有効期限前であればいつでも消費されることを意図している。 JWT の subject (sub) は、リクエストを行うために使用されたトークンの subject と同じであり、これにより、クライアントはトークンを使用することにより、 urn:example:cooperation-context の論理名で知られるシステムエンティティにおいて、その subject になりすますことが事実上可能になる。¶

  {
    "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 クレーム

前のリクエストの subject_token は JWT であり、デコードされた JWT Claims Set がここに示されている。JWT は特定の有効期限前に認可サーバーによって消費されることを意図している。 JWT の subject (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: Subject Token クレーム

A.2.3. Actor Token クレーム

前のリクエストの actor_token は JWT であり、デコードされた JWT Claims Set がここに示されている。この JWT もまた、特定の有効期限前に認可サーバーによって消費されることを意図している。 JWT の subject (admin@example.net) は、要求されているセキュリティトークンを行使する actor である。¶

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

図 16: Actor Token クレーム

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 Claims Set を以下に示す。新しい JWT は認可サーバーによって発行され、論理名 urn:example:cooperation-context で知られるシステムエンティティによって、その有効期限前であればいつでも消費されることを意図している。 JWT の subject (sub) は、リクエストを行うために使用された subject_token の subject と同じである。 JWT の actor (act) は、リクエストを行うために使用された actor_token の subject と同じである。これは委任を示し、 admin@example.net を、user@example.net の代理として動作する権限が委任された現在の actor として識別する。¶

  {
    "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: 発行されたトークンのクレーム