1.1. 規約および 用語

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

この仕様では、"The OAuth 2.0 Authorization Framework" [RFC6749]で定義される "access token"、"refresh token"、"authorization server"（AS）、"resource server"（RS）、 "authorization endpoint"、"authorization request"、"authorization response"、"token endpoint"、 "grant type"、"access token request"、"access token response"、および "client"という用語を使用します。¶

2.1. 認可詳細 タイプ

ASは、typeパラメーターの値の解釈と、 typeパラメーターが許可するオブジェクトフィールドを制御します。ただし、 typeパラメーターの値は一般に文書化され、開発者によって使用されることを意図しています。 API設計者は、曖昧さなく容易にコピーできるtype値を選択することが RECOMMENDEDです。たとえば、いくつかのグリフには同じ視覚的文字に対する 複数のUnicodeコードポイントがあり、開発者がASの定義したものとは異なる文字を入力してしまう可能性があります。 潜在的な混乱を減らす手段としては、値をASCII [RFC0020]文字に制限すること、データ型値の機械可読な一覧を提供すること、 または開発者に文書から直接コピーして貼り付けるよう指示することが考えられます。¶

アプリケーションまたはAPIが、オープン標準の場合のように 異なるサーバー全体に展開されることが想定される場合、API設計者は、 API設計者が制御するURIなど、自身の制御下にある衝突耐性のある名前空間を使用することが RECOMMENDEDです。¶

次の例は、実装が衝突耐性のあるタイプ値を確保するために 名前空間https://scheme.example.org/をどのように利用できるかを示しています。¶

{
   "type": "https://scheme.example.org/files",
   "locations": [
      "https://example.com/files"
   ],
   "permissions": [
      {
         "path": "/myfiles/A",
         "access": [
            "read"
         ]
      },
      {
         "path": "/myfiles/A/X",
         "access": [
            "read",
            "write"
         ]
      }
   ]
}

2.2. 共通データフィールド

この仕様は、異なる種類のAPI全体で使用できるように設計された 共通データフィールドのセットを定義します。この仕様は、API定義にこれらの共通フィールドの使用を要求せず、 代わりに、API設計者が利用できる再利用可能な汎用コンポーネントとして提供します。 すべてのフィールドの許可される値は、特定の"type"値によって定義される、保護対象のAPIによって決定されます。¶

locations:

リソースまたはRSの位置を表す文字列の配列。 これらの文字列は通常、RSの位置を識別するURIです。このフィールドにより、 セクション12で議論されているように、 クライアントは特定のRSを指定できます。¶

actions:

リソースで実行されるアクションの種類を表す 文字列の配列。¶

datatypes:

リソースから要求されるデータの種類を表す 文字列の配列。¶

identifier:

APIで利用可能な特定のリソースを示す 文字列識別子。¶

privileges:

リソースで要求される特権の種類またはレベルを表す 文字列の配列。¶

異なる共通データフィールドを組み合わせて使用する場合、 クライアントが要求する権限はすべての値の積になります。 このオブジェクトは、オブジェクト内に列挙されたすべてのactions値が、 オブジェクト内に列挙されたすべてのlocations値において、オブジェクト内に列挙されたすべての datatypes 値に対して使用されることのリクエストを表します。次の例では、クライアントは customer_information API内の顧客に属するcontactsとphotosの両方に対する readおよびwrite アクセスを要求しています。 このリクエストが許可された場合、クライアントは、 写真への読み取りアクセスと連絡先への書き込みアクセスなど、 APIによって定義される権利の任意の組み合わせを使用できると想定するでしょう。¶

[
   {
      "type": "customer_information",
      "locations": [
         "https://example.com/customers"
      ],
      "actions": [
         "read",
         "write"
      ],
      "datatypes": [
         "contacts",
         "photos"
      ]
   }
]

クライアントがアクセスをより細かく制御したい場合は、 複数のオブジェクトを送信できます。この例では、 クライアントは、同じAPIエンドポイント内のcontactsへのreadアクセスと、 photosへの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"
      ]
   }
]

