Grant Management for OAuth 2.0

はじめに

Grant Management for OAuth 2.0（グラント管理）は、クライアントアプリケーションに付与された権限を管理するための技術仕様で、既存の標準仕様よりも細かい粒度での管理を可能にします。

英国オープンバンキング、オーストラリア消費者データ権、ブラジルオープンバンキング 等のエコシステムで採用され、高度 API セキュリティのデファクトスタンダードとなった Financial-grade API 1.0、その後継仕様である Financial-grade API 2.0 の一部と位置付けられていることが、この仕様に注目すべき理由となっています。また、グラント管理仕様は、インターネット上に世界規模の高信頼性デジタルアイデンティティネットワークを構築するためのプロジェクトである GAIN (Global Assured Identity Network) のホワイトペーパーでも言及されています。

本記事は Authlete 社のウェブサイト上で公開されている『グラント管理（Grant Management for OAuth 2.0）』の仕様説明部分の要約です。当仕様の実装詳細にご興味のある方は Authlete 社の記事を参照してください。

グラントの概念

OAuth 2.0 では、ユーザーはクライアントアプリケーションに権限を与えます。結果として、認可サーバーからクライアントアプリケーションにアクセストークンが発行されます。

アクセストークン発行処理は繰り返されるかもしれません。二番目以降の処理でクライアントが要求する権限は最初の処理で要求されたものとは異なるかもしれません。このようにして、クライアントアプリケーションに与えられる権限は累積していきます。

グラント管理仕様では累積した権限をグラントと呼び、グラントに関する問い合わせ、グラントの累積および失効の手段を定義します。

リクエストパラメーター／レスポンスパラメーター

グラントを管理するため、各グラントにはグラント ID が割り当てられます。グラント ID はアクセストークンとともにトークンエンドポイントから発行されます。認可サーバーにグラント ID の発行を要求するには、新しい認可リクエストパラメーターである grant_management_action に create という値を指定し、認可リクエストに含めます。発行されたグラント ID は、新しいトークンレスポンスパラメーターである grant_id の値としてトークンレスポンスに含まれます。

権限を累積させるには、続く認可リクエストに grant_management_action=merge および新しい認可リクエストパラメーター grant_id を含めます。grant_id の値には発行済みのグラント ID を指定します。

FAPI PR 344 により、update は merge へと名称変更されました。この変更は Grant Management for OAuth 2.0 の実装者向け草稿第二版から有効になります。

create と merge に加え、grant_management_action リクエストパラメーターの値として replace も定義されています。replace アクションは、指定したグラント ID に紐付く権限を、grant_management_action=replace を含むリクエストで付与された権限だけで置き換えます。以前の権限は取り消されます。

grant_management_action リクエストパラメーターの値が merge または replace の場合、grant_id リクエストパラメーターは必須です。

グラント管理エンドポイント

グラント管理仕様では、グラント管理エンドポイントと呼ばれる新しいエンドポイントを定義しています。このエンドポイントにより、グラントに関する問い合わせとグラントの失効が可能となります。エンドポイントにアクセスするには、事前に発行されたアクセストークンが必要となります。

問い合わせ

問い合わせ
リクエスト	HTTP メソッド	GET
	URL	{エンドポイント}/{グラントID}
	保護	grant_management_query スコープを持つアクセストークン
レスポンス	ステータスコード	200 OK
	Content-Type	application/json
	フォーマット	"6.4. Query Status of a Grant" 参照

次のものは、グラント管理仕様の　"6.4. Query Status of a Grant" から抜粋したレスポンス例です。

レスポンスボディーの JSON はグラントの権限を示しています。トップレベルのプロパティーとして "scopes", "claims", "authorization_details" が含まれています。

scopes

"scopes" の値は、スコープとリソースの（以降スコープリソースクラスター）の配列です。各クラスターは "scope" と "resource" で構成されます。"scope" の値は空白区切りで並べたスコープ群です。"resource" の値はリソースの配列です。スコープ群とリソース群の値は scope リクエストパラメーター（RFC 6749 / Section 3.3）と resource リクエストパラメーター（RFC 8707 / Section 2）で指定されたものです。

