はじめに

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

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

この記事は 2021 年 9 月にリリースされた実装者向けドラフト初版 (アナウンス) をもとに仕様の説明をおこないます。しかしながら、他と同様、初版ドラフトは完璧ではありません。遅かれ早かれ実装者が必要とするであろう技術詳細が欠けており、異なる解釈を招く余地があります。しかし、初版ドラフトの目的が実装者に作業開始を促すことにある点を考慮すれば、不完全なことはむしろ自然とも言えます。

実装者からのフィードバックとして仕様改善に資することを期待し、本記事では仕様自体の説明に加えて Authlete が仕様をどのように解釈し実装したのかについても説明します。

仕様

グラントの概念

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

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

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

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

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

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

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

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

grant_management_action および grant_id リクエストパラメーターについて、仕様は次のように述べています。

These parameters can be used with any request serving as authorization request, e.g. it may be used with CIBA requests.

(これらのパラメーターは、認可リクエストとして動作するものであればどんなリクエストでも使えます。例えば CIBA リクエストで使ってもかまいません。)

具体的には、仕様ではバックチャネル認証エンドポイント (CIBA Core / Section 7) がこれらのパラメーターを認識することを期待しています。

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

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

問い合わせ

次のものは、グラント管理仕様の　“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 の一部として位置付けられています。

失効

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

サーバーメタデータ

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

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

実装

意思決定すべき事項

絶対的な答えを持たない多くの選択に実装者は直面することになるので、グラント管理仕様の実装はお互いかなり異なるものになるでしょう。下記はそのような選択の例です。

1. グラントのライフサイクルは、グラントを構成する要素と独立して管理すべきか、それとも要素に完全に依存するべきか。

2. 明示的なグラント管理アクション (grant_management_action を伴う認可リクエストおよびグラント管理エンドポイントへの失効リクエスト) を実行することなくグラントの内容は変化しうるのか、それとも明示的なアクションがなければ変化しないのか。

3. アクセストークンとリフレッシュトークンの権限は、紐付けられたグラントの内容が変化するのに伴って変化するのか、それとも発行後は変化しないのか。

4. リフレッシュトークンをどのようにグラントに紐付けるか。グラント失効時に関連するリフレッシュトークンも失効させなければならないのので、紐付けが必要。

5. グラント失効時、アクセストークンも失効させるかどうか。仕様ではアクセストークンも失効させるべきとしている。認可サーバーの実装によっては、発行後にアクセストークンを失効させることはできないことに注意。(参考: OAuth アクセストークンの実装に関する考察)

6. grant_management_action=merge で継承した権限をどのように管理するか。アクセストークン発行時のスナップショットとしてか (後から変化しない)、何か他の物へのリンクとしてか (後から変化するかもしれない)、またはその他の形態か。

7. grant_management_action=merge で継承した権限を持つアクセストークンの有効性をリソースサーバーはどのように確認するか。現在のところ、イントロスペクションレスポンスと JWT アクセストークンの形式についてグラント管理用に合意された標準は存在せず、議論も若干紛糾している。(参考: "FAPI ISSUE 455: Impact of grant_management_action=update on AT implementation and introspection")

実装の実例

グラント管理は Authlete 2.3 以降でサポートされます。コミュニティへのフィードバックとして、Authlete の実装で採用した設計について記述していきます。

前提知識

下記のリストは、後続のセクションを読むのに必要となる Authlete のアクセストークンの実装に関する前提知識です。

1. アクセストークンの実装型は「ハンドル」であり、「内包型」(典型例は JWT) ではありません。「アクセストークン署名アルゴリズム」を設定することにより、Authlete に JWT アクセストークンを生成されることはできます (参照: "「JWT ベースのアクセストークン」の有効化")。しかし、プライバシーおよびセキュリティ上の理由により、Authlete の JWT アクセストークンは紐付くデータ全てを含むことを意図的にせず、データの一部はアクセストークンに埋め込まれることなく Authlete のデータベース内のみに保持されます。詳細については 「JWT アクセストークンからの個人情報漏洩」 および 「OAuth アクセストークンの実装に関する考察」 を参照してください。