APIは、それぞれの認可オブジェクトのtypeに従って、 独自の拡張を定義することがMAYです。 API設計者は、この仕様で定義された共通データフィールドと、 API自体に固有のフィールドを組み合わせて使用することが想定されます。 次の非規範的な例は、2つの異なる架空のAPI type値の一部として、 共通フィールドとAPI固有フィールドの両方を使用する方法を示しています。最初の アクセスリクエストには、ここで指定されたactions、locations、および datatypes フィールドに加え、指定された座標で撮影された写真へのアクセスを示すAPI固有の geolocation フィールドが含まれています。2番目のアクセスリクエストには、ここで指定された actionsおよび identifierフィールドに加え、API固有の currencyフィールドが含まれています。¶

[
   {
      "type":"photo-api",
      "actions":[
         "read",
         "write"
      ],
      "locations":[
         "https://server.example.net/",
         "https://resource.local/other"
      ],
      "datatypes":[
         "metadata",
         "images"
      ],
      "geolocation":[
         {
            "lat":-32.364,
            "lng":153.207
         },
         {
            "lat":-35.364,
            "lng":158.207
         }
      ]
   },
   {
      "type":"financial-transaction",
      "actions":[
         "withdraw"
      ],
      "identifier":"account-14-32-32-3",
      "currency":"USD"
   }
]

このリクエストが承認された場合、結果として得られるアクセストークンのアクセス権は、 上記と同様に、2つのAPIそれぞれについて要求されたアクセス種類の和集合になります。¶

3.1. "scope"パラメーターとの 関係

authorization_detailsとscopeは、 独立した認可要件を運ぶために、同じ認可リクエストで使用できます。¶

authorization_detailsとscopeの併用は、 既存のOAuthベースのアプリケーションが段階的にauthorization_detailsのみの使用へ 移行できるようにするため、この仕様で部分的にサポートされています。 特定のAPIは、要件指定の形式を1つだけ使用することがRECOMMENDEDです。¶

ASは、与えられた認可リクエストについて、両方の要件セットを相互に組み合わせて処理 MUSTします。ASがこれらのパラメーターをどのように組み合わせるかの詳細は、 保護対象のAPIに固有であり、この仕様の範囲外です。¶

ユーザー同意を取得するとき、ASは認可リクエストによって表される統合された要件セットを提示 MUSTします。¶

リソース所有者がクライアントに要求されたアクセスを許可した場合、ASは それぞれのauthorization_details（および該当する場合はscope値）に関連付けられた トークンをクライアントに発行します。¶

3.2. "resource"パラメーターとの 関係

[RFC8707]で定義される resource認可リクエストパラメーターは、要求されたスコープを適用できるリソースを さらに決定するために使用できます。resource パラメーターは、ASがauthorization_details認可リクエストパラメーターを処理する方法には 影響しません。¶

6.1. 認可詳細の 比較

OAuthプロトコルの多くのアクションでは、ASとRSが、 リクエストが以前の既存のリクエストより「多く」を求めているか「少なく」を求めているかに基づいて セキュリティ上の判断を行うことができます。たとえば、トークンの更新時に、クライアントは リソース所有者によって以前に認可されたものより「少ない権限」を持つ新しいアクセストークンを 要求できます。要求されたアクセストークンは削減された権限を伝達しますが、 リソース所有者の以前の認可はこのようなリクエストによって変更されません。 authorization_details内のフィールドの意味は、特定のAPIまたはAPIセットに 実装固有であるため、任意の2つの認可詳細リクエストを比較するための標準化された仕組みはありません。 ASは、ほとんどの場合、単純なオブジェクト比較に依存すべきではありません。 リクエスト内の一部フィールドの交差が、APIがどのように設計および展開されているかに応じて、 付与されるアクセス権に副作用をもたらす可能性があるためです。これは一部のAPIでscope値を使用する場合と 同様の効果です。¶

新しいリクエストを既存のリクエストと比較する場合、ASは、 リソース所有者がリクエストを認可する必要があるかどうかを判断するために、 最初にリクエストを許可したときと同じ処理技法を使用できます。この比較の詳細は、 認可リクエストのtypeの定義に依存し、この仕様の範囲外ですが、 一般的なパターンを適用できます。¶

これは、継続している例を使用して説明されます。 セクション3の認可リクエスト例は、ユーザーによって承認された場合、 次の権限に関連付けられた認可コードの発行をもたらしました。¶