"scopes" の構造から、merge 操作の繰り返しにより権限が累積してもスコープリソースクラスター群は分けて管理すべきということに実装者は気が付きます。もしも merge 操作でクラスター群の内容が混ざってしまうと、スコープ群が意図しないリソース群と組み合わされてしまうかもしれません。下図内の右下の JSON は、クラスター群の内容を混ぜてしまうと change スコープが https://payment.example.com リソースに関連付けられてしまうことを示しており、これは、金銭の窃取などの重大なセキュリティ事件を引き起こしかねません。

claims

"claims" の値は、ユーザーがクライアントアプリケーションに知ることを許可した「クレーム」の配列です。簡単に言うと、ここでの「クレーム」とはユーザーの属性のことです。family_name や phone_number などのユーザー属性のいくつかは、OpenID Connect Core 1.0 の Section 5.1 で標準クレームとして定義されています。

クライアントアプリケーションは、特別なスコープ（profile、email、address、phone）を scope リクエストパラメーターに含めることにより（OIDC Core / Section 5.4）、または claims リクエストパラメーターを使うことにより（OIDC Core / Section 5.5）、クレームを要求することができます。

authorization_details

"authorization_details" の値は認可に関する詳細情報の配列です。それらの情報は、"OAuth 2.0 Rich Authorization Requests"（RAR）で定義される authorization_details リクエストパラメーターで指定されたものです。

RAR が開発される前は、認可リクエストに詳細情報を含めるために認可サーバーは非標準リクエストパラメーターを導入するか、または scope リクエストパラメーターを非標準の方法で利用しなければなりませんでした。後者の方法は「parameterized scope」や「dynamic scope」と呼ばれ、動的な値をスコープ文字列に埋め込みます。例えば、Open Banking Brasil Financial-grade API Security Profile 1.0 は「動的同意スコープ」（Section 7.1.2）を定義しています。そのフォーマットは consent:{ConsentID} となっており、consent: が固定文字列のプレフィックス、{ConsentID} が動的部分です（例: consent:urn:bancoex:C1DD33123）。

動的スコープの問題は、標準化されていないこと、および、それ自身に起因する特性として書式が多岐に渡ることにより、実装間の互換性に全く期待できないことです。RAR はその問題を解決するために開発され、Financial-grade API 2.0 の一部として位置付けられています。

失効

失効
リクエスト	HTTP メソッド	DELETE
	URL	{エンドポイント}/{グラントID}
	保護	grant_management_revoke スコープを持つアクセストークン
レスポンス	ステータスコード	204 No Content

グラント管理仕様は、失効するグラントに紐付く全てのリフレッシュトークンも失効しなければならず（MUST）、アクセストークンも失効すべき（SHOULD）と述べています。

アクセストークンとリフレッシュトークンの実装は、認可サーバーの実装間で異なります。特に、PKI の CRL（Certificate Revocation List）または OCSP（Online Certificate Status Protocol）相当の仕組みを運用しない限り、JWT アクセストークンをはじめとする内包型アクセストークンは失効できないことに注意してください。詳細は『OAuth アクセストークンの実装に関する考察』を参照してください。

サーバーメタデータ

グラント管理仕様は次のサーバーメタデータを追加します。

メタデータ	説明
grant_management_actions_supported	認可サーバーがサポートするグラント管理アクション群。取りうる値は create, query replace, revoke および merge.
grant_management_endpoint	グラント管理エンドポイントの URL
grant_management_action_required	grant_management_action リクエストパラメーターが常に要求されるかどうかを示す真偽値

セキュリティ上の理由により、グラント管理はコンフィデンシャルクライアントのみしか利用できないので（"grant management is restricted to confidential only clients due to security reasons"（Section 5.1））、ディスカバリー文書（OIDC Discovery）が "grant_management_action_required":true を含んでいる場合、それは当認可サーバーの認可エンドポイントがパブリッククライアントからのリクエストを全て拒絶することを示唆しています。

さいごに

Grant Management for OAuth 2.0 は Authlete 2.3 以降でサポートされます。現時点では、当バージョンは共有サーバー（api.authlete.com）にデプロイされていません。Authlete 2.3 へのアーリーアクセスをご希望の場合はお問い合わせください。