2. リフレッシュトークンフロー (RFC 6749 / Section 6) 成功時、使用されたリフレッシュトークンに紐付くアクセストークンは、有効期限が切れていなくても失効します。

3. リフレッシュトークンフロー成功時に新しいリフレッシュトークンが発行されるか、もしくは発行されずに使用したリフレッシュトークンが使用後も有効のままかは、設定により選択可能です (参照: リフレッシュトークンの継続利用設定)。新しいリフレッシュトークンが発行される場合、使用されたリフレッシュトークンは、有効期限が切れていなくても失効します。

4. リフレッシュトークンとアクセストークンの関係は 1 対 1 です。つまり、1 つのリフレッシュトークンごとに有効なアクセストークンの数は最大でも 1 で、逆も成り立ちます。

5. リフレッシュトークンが削除された場合、対になっているアクセストークンも削除されます。同様に、アクセストークンが削除された場合、対になっているリフレッシュトークンも削除されます。後者の動作については驚く方もいるかもしれませんが、RFC 7009 OAuth 2.0 Token Introspection の Section 2.1 は明示的に次のように述べています: “If the token passed to the request is an access token, the server MAY revoke the respective refresh token as well.”

6. 上記のリフレッシュトークンの動作は、Authlete のかなり初期の段階でなされた設計に関する意思決定により説明できます: アクセストークンとリフレッシュトークンの組はアクセストークンテーブル内の一つのレコードで管理される。

7. アクセストークンレコードは、アクセストークンとリフレッシュトークンのどちらか、もしくは双方が有効期限前であれば、Live (期限切れしていない) とみなされます。

グラント

Authlete はグラントを Live アクセストークンレコードの集合と定義します。 結果として、グラントのアクセストークンレコードが期限切れしたとき、グラントの内容が変化します。この変化は明示的なグラント管理アクション (grant_management_action を伴う認可リクエストおよびグラント管理エンドポイントへの失効リクエスト) がなくとも起こりえます。なぜなら、アクセストークンレコードの期限切れはグラント管理アクションとは独立して起こるからです。

認可サーバーの実装はグラント ID を管理するために新たにデータベーステーブルを作成することを選ぶかもしれません。しかし、Authlete は異なるアプローチを選択し、既存のアクセストークンテーブルに grant_id カラムを追加するだけで済ませました。下図は、グラントが Live アクセストークンレコードにより構成されることを示しています。

グラント ID 発行

初版ドラフトの Section 5.4 Token Response が “The AS will return a grant_id if it supports any of the grant management actions” と言っているものの、Authlete では、トークンレスポンスがグラント ID を含むのは、先行する認可リクエスト (またはバックチャネル認証リクエストもしくはデバイス認可リクエスト) が grant_management_action リクエストパラメーターを含んでいる場合のみです。

仕様書の記述は結果的に、グラント管理をサポートする認可サーバーが無条件に常にグラント ID を発行することを要求することになっていますが、グラント管理を使用することを認めらていないパブリッククライアント (Section 5.1) にグラント ID を発行しても意味がありません。"FAPI ISSUE 455: Condition for a token response to include a grant_id" で文言の変更を提案しています。

認可リクエストが grant_management_action リクエストパラメーターを含み、認可エンドポイントからアクセストークンが発行されるとしても、Authlete は認可エンドポイントからグラント ID を発行しません。なぜなら、仕様の著者の方々が意図的にそのケースを仕様から取り除いていることを確認できたからです。仕様内で明示的に言及するよう、"FAPI ISSUE 453: Grant ID from Authorization Endpoint" で提案しています。

一方、バックチャネル認証リクエストが grant_management_action リクエストパラメーターを含み、クライアントが CIBA プッシュモードを使用するように設定されている場合、Authlete は CIBA プッシュ通知にグラント ID を含めます。しかし、CIBA プッシュ通知用に grant_id パラメーターを登録することをまだ提案していません。いずれにしても、FAPI-CIBA プロファイルは CIBA プッシュモードの使用を禁止しているため、FAPI ワーキンググループはこの件に興味は示さないでしょう。