• アカウントの一覧表示、¶
• 1つ以上のアカウントの残高へのアクセス、¶
• 1つ以上のアカウントの取引へのアクセス、および¶
• 支払いの開始、ステータス確認、およびキャンセル。¶

クライアントは次に、アカウント一覧へのアクセス権限だけを割り当てたアクセストークンを発行するよう、 ASに次のように要求できます。¶

[
   {
      "type": "account_information",
      "actions": [
         "list_accounts"
      ],
      "locations": [
         "https://example.com/accounts"
      ]
   }
]

この例のAPIは、account_information型で使用される各フィールドが 追加的な権利を含み、actionsおよびlocations配列内の各値が 異なるアクセス要素を指定するように設計されています。この場合に比較を行うために、 ASは次の手順を実行します。¶

• 前の手順で発行された認可コードに、 account_information型の認可詳細オブジェクトが含まれることを検証する、¶
• 承認済みアクションの一覧に list_accountsが含まれるかを検証する、および¶
• locations値が、 以前に承認された場所のみを含むかを検証する。¶

すべてのチェックが成功した場合、ASは削減されたアクセスセットを持つ要求されたアクセストークンを 発行します。¶

この比較は、この特定のAPI型定義に関連していることに注意してください。 異なるAPI型定義では、異なる処理規則を持つ可能性があります。たとえば、 actions値が別のactions値に関連付けられた権利を包含する可能性があります。 たとえば、クライアントが最初にwriteアクセスを持つトークンを要求した場合、 これはこのAPIへの読み取りアクセスと書き込みアクセスの両方を意味します。¶

[
    {
        "type": "example_api",
        "actions": [
            "write"
        ]
    }
]

その後、同じクライアントがread アクセスの更新リクエストを行います。¶

[
    {
        "type": "example_api",
        "actions": [
            "read"
        ]
    }
]

ASはtype値とactions 値を比較して、readアクセスが以前にクライアントに付与された writeアクセスによってすでにカバーされていることを判断します。¶

この同じAPIは、privilegesの可能な値として adminを持つように設計できます。この例では、結果のトークンがリソース上の任意の機能を実行できることを 示すために使用されます。 その クライアントがこのようなAPIへのadmin特権を付与された場合、 authorization_detailsは次のようになります。¶

[
    {
        "type": "example_api",
        "privileges": [
            "admin"
        ]
    }
]

ASはtype値を比較し、 privileges値が以前にクライアントに付与された readまたはwriteアクセスの任意の側面を包含することを見つけます。 ほかのAPI定義では、値が互いに包含しないようにprivilegesを使用できることに注意してください。¶

次の例は、クライアントが共通データ要素 locations（セクション 2.2を参照）を使用して、特定のRSに制限されたアクセストークンの発行を要求する方法を示しています。 継続例では、クライアントは、https://example.com/paymentsに存在するRSに適用可能な payment_initiation型の承認済みグラントのすべての権限を 次のように要求できます。¶

[
   {
      "type": "payment_initiation",
      "locations": [
         "https://example.com/payments"
      ]
   }
]

7.1. トークンレスポンスにおける拡充された認可 詳細

アクセストークンに付加された認可詳細は、クライアントが要求したものと異なることが MAYです。ユーザーがクライアントの要求より少ない範囲を認可することに加えて、 ASが認可詳細オブジェクト内のデータを拡充するユースケースがあります。 拡充が許可されるかどうか、およびそれがどのように機能するかの詳細は、 必然的にそれぞれの認可詳細タイプの定義の一部です。¶

1つの例として、クライアントがアカウント情報へのアクセスを求めるが、 アクセスできる具体的なアカウントについての決定をユーザーに委ねる場合があります。 認可プロセスの過程で、ユーザーはクライアントにアクセスを許可したいアカウントのサブセットを選択します。 選択されたアカウントを伝達する設計上の選択肢の1つとして、ASはこの情報を それぞれの認可詳細オブジェクトに追加できます。¶

その例では、要求されたauthorization_detailsパラメーターは 次のようになります。この例では、空配列は、ASによる拡充中にデータが追加される場所の プレースホルダーとして機能します。この例は説明のためだけのものであり、 認可詳細タイプの具体的な設計方法としてこの方法を推奨することを意図していません。¶

