RAR - Rich Authorization Requestsとは
アクセストークンの権限を従来のscopeより細かく定義するための仕組みがRARです。
認可リクエストに送るauthorization_detailsを設計することにより、"accounts"のようなキーワードベースである従来のscopeより詳細な権限スコープを定義することができます。これにより、例えば特定の写真の読み取りの許可のような、より具体的な権限をOAuth2に組み込むことができます。
認可リクエスト例
authorization_detailsを使った認可エンドポイントへのリクエスト例です。
GET /authorize?response_type=code
&client_id=s6BhdRkqt3
&state=af0ifjsldkj
&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
&code_challenge_method=S256
&code_challenge=K2-ltc83acc4h0c9w6ESC_rEMTJ3bwc-uCHaoeK1t8U
&authorization_details=%5B%7B%22type%22%3A%22account%5Finfo
rmation%22%2C%22actions%22%3A%5B%22list%5Faccounts%22%2C%22
read%5Fbalances%22%2C%22read%5Ftransactions%22%5D%2C%22loca
tions%22%3A%5B%22https%3A%2F%2Fexample%2Ecom%2Faccounts%22%
5D%7D%2C%7B%22type%22%3A%22payment%5Finitiation%22%2C%22act
ions%22%3A%5B%22initiate%22%2C%22status%22%2C%22cancel%22%5
D%2C%22locations%22%3A%5B%22https%3A%2F%2Fexample%2Ecom%2Fp
ayments%22%5D%2C%22instructedAmount%22%3A%7B%22currency%22%
3A%22EUR%22%2C%22amount%22%3A%22123%2E50%22%7D%2C%22credito
rName%22%3A%22Merchant%20A%22%2C%22creditorAccount%22%3A%7B
%22iban%22%3A%22DE02100100109307118603%22%7D%2C%22remittanc
eInformationUnstructured%22%3A%22Ref%20Number%20Merchant%22
%7D%5D HTTP/1.1
Host: server.example.com
上記のうち、authorization_details部分を読みやすくデコードしたものが以下です。
[
{
"type": "account_information",
"actions": [
"list_accounts",
"read_balances",
"read_transactions"
],
"locations": [
"https://example.com/accounts"
]
},
{
"type": "payment_initiation",
"actions": [
"initiate",
"status",
"cancel"
],
"locations": [
"https://example.com/payments"
],
"instructedAmount": {
"currency": "EUR",
"amount": "123.50"
},
"creditorName": "Merchant A",
"creditorAccount": {
"iban": "DE02100100109307118603"
},
"remittanceInformationUnstructured": "Ref Number Merchant"
}
]
ちなみに、authorization_detailsを含むリクエストは複雑で長いので、PARと併用することも検討できます。
OAuth2.0 PAR(Pushed Authorization Requests)の概要
authorization_detailsの仕様概略
authorization_detailsの中身は権限を示すオブジェクトの配列です。（以下オブジェクトと表記）
オブジェクトは型を意図するtypeキーを持つ必要があります。
また、利用は任意ですがオブジェクト内で使う以下のキーがRFC9396にて予め定義されています。
| キー | 内容 | 必須 |
|---|---|---|
| type | オブジェクトのタイプを示す文字列 | 必須 |
| locations | リソースまたはリソースサーバーの場所を表す文字列の配列 | 任意 |
| actions | リソースで実行されるアクションの種類を表す文字列の配列 | 任意 |
| datatypes | リソースから要求されるデータの種類を表す文字列の配列 | 任意 |
| identifier | APIで利用可能な特定のリソースを示す文字列識別子 | 任意 |
| (任意のキー) | 開発者が自分で定義する文字列 | 任意 |
authorization_detailsの例です。
この例では顧客情報のうちの連絡先のReadと写真のWriteをユーザーに許可しています。
[
{
"type": "customer_information",
"locations": [
"https://example.com/customers"
],
"actions": [
"read"
],
"datatypes": [
"contacts"
]
},
{
"type": "customer_information",
"locations": [
"https://example.com/customers"
],
"actions": [
"write"
],
"datatypes": [
"photos"
]
}
]
一般的なデータフィールドの場合、権限はその配列の和(または)を取ります。
異なるデータフィールドがある場合、権限はそれぞれの積(かつ)を取ります。
具体的に、以下の例では「連絡先及び写真をReadまたはWriteする権限を与える」ということをやっています。
[
{
"type": "customer_information",
"locations": [
"https://example.com/customers"
],
"actions": [
"read",
"write"
],
"datatypes": [
"contacts",
"photos"
]
}
]
上記で挙げた他にも、API設計者は自由にキーを定義することができます。
以下の例では支払いの金額としてcurrencyとamountのキーを定義しています。
[
{
"type": "financial-transaction",
"actions": [
"payment"
],
"identifier": "account-14-32-32-3",
"currency": "USD",
"amount": "10.0"
}
]
まとめ
RAR（Rich Authorization Requests）は、従来のscopeでは表現しきれなかった粒度の権限を定義するためのOAuth2の仕様です。
従来のscopeはaccountsのようなキーワードベースでの権限指定に留まっていましたが、RARではauthorization_detailsを用いることで、より具体的で構造化された権限を表現することが可能になります。
また、authorization_detailsはJSON形式のオブジェクトとして自由に設計できるため、ユースケースに即した認可制御を実現できます。
一方で、リクエストが複雑化しやすいという特性もあるため、PAR（Pushed Authorization Requests）と併用することで、安全かつ効率的な運用が可能になります。