継承した権限

認可リクエストが grant_management_action=merge を含んでいるとき、新規発行されるアクセストークンは、grant_id リクエストパラメーターで特定されるグラントの権限を継承します。Authlete はこの継承を、既存のアクセストークンレコード群の権限を新規挿入されるアクセストークンレコードの grant カラムにコピーすることで実現します。

grant カラムの内容は、アクセストークン発行時点に存在した権限のスナップショットです。スナップショットは、権限の提供元のアクセストークンレコードが期限切れしたり削除されたりした後も変化しません。

ディスカバリー文書内のメタデータ

グラント管理関連のサーバーメタデータの値は下表が説明するとおりに決定されます。

異なるユーザー

認可処理の過程でユーザーは (まだであれば) 認証されます。grant_id リクエストパラメーターで指定されたグラントのユーザーが認証されたユーザーと異なるということはありえます。そのような場合に認可サーバーがどの振る舞うべきかについて、仕様は述べていません。この件を議論するため "FAPI 452: When the user being authenticated is different from the user of the grant" を作成しましたが、結論としては「実装に任せる」となりそうです。

認証されたユーザーとグラントのユーザーが異なる場合、Authlete はエラーを報告することなく、グラント管理関連の処理を黙ってスキップします。

同意済みクレーム

設計により、認可サーバーとユーザーとのやりとりに Authlete は干渉しません。Authlete は認可サーバーではなく、開発者が自分の認可サーバーを開発するのに使う Web API のセットです。そのため、開発者が開発した認可サーバーがユーザーの同意をどのように取得するのか、Authlete は知りません。クレームセットに展開される特別なスコープ (profile, email, address, phone) が scope リクエストパラメーターに含まれているとき、認可サーバーは展開されたクレーム群について一つ一つ同意を取るかもしれませんし、その手続きを省略するかもしれません。Authlete は、提供されたクレームデータが、ユーザーの同意を得たものかどうかを知ることなく、ID トークンやユーザー情報レスポンスに組み込みます。

しかし、グラント管理エンドポイントの応答に含まれる claims プロパティーを意味あるものにするためには、Authlete は同意されたクレーム群の正確なセットを知るべきです。この目的のため、次の API に consentedClaims リクエストパラメーターが追加されました。(参照: AuthorizationIssueRequest.setConsentedClaims())

• /api/auth/authorization/issue
• /api/backchannel/authentication/complete
• /api/device/complete

リクエストパラメーターが与えられ、値が空でなければ、Authlete はその値を同意済みクレーム群のセットとみなします。そうでない場合、Authlete は同意された特別なスコープ群 (例: profile) と (claims リクエストパラメーターにより) 提供されたクレームデータをもとに、同意済みクレーム群のセットを計算します。しかし、計算により得られるセットは実際に同意されたクレーム群のセットとは異なるかもしれません。特に、計算されたセットには、認可サーバーがユーザー情報エンドポイントから返すクレーム群は含まれていないかもしれません。そのため、同意済みクレーム群の正確なセットを制御する必要がある場合、consentedClaims リクエストパラメーターが使用されるべきです。

グラント管理レスポンスの圧縮

Authlete はグラント管理レスポンスの内容を圧縮します。

scopes

scopes 配列内の要素はリソースセットごとにグループ化されます。要素はリソースセットでソートされます。同じリソースセット内のスコープはマージされて scope プロパティにセットされます。

例えば、グラントの Live アクセストークンレコード群が次の権限を持っている場合、

当該集合は次のように圧縮されます。

この結果、グラント管理レスポンス内の scopes 配列は次のようになります。

{
  "scopes": [
    { "scope": "B1 G1 X1",    "resource": [ "r1"       ] },
    { "scope": "A12 H12 X12", "resource": [ "r1", "r2" ] },
    { "scope": "D13 I13 X13", "resource": [ "r1", "r3" ] },
    { "scope": "C2 K2 X2",    "resource": [ "r2"       ] },
    { "scope": "E23 L23 X23", "resource": [ "r2", "r3" ] },
    { "scope": "F3 J3 X3",    "resource": [ "r3"       ] }
  ]
}