"authorization_details": [
   {
      "type": "account_information",
      "access": {
         "accounts": [],
         "balances": [],
         "transactions": []
      },
      "recurringIndicator":true
   }
]

その後、ASは認可詳細オブジェクトを拡張し、 それぞれのアカウント識別子を追加します。¶

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

{
   "access_token":"2YotnFZFEjr1zCsicMWpAA",
   "token_type":"example",
   "expires_in":3600,
   "refresh_token":"tGzv3JokF0XG5Qx2TlKWIA",
   "authorization_details":[
      {
         "type":"account_information",
         "access":{
            "accounts":[
               {
                  "iban":"DE2310010010123456789"
               },
               {
                  "maskedPan":"123456xxxxxx1234"
               }
            ],
            "balances":[
               {
                  "iban":"DE2310010010123456789"
               }
            ],
            "transactions":[
               {
                  "iban":"DE2310010010123456789"
               },
               {
                  "maskedPan":"123456xxxxxx1234"
               }
            ]
         },
         "recurringIndicator":true
      }
   ]
}

別の例として、クライアントが医療記録へのアクセスを求めているが、 リクエスト時点では記録番号を知らない場合があります。この例では、クライアントは希望するアクセスの種類を指定しますが、 そのアクセスの場所または識別子は指定しません。¶

{
"authorization_details": [
   {
      "type": "medical_record",
      "sens": [ "HIV", "ETH", "MART" ],
      "actions": [ "read" ],
      "datatypes": [ "Patient", "Observation", "Appointment" ]
   }
]}

ユーザーがASと対話するとき、ユーザーはクライアントに提供する責任のある医療記録を選択します。 この情報はアクセストークンとともに返されます。¶

{
   "access_token":"2YotnFZFEjr1zCsicMWpAA",
   "token_type":"example",
   "expires_in":3600,
   "refresh_token":"tGzv3JokF0XG5Qx2TlKWIA",
   "authorization_details":[
    {
      "type": "medical_record",
      "sens": [ "HIV", "ETH", "MART" ],
      "actions": [ "read" ],
      "datatypes": [ "Patient", "Observation", "Appointment" ],
      "identifier": "patient-541235",
      "locations": [ "https://records.example.com/" ]
     }
  ]
}

9.1. JWTベースのアクセストークン

アクセストークンがJWT [RFC7519]である場合、ASは、 特定のオーディエンス向けにフィルタリングされた認可詳細オブジェクトをトップレベルのクレームとして追加することが RECOMMENDEDです。¶

ASは通常、RSがリクエスト処理に必要とする追加のクレーム、 たとえばユーザーID、ロール、取引固有のデータもJWTに追加します。 特定のRSが必要とするクレームは、ASとのRS固有ポリシーによって定義されます。¶

次は、上記の支払い開始例に関するJWT例の内容を示します。¶

{
   "iss": "https://as.example.com",
   "sub": "24400320",
   "aud": "a7AfcPcsl2",
   "exp": 1311281970,
   "acr": "psd2_sca",
   "txn": "8b4729cc-32e4-4370-8cf0-5796154d1296",
   "authorization_details": [
      {
         "type": "https://scheme.example.com/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"
      }
   ],
   "debtorAccount": {
      "iban": "DE40100100103307118608",
      "user_role": "owner"
   }
}

この場合、ASはJWTベースのアクセストークンに次の例のクレームを追加しました。¶

sub:

クライアントが支払い開始を求めている対象ユーザーを示します。¶

txn:

プロバイダーexample.comのサービス全体で 取引を追跡するために使用される取引ID¶

debtorAccount:

債務者口座を含むAPI固有フィールド。 この例では、このアカウントはauthorization_detailsで渡されたものではなく、 認可プロセス中にユーザーによって選択されました。user_roleフィールドは、 この特定のアカウントに関してユーザーが持つロールを伝達します。この場合、ユーザーは所有者です。 このデータは支払いAPI（RS）でのアクセス制御に使用されます。¶

9.2. トークンイントロスペクション

トークンイントロスペクション [RFC7662]は、RSがASに問い合わせて アクセストークンに関する情報を判断する手段を提供します。ASがレスポンスにトークンの認可詳細情報を含める場合、 その情報はイントロスペクションレスポンスJSONオブジェクトのトップレベルメンバーとして authorization_detailsで伝達される MUSTです。authorization_detailsメンバーは、 セクション2で定義された同じ構造を含む MUSTであり、イントロスペクションリクエストを行うRS向けに フィルタリングおよび拡張される可能性があります。¶

支払い開始例のイントロスペクションレスポンス例を次に示します。¶

{
   "active": true,
   "sub": "24400320",
   "aud": "s6BhdRkqt3",
   "exp": 1311281970,
   "acr": "psd2_sca",
   "txn": "8b4729cc-32e4-4370-8cf0-5796154d1296",
   "authorization_details": [
      {
         "type": "https://scheme.example.com/payment_initiation",
         "actions": [
            "initiate",
            "status",
            "cancel"
         ],
         "locations": [
            "https://example.com/payments"
         ],
         "instructedAmount": {
            "currency": "EUR",
            "amount": "123.50"
         },
         "creditorName": "Merchant123",
         "creditorAccount": {
            "iban": "DE02100100109307118603"
         },
         "remittanceInformationUnstructured": "Ref Number Merchant"
      }
   ],
   "debtorAccount": {
      "iban": "DE40100100103307118608",
      "user_role": "owner"
   }
}

11.1. 特定のデプロイメントにおける認可 詳細の使用

特定のデプロイメントで認可詳細を使用するには、 次の手順が必要です。¶

• 認可詳細タイプを定義する。¶
• OAuthサーバーメタデータで認可詳細タイプを公開する。¶
• ユーザー同意プロンプトで認可詳細をどのように表示するかを決定する。¶
• 必要に応じて、ユーザー同意プロセスで認可詳細を拡充する （例: 選択されたアカウントを追加する、または有効期限を設定する）。¶
• 必要に応じて、認可詳細がアクセストークン内容または イントロスペクションレスポンスにどのように反映されるかを決定する。¶
• RSが認可詳細または認可詳細から派生したトークンデータを どのように処理するかを決定する。¶
• 必要に応じて、クライアントに特定の認可詳細タイプを使用する権利を付与する。¶

11.2. 最小実装 サポート

この仕様をサポートする一般的なAS実装は、 次の基本機能を提供すべきです。¶

• OAuthサーバーメタデータでサポートされている認可詳細タイプの広告をサポートする¶
• この仕様に適合する認可リクエストで authorization_detailsパラメーターを受け入れることをサポートする¶
• 同意された認可詳細をグラントの一部として保存することをサポートする¶
• 認可詳細をアクセストークンおよびトークンイントロスペクションレスポンスに追加し、 RSで利用できるようにするための既定の動作を実装する（scope値と同様）。これは任意のグラントタイプ、 特にauthorization_codeおよびrefresh_tokenで機能すべきです。¶

認可詳細の処理および提示は、異なる認可詳細タイプ間で大きく異なります。 したがって、実装はそれぞれの動作のカスタマイズをサポートすべきです。特に、実装は デプロイメントが次を行えるようにすべきです。¶

• 認可詳細の提示を決定する。¶
• ユーザー同意プロセスで要求された認可詳細を変更する （例: フィールドの追加）。および¶
• 要求された認可詳細と既存の認可詳細をマージする。¶

このようなカスタマイズをサポートする1つのアプローチは、 拡張モジュールの登録を可能にする仕組みを持つことです。各モジュールは、 それぞれのユーザー同意のレンダリングと、構造化アクセストークンまたはトークンイントロスペクションレスポンスを介して RSに必要なデータを提供するために必要な変換を担当します。¶

11.3. 機械可読なタイプスキーマの 使用

実装は、認可詳細タイプを定義するために機械可読なスキーマ言語を デプロイメントが使用できるようにして、そのようなスキーマに対する認可詳細オブジェクトの作成および検証を 容易にする可能性があります。たとえば、認可詳細 typeがJSON Schema [JSON.Schema]を使用して定義された場合、JSON Schema識別子を それぞれの認可詳細オブジェクト内のtype値として使用できます。¶

ただし、type値はASによって、また必要な範囲で クライアントおよびRSによって理解される識別子であることに注意してください。 この仕様は、type値が機械可読なスキーマ形式を指すこと、またはシステム内のいずれかの当事者 （クライアント、AS、RSなど）がtypeフィールドの内容を特定の方法で参照解除または処理することを 前提としていません。¶