claims

グラントの Live アクセストークンレコード群の同意済みクレーム群は集められ、重複は取り除かれ、残った要素はソートされて claims 配列に格納されます。

例えば、グラントの Live アクセストークンレコード群が次の同意済みクレーム群を持っている場合、

当該集合は次のように圧縮されます。

この結果、グラント管理レスポンス内の claims 配列は次のようになります。

{
  "claims": [
    "c1", "c2", "c3", "c4", "c5"
  ]
}

authorization_details

authorization_details 配列内の重複は取り除かれます。Authlete は配列要素のハッシュ値を比較することで重複を検出します。JSON 内のスペースや改行はハッシュ計算の結果に影響しません。また、JSON オブジェクト内のキーの順序も結果に影響しません。そのため、次の二つの authorization_details 要素は同一とみなされます。

{
  "authorization_details": [
    {
      "type": "t1",
      "actions": [ "a1", "a2" ],
      "my_custom_data": {
        "key1": "value1",
        "key2": "value2"
      }
    },
    {
      "my_custom_data": { "key2": "value2", "key1": "value1" },
      "actions": [
        "a1",
        "a2"
      ],
      "type": "t1"
    }
  ]
}

アクセストークンイントロスペクション

先に述べたとおり、スコープ群が意図しないリソース群と組み合わせられることがないよう、merge 操作の繰り返しにより権限が累積しても認可サーバーはスコープリソースクラスター群を分けて管理せざるをえません。

merge 操作により、アクセストークンはスコープリソースクラスター群を継承します。であれば、イントロスペクションレスポンス (RFC 7662) と JWT アクセストークン (RFC 9068) のフォーマットを拡張する必要があります。そうしないと、保護リソースエンドポイントはアクセストークンの有効性を適切に確認できないからです。

この件を議論するため、"FAPI ISSUE 455: Impact of grant_management_action=update on AT implementation and introspection" を作成し、また、議論の要点を詳細に説明するために "Complexity of Access Token Privileges Introduced by Grant Management" という記事も書きました。

しかし、同意に達することは期待していたよりもはるかに大変でした😅。これを書いている時点では、本件の解決策についてコミュニティが短期間で合意に至るのは非現実的に思われます。

幸運なことに、Authlete は標準イントロスペクションエンドポイントとは異なる独自のイントロスペクション API (/api/auth/introspection) を開発者の方々に提供しています。当該 API は、標準のものよりも下記の点においてかなり便利です。

1. 証明書バインディング (RFC 8705)、DPoP、リソース (RFC 8707)、スコープ (RFC 6749)、リソースオーナーのサブジェクト、などの有効性を確認する複雑な処理を、イントロスペクション API に実施させることができる。

2. エラーの場合、保護リソースエンドポイントが RFC 6750 に簡単に準拠できるように、イントロスペクション API は当仕様に準拠するエラーメッセージを用意する。

3. 開発者は Authlete の Extra Properties 機能を用いて任意の Key-Value ペア群をアクセストークンに紐付けることができる (参照: トークンに任意のプロパティをひもづける方法)。イントロスペクション API の応答はその Key-Value ペア群を含んでいる。

Authlete はグラント管理のためにイントロスペクション API を拡張しました。

まず、新しいレスポンスパラメーター grantId と grant を追加しました。

次に、イントロスペクション API は新しいリクエストパラメーター resources を認識します。そして、scopes と resources 用の検証処理は一から書き直され、下表で説明するとおりに動作します。

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

新しい API /api/gm が追加されました。開発者はこの API を用いてグラント管理エンドポイントを実装することができます。

下表は /api/gm API のリクエストパラメーターのリストです。詳細は GMRequest クラスの JavaDoc を参照してください。

さいごに

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

2021 年 11 月 9 日
文責: 川崎 貴彦