11.4. 大きなリクエスト

リクエストパラメーターまたはリクエストオブジェクト内に authorization_detailsを含む認可リクエストURIは非常に長くなる可能性があります。 したがって、実装者は、authorization_detailsを信頼性が高く安全な方法で渡すために、 [RFC9101]で定義されるrequest_uriパラメーターを、 [RFC9126]で定義されるプッシュ型リクエストオブジェクト機構と組み合わせて使用することを 検討すべきです。以下は、HTTPSで保護された接続を介して認可リクエストデータをASに直接送信する そのようなプッシュ型認可リクエストの例です。¶

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

  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_information%22
  %2C%22actions%22%3A%5B%22list_accounts%22%2C%22read_balances%22%2C%
  22read_transactions%22%5D%2C%22locations%22%3A%5B%22https%3A%2F%2Fe
  xample.com%2Faccounts%22%5D%7D%2C%7B%22type%22%3A%22payment_initiat
  ion%22%2C%22actions%22%3A%5B%22initiate%22%2C%22status%22%2C%22canc
  el%22%5D%2C%22locations%22%3A%5B%22https%3A%2F%2Fexample.com%2Fpaym
  ents%22%5D%2C%22instructedAmount%22%3A%7B%22currency%22%3A%22EUR%22
  %2C%22amount%22%3A%22123.50%22%7D%2C%22creditorName%22%3A%22Merchan
  t123%22%2C%22creditorAccount%22%3A%7B%22iban%22%3A%22DE021001001093
  07118603%22%7D%2C%22remittanceInformationUnstructured%22%3A%22Ref%2
  0Number%20Merchant%22%7D%5D

14.1. OAuthパラメーター 登録

次のパラメーターは、 [RFC6749]によって確立された "OAuth Parameters"レジストリ [IANA.OAuth.Parameters]に 登録されています。¶

名前:

authorization_details¶

パラメーター使用場所:

認可リクエスト、トークンリクエスト、トークン レスポンス¶

変更管理者:

IETF¶

参照:

RFC 9396¶

14.2. JSON Web Tokenクレーム 登録

次の値は、[RFC7519]によって 確立されたIANA "JSON Web Token Claims"レジストリに登録されています。¶

クレーム名:

authorization_details¶

クレーム説明:

クレーム authorization_detailsは、アクセストークンの権利を表すJSONオブジェクトのJSON配列を含みます。 各JSONオブジェクトには、特定の種類のリソースに関する認可要件を指定するためのデータが含まれます。¶

変更管理者:

IETF¶

参照:

RFC 9396のセクション9.1¶

14.3. OAuthトークン イントロスペクションレスポンス登録

次の値は、[RFC7662]によって確立されたIANA "OAuth Token Introspection Response"レジストリに登録されています。¶

名前:

authorization_details¶

説明:

メンバー authorization_detailsは、アクセストークンの権利を表すJSONオブジェクトのJSON配列を含みます。 各JSONオブジェクトには、特定の種類のリソースに関する認可要件を指定するためのデータが含まれます。¶

変更管理者:

IETF¶

参照:

RFC 9396のセクション9.2¶

14.4. OAuth認可 サーバーメタデータ登録

次の値は、[RFC8414]によって 確立された、[IANA.OAuth.Parameters]のIANA "OAuth Authorization Server Metadata"レジストリに登録されています。¶

メタデータ名:

authorization_details_types_supported¶

メタデータ説明:

ASがサポートする認可詳細タイプを含むJSON配列¶

変更管理者:

IETF¶

参照:

RFC 9396のセクション10¶

14.5. OAuth動的クライアント 登録メタデータ登録

次の値は、[RFC7591]によって 確立された、[IANA.OAuth.Parameters]のIANA "OAuth Dynamic Client Registration Metadata"レジストリに登録されています。¶

クライアントメタデータ名:

authorization_details_types¶

クライアントメタデータ説明:

クライアントが使用する認可詳細タイプを示します。¶

変更管理者:

IETF¶

参照:

RFC 9396のセクション10¶

14.6. OAuth拡張エラー 登録

次の値は、[RFC6749]によって 確立された、[IANA.OAuth.Parameters]のIANA "OAuth Extensions Error Registry"に登録されています。¶

名前:

invalid_authorization_details¶

使用場所:

トークンエンドポイント、認可エンドポイント¶

プロトコル拡張:

OAuth 2.0 Rich Authorization Requests¶

変更管理者:

IETF¶

参照:

RFC 9396のセクション5¶

A.1. OpenID Connect

OpenID Connect [OIDC]は、 JSONベースのclaimsリクエストパラメーターを指定しています。これは、クライアント （OpenID Connect Relying Partyとして動作）が受け取りたいクレームを、細かい粒度かつ プライバシーを保護する方法で指定し、それらのクレームを特定の配信機構、すなわちID Tokenまたは userinfoレスポンスに割り当てるために使用できます。¶

scope値openidと追加パラメーターclaimsの組み合わせは、 すべての非OIDC scope値と同じ方法で、authorization_detailsと併せて使用できます。¶

あるいは、OpenID Connect用の認可詳細タイプが存在する可能性があります。 このセクションは、そのような認可詳細タイプがどのように見えるかの例を示しますが、 この認可詳細タイプを定義することは、この仕様の範囲外です。¶

これらの仮想的な例は、認可プロセスのOpenID Connect部分に固有のすべての詳細を、 認可JSONオブジェクト内にカプセル化しようとするものです。¶

トップレベルフィールドは、[OIDC]で与えられた定義に基づいています。¶

claim_sets:

profileなど、 それぞれのscope値の置き換えとなる、事前定義されたクレームセットの名前¶

max_age:

最大認証経過時間¶

acr_values:

要求されるAuthentication Context Class Reference（ACR）値¶

claims:

[OIDC]で 定義されるclaims JSON構造¶

これは、いくつかのクレームセットに対する単純なリクエストです。¶

[
   {
      "type": "openid",
      "locations": [
         "https://op.example.com/userinfo"
      ],
      "claim_sets": [
         "email",
         "profile"
      ]
   }
]

より高度な例を図 26に示します。¶

[
   {
      "type": "openid",
      "locations": [
         "https://op.example.com/userinfo"
      ],
      "max_age": 86400,
      "acr_values": "urn:mace:incommon:iap:silver",
      "claims": {
         "userinfo": {
            "given_name": {
               "essential": true
            },
            "nickname": null,
            "email": {
               "essential": true
            },
            "email_verified": {
               "essential": true
            },
            "picture": null,
            "http://example.com/claims/groups": null
         },
         "id_token": {
            "auth_time": {
               "essential": true
            }
         }
      }
   }
]

A.2. リモート電子 署名

次の例は、ETSI TS 119 432 [ETSI]と、 リモート署名作成のためのCloud Signature Consortium（CSC）API [CSC]で示されたリモート電子署名の概念に基づいています。¶

[
   {
      "type": "sign",
      "locations": [
         "https://signing.example.com/signdoc"
      ],
      "credentialID": "60916d31-932e-4820-ba82-1fcead1c9ea3",
      "documentDigests": [
         {
            "hash": "sTOgwOm+474gFj0q0x1iSNspKqbcse4IeiqlDg/HWuI=",
            "label": "Credit Contract"
         },
         {
            "hash": "HZQzZmMAIWekfGH0/ZKW1nsdt0xg3H6bZYztgsMTLw0=",
            "label": "Contract Payment Protection Insurance"
         }
      ],
      "hashAlgorithmOID": "2.16.840.1.101.3.4.2.1"
   }
]

トップレベルフィールドには次の意味があります。¶

credentialID:

署名に使用される証明書の識別子¶

documentDigests:

署名される各文書のハッシュ（hashフィールド）を含む配列。 さらに、対応するlabelフィールドは、たとえばユーザー同意で使用するために、 それぞれの文書をユーザーに識別します。¶

hashAlgorithm:

ハッシュ値を計算するために使用されたアルゴリズム¶

ASは、この構造に列挙された文書の署名作成についてユーザーに同意を求めることが想定されます。 クライアントは、このプロセスの結果として発行されたアクセストークンを使用して、 それぞれの署名サービスの文書署名APIを呼び出し、実際に署名を作成します。このアクセストークンは、 ユーザーが同意したとおりに、クライアント、ユーザーID、およびハッシュ（および署名アルゴリズム）に バインドされます。¶

A.3. 税務データへのアクセス

この例は、たとえば信用力を判断するために第三者が市民の 納税申告書および所得証明にアクセスできるAPIから着想を得ています。¶

[
    {
        "type": "tax_data",
        "locations": [
            "https://taxservice.govehub.no.example.com"
        ],
        "actions":"read_tax_declaration",
        "periods": ["2018"],
        "duration_of_access": 30,
        "tax_payer_id": "23674185438934"
    }
]

トップレベルフィールドには次の意味があります。¶

periods:

クライアントがアクセスしたい期間¶

duration_of_access:

クライアントがデータにアクセスすることを意図する日数¶

tax_payer_id:

納税者の識別子（クライアントが知っている場合）¶

A.4. eHealth

これら2つの例は、ノルウェーのeHealthシステムで使用されるAPIの要件から着想を得ています。¶

このユースケースでは、理学療法士がローカルのElectronic Health Records（EHR）システムを使用して コンピューターの前に座っています。彼らは特定の患者の電子患者記録を見たいと考えており、 また、おそらく別の機関または全国的なサービスにある別のシステムから患者の診療記録エントリーを取得したいと考えています。 このデータへのアクセスはAPIによって提供されます。¶

APIでリクエストを認可するために必要な情報はEHRシステムだけが知っており、 APIに提示されなければなりません。¶

最初の例では、認可詳細オブジェクトは組織の識別子を含みます。 この場合、APIは、与えられた組織が機微なデータへのアクセスを与えるために 個人の健康情報を処理する法的根拠を持っているかどうかを知る必要があります。¶

"authorization_details": {
    "type": "patient_record",
    "requesting_entity": {
        "type": "Practitioner",
        "identifier": [
        {
            "system": "urn:oid:2.16.578.1.12.4.1.4.4",
            "value": "1234567"
        }],
        "practitioner_role": {
            "organization": {
                "identifier": {
                    "system": "urn:oid:2.16.578.1.12.4.1.2.101",
                    "type": "ENH",
                    "value": "[organizational number]"
                }
            }
        }
    }
}

2番目の例では、APIはリクエストを認可するためにより多くの情報を必要とします。 この場合、認可詳細オブジェクトは、保健機関およびリクエスト時点でユーザーが持つ現在の職業に関する 追加情報を含みます。この追加レベルの詳細は、認可とデータ最小化の両方に使用できます。¶

[
   {
      "type": "patient_record",
      "location": "https://fhir.example.com/patient",
      "actions": [
         "read"
      ],
      "patient_identifier": [
         {
            "system": "urn:oid:2.16.578.1.12.4.1.4.1",
            "value": "12345678901"
         }
      ],
      "reason_for_request": "Clinical treatment",
      "requesting_entity": {
         "type": "Practitioner",
         "identifier": [
            {
               "system": "urn:oid:2.16.578.1.12.4.1.4.4",
               "value": "1234567"
            }
         ],
         "practitioner_role": {
            "organization": {
               "identifier": [
                  {
                     "system": "urn:oid:2.16.578.1.12.4.1.2.101",
                     "type": "ENH",
                     "value": "<organizational number>"
                  }
               ],
               "type": {
                  "coding": [
                     {
                        "system":
                           "http://hl7.example.org/fhir/org-type",
                        "code": "dept",
                        "display": "Hospital Department"
                     }
                  ]
               },
               "name": "Akuttmottak"
            },
            "profession": {
               "coding": [
                  {
                     "system": "http://snomed.example.org/sct",
                     "code": "36682004",
                     "display": "Physical therapist"
                  }
               ]
            }
         }
      }
   }
]

フィールドの説明:¶

patient_identifier:

OID形式のシステム識別子（名前空間）と、 この名前空間内の実際の値から構成される患者の識別子。¶

reason_for_request:

ユーザーが特定のAPIにアクセスしたい理由。¶

requesting_entity:

アイデンティティ、ロール、および組織コンテキストによる リクエスト者の指定。このデータは、認可を容易にし、監査目的のために提供されます。¶

このユースケースでは、ASは患者ではないリクエスト者を認証し、 ポリシーに基づいてアクセスを承認します。¶