Skip to content

OAuth 2.0 Rich Authorization Requests

Internet Engineering Task Force (IETF)                    T. Lodderstedt
Request for Comments: 9396                                       yes.com
Category: Standards Track                                      J. Richer
ISSN: 2070-1721                                      Bespoke Engineering
                                                             B. Campbell
                                                           Ping Identity
                                                                May 2023

Abstract

本文書は、OAuth メッセージ内で詳細（fine-grained）な認可データを運ぶために使用される新しいパラメータ authorization_details を規定する。

Status of This Memo

本文書は Internet Standards Track 文書である。

本文書は Internet Engineering Task Force (IETF) の成果物である。本文書は IETF コミュニティの合意を表す。公開レビューを受け、Internet Engineering Steering Group (IESG) により出版が承認されている。Internet Standards に関する追加情報は RFC 7841 の Section 2 にある。

本文書の現在の状態、正誤表（errata）、およびフィードバックの提供方法に関する情報は、https://www.rfc-editor.org/info/rfc9396 から入手できる。

Copyright (c) 2023 IETF Trust and the persons identified as the document authors. All rights reserved.

本文書は、本文書の公開日時点で有効な BCP 78 および IETF Trust の「IETF 文書に関する法的規定」 https://trustee.ietf.org/license-info の適用を受ける。これらの文書には、本文書に関する権利および制限が記述されているため、注意深く確認されたい。本文書から抽出された Code Components は、Trust Legal Provisions の Section 4.e に記載される Revised BSD License の文言を含めなければならず、また Revised BSD License に記載のとおり、無保証で提供される。

Table of Contents

1. Introduction

"The OAuth 2.0 Authorization Framework" [RFC6749] は、OAuth client が要求する scope（すなわち、Access Token の制限された権能）を指定できる scope パラメータを定義している。この仕組みは、静的なシナリオや粗い粒度の認可要求（例えば「Resource Owner の profile への read アクセスをください」）を実装するには十分である。しかし、「Merchant A に 45 ユーロを送金できるようにしてください」や「directory A への read アクセスと file X への write アクセスをください」のような、より細かな粒度の認可要件を指定するには十分ではない。

本仕様は、client が JSON [RFC8259] のデータ構造の表現力を用いて、細かな粒度の認可要件を指定できるようにする新しいパラメータ authorization_details を導入する。

例えば、クレジット送金（複数の open banking の取り組みでは "payment initiation" と呼ばれる）の Authorization Request は、次のような JSON オブジェクトで表現できる。

{
  "type": "payment_initiation",
  "locations": [
    "https://example.com/payments"
  ],
  "instructedAmount": {
    "currency": "EUR",
    "amount": "123.50"
  },
  "creditorName": "Merchant A",
  "creditorAccount": {
    "bic": "ABCIDEFFXXX",
    "iban": "DE02100100109307118603"
  },
  "remittanceInformationUnstructured": "Ref Number Merchant"
}

Figure 1: Example of an Authorization Request for a Credit Transfer

このオブジェクトには、意図した支払いに関する詳細情報（例えば amount、currency、creditor）が含まれており、利用者に提示して同意を得るために必要となる。Authorization Server (AS) と、対応する Resource Server (RS)（payment initiation API を提供する）は、協調してこの同意を強制する。

open banking および electronic signing の領域における新たなユースケースから生じる課題について包括的に議論したものとしては、[Transaction-Auth] を参照されたい。

カスタムの認可要求を容易にすることに加えて、本仕様は、異なる API 間で利用できる共通データ型フィールドの集合も導入する。

1.1. Conventions and Terminology

本文書中のキーワード "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. Request Parameter "authorization_details"

request パラメータ authorization_details は、JSON 表記でオブジェクト配列を含む。各 JSON オブジェクトには、特定種類の resource に対する認可要件を指定するためのデータが含まれる。resource の種類またはアクセス要件は type フィールドにより決定される。type フィールドは次のとおり定義される。

  • type: authorization details type を示す文字列の識別子。\ type フィールドの値は、そのフィールドを含むオブジェクトに許容される内容を決定する。この値は、AS の文脈における当該 API に対して一意である。このフィールドは REQUIRED である。

authorization_details 配列は、同一の type を複数エントリとして含んでもよい（MAY）。

Figure 2 は、前掲の例データを用いた type が payment_initiation の authorization_details を示す。

[
  {
    "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"
  }
]

Figure 2: Example of "authorization_details" for a Credit Transfer

Figure 3 は、口座情報へのアクセスと、支払い開始の許可を同時に求める複合 request を示す。

[
  {
    "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"
  }
]

Figure 3: Example of "authorization_details" for a Combined Request

type フィールドが account_information および payment_initiation の JSON オブジェクトは、AS が同意を求めるために使用する、異なる authorization_details を表す。

Note: AS はこのデータを後続で対応する RS に提供する（Section 9 を参照）。

2.1. Authorization Details Types

AS は type パラメータ値の解釈、および type パラメータが許容するオブジェクトフィールドを制御する。ただし、type パラメータ値は一般に文書化され、開発者が利用することも意図されている。API 設計者は、曖昧さなく容易にコピーできる type 値を選ぶことが RECOMMENDED である。例えば、同じ見た目の文字に対して複数の Unicode code point が存在する glyph があり、開発者が AS の定義と異なる文字を入力してしまう可能性がある。混乱を減らす手段としては、値を ASCII [RFC0020] 文字に限定する、データ型値を機械可読な形で一覧提供する、または文書から直接 copy & paste するよう開発者に指示する、などがある。

アプリケーションまたは API が、open standard の場合のように複数のサーバにまたがってデプロイされることが想定される場合、API 設計者は、自身の管理下にある衝突耐性（collision-resistant）を持つ名前空間、例えば API 設計者が管理する URI を使用することが RECOMMENDED である。

以下の例は、実装が名前空間 https://scheme.example.org/ を利用して、衝突耐性のある type 値を確保する方法を示す。

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

Figure 4: Example of "authorization_details" with a URL as Type Identifier

2.2. Common Data Fields

本仕様は、異なる種類の API をまたいで利用できるよう設計された共通データフィールドの集合を定義する。本仕様は、API 定義においてこれら共通フィールドの使用を要求しない。代わりに、API 設計者が再利用できる汎用コンポーネントとして提供する。各フィールドの許容値は、特定の type 値により定義される保護対象 API によって決定される。

  • locations: resource または RS の場所を表す文字列配列。これらの文字列は通常、RS の場所を識別する URI である。このフィールドにより、client は特定の RS を指定できる（Section 12 で議論する）。
  • actions: resource に対して実行されるアクション種別を表す文字列配列。
  • datatypes: resource から要求されるデータ種別を表す文字列配列。
  • identifier: API で利用可能な特定 resource を示す文字列識別子。
  • privileges: resource において要求される権限の種類またはレベルを表す文字列配列。

複数の共通データフィールドを組み合わせて使用する場合、client が要求する permission は全ての値の積（組み合わせ）になる。すなわち、オブジェクトは、オブジェクト内に列挙された全ての actions 値を、列挙された全ての locations 値において、列挙された全ての datatypes 値に対して使用する request を表す。以下の例では、client は customer_information API において、顧客に属する contacts と photos の両方に対して read と write アクセスを要求している。この request が許可されれば、client は API により定義されるあらゆる権利の組み合わせ（例えば photos への read と contacts への write）を利用できると想定するだろう。

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

Figure 5: Example of "authorization_details" with Common Data Fields

client がアクセスをより細かく制御したい場合、複数のオブジェクトを送信できる。この例では、同一 API endpoint において、contacts への read アクセスと photos への write アクセスを求めている。この request が許可されても、contacts への 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"
    ]
  }
]

Figure 6: Example of "authorization_details" with Common Data Fields in Multiple Objects

API は、対応する authorization object の type に従うことを条件に、独自の拡張を定義してもよい（MAY）。API 設計者は、本仕様で定義された共通データフィールドと、API 固有フィールドを組み合わせて使用することが想定される。以下の非規範的例は、架空の 2 種類の API type 値に対して、共通フィールドと API 固有フィールドの双方を使用する例である。最初のアクセス request は、actions, locations, datatypes に加え、指定座標で撮影された写真へのアクセスを示す API 固有の geolocation フィールドを含む。2 つ目のアクセス request は、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"
  }
]

Figure 7: Example of "authorization_details" Using Common and Extension Data Fields

この request が承認されると、結果の Access Token のアクセス権は、上記と同様に、2 つの API ごとに要求されたアクセス種別の和集合になる。

3. Authorization Request

authorization_details の authorization request パラメータは、scope パラメータが同目的で使用されるあらゆる場所で、認可要件の指定に使用できる。例は次のとおり。

  • [RFC6749] に規定される authorization requests
  • [RFC8628] に規定される device authorization requests
  • [OID-CIBA] で定義される backchannel authentication requests

[RFC6749] で定義される authorization requests の場合、実装者は、フローの security / privacy / reliability を改善するために pushed authorization requests [RFC9126] の使用を検討してもよい（MAY）。詳細は Section 12, 13, 11.4 を参照。

パラメータのエンコーディングは、各文脈により決定される。[RFC6749] に基づく authorization request の文脈では、パラメータは Figure 8 に示すように、シリアライズされた JSON を application/x-www-form-urlencoded 形式でエンコードする（表示上の都合による改行のみ）。

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

Figure 8: Example of Authorization Request with "authorization_details"

authorization_details パラメータで提供されたデータに基づき、AS は利用者に対して要求されたアクセス権限への同意を求める。

Note: 利用者は、要求された authorization details の一部（サブセット）のみを許可することもあり得る。

Figure 9 では、client は口座情報へのアクセスと支払い開始を望んでいる。

[
  {
    "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"
  }
]

Figure 9: URL Decoded "authorization_details"

3.1. Relationship to the "scope" Parameter

authorization_details と scope は、同一の authorization request 内で、独立した認可要件を運ぶために併用できる。

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

AS は、与えられた authorization request に対して、これら 2 組の要件を互いに組み合わせて処理しなければならない（MUST）。AS がこれらパラメータをどのように組み合わせるかの詳細は、保護対象 API に固有であり、本仕様の範囲外である。

利用者の同意を収集する際、AS は、authorization request が表す統合された要件集合を提示しなければならない（MUST）。

resource owner が client に要求されたアクセスを許可した場合、AS は、対応する authorization_details（および該当する場合は scope 値）に紐づく token を client に発行する。

3.2. Relationship to the "resource" Parameter

[RFC8707] で定義される resource authorization request パラメータは、要求された scope を適用できる resource をさらに特定するために使用できる。resource パラメータは、AS が authorization_details の authorization request パラメータを処理する方法には影響しない。

4. Authorization Response

本仕様は、authorization response への拡張を定義しない。

5. Authorization Error Response

AS は、不明な authorization details type、または対応する type 定義に適合しない authorization details を処理してはならない（MUST NOT）。AS は処理を中止し、authorization_details 構造内のオブジェクトについて次のいずれかが真である場合、error invalid_authorization_details で client に応答しなければならない（MUST）。

  • 不明な authorization details type 値を含む。
  • 既知の type のオブジェクトだが、不明なフィールドを含む。
  • authorization details type に対して誤った型のフィールドを含む。
  • authorization details type に対して無効な値のフィールドを含む。
  • authorization details type に必要な必須フィールドが欠落している。

6. Token Request

authorization_details の token request パラメータは、client が AS に対して Access Token に割り当てたい authorization details を指定するために使用できる。AS は、基となる grant（grant types が authorization_code, refresh_token などの場合）または client のポリシー（grant_type が client_credentials の場合）が、要求された authorization details を伴う Access Token の発行を許可するかどうかを検査する。許可されない場合、AS は error code invalid_authorization_details（invalid_scope と同様）で request を拒否する。

6.1. Comparing Authorization Details

OAuth プロトコルの多くの操作では、request が以前の既存 request と比べて「より多い」か「より少ない」かに基づいて、AS と RS が security 上の判断を行う。例えば token を refresh する際、client は resource owner により以前に認可されたものより「少ない permission」を持つ新しい Access Token を要求できる。要求された Access Token は減らされた permission を伝えるが、resource owner の以前の認可自体は、そのような request によって変更されない。

authorization_details 内の各フィールドの意味論は、特定の API または API 群に固有の実装となるため、任意の 2 つの authorization detail request を比較する標準化された仕組みは存在しない。AS は、多くの場合に単純なオブジェクト比較へ依存すべきではない。request 内のいくつかのフィールドの交差が、付与されるアクセス権に副作用を与え得るためであり、それは API の設計やデプロイ方法に依存する。これは、いくつかの API で使用される scope 値と同様の効果である。

新しい request を既存 request と比較する際、AS は、そもそも request を許可する際に用いたのと同じ処理手法を用いて、resource owner が当該 request を認可する必要があるかどうかを判断できる。比較の詳細は、authorization request の type 定義に依存し、本仕様の範囲外であるが、共通のパターンを適用できる。

これを、継続している例で示す。Section 3 の例の authorization request は、利用者により承認されると、次の privilege に紐づいた Authorization Code の発行につながった。

  • list accounts
  • 1 つ以上の口座の残高へのアクセス
  • 1 つ以上の口座の取引へのアクセス
  • 支払いの開始、状態の確認、キャンセル

ここで client は、AS に対して、口座一覧へのアクセス privilege のみが割り当てられた Access Token を発行するよう、次のとおり request できる。

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

Figure 10: Example of "authorization_details" Reduced Privileges

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

  • 前の手順で発行された Authorization Code が、type が account_information の authorization details オブジェクトを含むことを検証する。
  • 承認済み actions の一覧が list_accounts を含むかどうかを検証する。
  • locations 値が、以前に承認された locations のみを含むことを検証する。

すべての検査が成功すれば、AS は減らされたアクセス集合を持つ要求された Access Token を発行する。

なお、この比較は、この特定の API type 定義に固有である。別の API type 定義では、異なる処理規則があり得る。例えば、ある actions 値が別の actions 値に紐づく権利を包含することがある。例えば、client が最初に write アクセスを持つ token を要求した場合、それはこの API への read と write の両方のアクセスを意味する。

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

Figure 11: Example of "authorization_details" Requesting "write" Access to an API

後に同じ client が、read アクセスの refresh request を行う。

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

Figure 12: Example of "authorization_details" Requesting "read" Access to an API

AS は type 値と actions 値を比較し、read アクセスが、以前に client に付与された write アクセスにより既にカバーされていることを判断する。

同じ API は、privileges の候補値として admin を設けるよう設計できる。本例では、結果の token が resource 上のあらゆる機能を実行できることを示すために admin を用いる。client がその API に対してそのような admin privilege を付与された場合、authorization_details は次のとおりである。

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

Figure 13: Example of "authorization_details" with "admin" Access to an API

AS は type 値を比較し、privileges 値が、以前に client に付与されていた read / write アクセスのあらゆる側面を包含することを見いだす。なお、他の API 定義では、privileges において値同士が互いを包含しないよう設計することもある。

次の例は、client が共通データ要素 locations（Section 2.2 を参照）を用いて、特定の RS に制限された Access Token の発行を request する方法を示す。継続している例では、client は、https://example.com/payments にある RS に適用可能な、type が payment_initiation の承認済み grant の全 permission を request できる。

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

Figure 14: Example of "authorization_details" Requesting an Audience-Restricted Access Token

7. Token Response

[RFC6749] で定義される token response パラメータに加えて、AS は resource owner により許可され、対応する Access Token に割り当てられた authorization_details も返さなければならない（MUST）。

token response で発行される Access Token に割り当てられる authorization details は、対応する token request の authorization_details パラメータにより決定される。client が authorization_details の token request パラメータを指定しない場合、AS は裁量で結果の authorization_details を決定する。

AS は、authorization_details の値を client に対して省略してもよい（MAY）。

継続している例では、次のようになる。

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": "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"
    }
  ]
}

Figure 15: Example Token Response

7.1. Enriched Authorization Details in Token Response

Access Token に付与される authorization details は、client が request した内容と異なる場合がある。利用者が client の要求より少ない内容を認可する場合に加えて、AS が authorization details オブジェクト内のデータを拡張（enrich）するユースケースがある。拡張が許容されるかどうか、およびその具体は、対応する authorization details type の定義の一部となる。

一例として、client が口座情報へのアクセスを求めるが、どの口座へアクセスできるかの決定を利用者に委ねる場合がある。認可プロセスの過程で、利用者は client にアクセスを許可したい自身の口座のサブセットを選択する。選択された口座を伝達する設計オプションの一つとして、AS はこの情報を対応する authorization details オブジェクトに追加できる。

その例では、要求された authorization_details パラメータは次のようになる。ここでは、空配列は、AS による拡張の過程でデータが追加される箇所のプレースホルダとして機能する。この例は説明目的のみであり、いかなる authorization details type の具体をこのように設計すべきだという嗜好を示すものではない。

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

Figure 16: Example of Requested "authorization_details"

その後、AS は authorization details オブジェクトを展開し、対応する口座識別子を追加する。

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
    }
  ]
}

Figure 17: Example of Enriched "authorization_details"

別の例として、client が医療記録へのアクセスを要求するが、request 時点では記録番号を知らない場合がある。この例では、client は望むアクセス種別を指定するが、そのアクセスの locations や identifier は指定しない。

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

Figure 18: Example of Requested "authorization_details"

利用者が AS と対話する際、利用者は client に渡す責任がある医療記録をどれにするかを選ぶ。この情報が Access Token とともに返される。

{
  "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/"]
    }
  ]
}

Figure 19: Example of Enriched "authorization_details"

Note: client は、特定の authorization details オブジェクトが拡張され得る可能性を、事前に認識しておく必要がある。この性質は、対応する authorization details type の定義の一部であると想定される。

8. Token Error Response

Token Error Response は、Section 5 に与えられた規則に適合しなければならない（MUST）。

9. Resource Servers

RS が認可プロセスで承認された authorization details を強制できるようにするため、AS はこのデータを RS に提供しなければならない（MUST）。AS は、JWT 形式の Access Token に authorization_details フィールドを追加してもよい（MAY）。あるいは token introspection response に追加してもよい。

9.1. JWT-Based Access Tokens

Access Token が JWT [RFC7519] の場合、AS は、特定の audience にフィルタした authorization details オブジェクトをトップレベルの claim として追加することが RECOMMENDED である。

AS は通常、RS が request 処理に必要とする追加の claim（例えば user ID、role、transaction 固有データ）も JWT に追加する。どの claim を特定の RS が必要とするかは、AS における RS 固有のポリシーにより定義される。

以下は、前掲の payment initiation の例に対する 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"
  }
}

Figure 20: Example of "authorization_details" in JWT-Based Access Token

この場合、AS は JWT ベースの Access Token に次の claim 例を追加した。

  • sub: client が payment initiation を求めている利用者を示す。
  • txn: provider example.com のサービス全体で transaction を追跡するための transaction id。
  • debtorAccount: debtor 口座を含む API 固有フィールド。例では、この口座は authorization_details では渡されず、認可プロセス中に利用者が選択した。user_role は、この特定の口座に対する利用者の role を伝える。この場合は owner である。このデータは payment API（RS）におけるアクセス制御に使用される。

9.2. Token Introspection

token introspection [RFC7662] は、RS が AS に問い合わせて Access Token に関する情報を得るための手段を提供する。AS が token に関する authorization detail 情報を response に含める場合、その情報は introspection response の JSON オブジェクトのトップレベル要素として authorization_details により伝達されなければならない（MUST）。

authorization_details 要素は、Section 2 で定義されたのと同じ構造を含まなければならない（MUST）。ただし introspection request を行う RS に合わせて、フィルタや拡張が行われる場合がある。

以下は、payment initiation の例に対する introspection response の例である。

{
  "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"
  }
}

Figure 21: Example of "authorization_details" in Introspection Response

10. Metadata

この機能のサポートを告知するため、AS metadata response [RFC8414] に、サポートする authorization details type の一覧を authorization_details_types_supported という metadata パラメータとして含める。これは JSON 配列である。

以下の例で示す。

{
  "...": "...",
  "authorization_details_types_supported": [
    "payment_initiation",
    "account_information"
  ]
}

Figure 22: Example of Server Metadata about the Supported Authorization Details

client は、authorization request 時に使用する authorization details type を、client registration metadata パラメータ authorization_details_types により示してもよい（MAY）。これは JSON 配列である。

以下の例で示す。

{
  "...": "...",
  "authorization_details_types": [
    "payment_initiation"
  ]
}

Figure 23: Example of Server Metadata about Authorization Details

AS に対する authorization details type の登録は、本仕様の範囲外である。

11. Implementation Considerations

11.1. Using Authorization Details in a Certain Deployment

特定のデプロイにおいて authorization details を使用するには、次の手順が必要になる。

  • authorization details type を定義する。
  • OAuth server metadata に authorization details type を公開する。
  • 利用者の同意プロンプトで authorization details をどのように表示するかを決める。
  • 必要に応じて、利用者の同意プロセス中に authorization details を拡張する（例：選択された口座を追加する、期限を設定する）。
  • 必要に応じて、authorization details が Access Token の内容または introspection response にどのように反映されるかを決める。
  • RS が authorization details、または authorization details から導出された token データをどのように処理するかを決める。
  • 必要に応じて、client に特定の authorization details type の使用を許可する（entitle）。

11.2. Minimal Implementation Support

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

  • OAuth server metadata における、サポートする authorization details type の告知をサポートする。
  • 本仕様に適合した authorization request において authorization_details パラメータを受け付ける。
  • grant の一部として、同意された authorization details の保存をサポートする。
  • Access Token および token introspection response に authorization details を追加して RS に利用可能にするためのデフォルト動作を実装する（scope 値と同様）。これは、あらゆる grant type で動作すべきであり（SHOULD）、特に authorization_code と refresh_token で動作すべきである。

authorization details の処理と提示は、authorization details type により大きく異なる。そのため実装は、対応する挙動のカスタマイズをサポートすべきである（SHOULD）。特に実装は、デプロイが次を行えるようにすべきである。

  • authorization details の提示方法を決定する。
  • 利用者同意プロセス中に、要求された authorization details を修正する（例：フィールドの追加）。
  • 要求されたものと既存の authorization details をマージする。

このようなカスタマイズをサポートする一つのアプローチとしては、拡張モジュールを登録できる仕組みを用意する方法がある。各モジュールは、対応する利用者同意のレンダリング、および、構造化 Access Token や token introspection response により RS に必要なデータを提供するための変換を担う。

11.3. Use of Machine-Readable Type Schemas

実装は、authorization details type の定義のために機械可読な schema 言語を用い、そのような schema に対して authorization details オブジェクトの生成および検証を容易にすることを、デプロイに許容する場合がある。例えば、authorization details type が JSON Schemas [JSON.Schema] で定義される場合、JSON Schema の識別子を、対応する authorization details オブジェクトの type 値として使用できる。

ただし、type 値は AS により理解され、必要な範囲で client と RS により理解される識別子である。本仕様は、type 値が機械可読 schema 形式を指すこと、またはシステム内のいずれの当事者（client、AS、RS など）が type フィールドの内容を参照（dereference）したり処理したりすることについて、いかなる仮定も置かない。

11.4. Large Requests

request パラメータまたは request object に authorization_details を含む authorization request URI は非常に長くなり得る。したがって実装者は、[RFC9126] で定義される pushed request object の仕組みと組み合わせて、[RFC9101] で定義される request_uri パラメータを用い、信頼性と安全性のある形で authorization_details を渡すことを検討すべきである（SHOULD）。

以下は、HTTPS で保護された接続を介して authorization request データを直接 AS に送る pushed authorization request の例である。

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

Figure 24: Example of Large Request including "authorization_details"

12. Security Considerations

authorization_details パラメータは、OAuth の authorization request の場合、User-Agent を経由して送信されるため、利用者による改変に対して脆弱である。authorization_details の完全性（integrity）が懸念される場合、client は authorization_details を改ざん（tampering）や入れ替え（swapping）から保護しなければならない（MUST）。これは、[RFC9101] で定義される signed request objects を用いて request を署名する、または [RFC9101] で定義される request_uri パラメータを [RFC9126] と併用して request object の URI を AS に渡すことで達成できる。

authorization_details パラメータ内の文字列比較はすべて [RFC8259] に定義されるとおりに行うものとする。文字列値の同等性を評価するにあたり、追加の変換や正規化を行ってはならない。

共通データフィールド locations により、client は特定の認可をどこで使用する意図があるかを指定できる。すなわち、permission を RS に明確に割り当てることが可能になる。複数の RS が存在する状況では、audience restriction により、意図しない client の認可（例：read の scope 値が email と cloud service の双方に適用可能になってしまう）を防ぐ。

AS は、injection attack を防ぐため、authorization_details 内で渡されるデータを適切にサニタイズし、取り扱わなければならない（MUST）。

[RFC6749], [RFC7662], [RFC8414] の Security Considerations も適用される。

13. Privacy Considerations

実装者にとって、privacy を保護する形で authorization details を設計し、使用することは特に重要である。

authorization_details に含まれる機微な個人データは、例えば referrer header を通じて漏えいしないよう防止されなければならない。実装オプションには、[RFC9101] で定義される encrypted request objects、または [RFC9126] と [RFC9101] の request_uri パラメータを利用して、client と AS の間で end-to-end に暗号化された接続を介して authorization_details を送信する方法が含まれる。後者はアプリケーション層の暗号化を必要としないが、client と AS の間で追加のメッセージ交換が必要になる。

request データが暗号化されていても、攻撃者が AS を利用して利用者データを学習できる場合がある。攻撃者が制御するデバイス上の authorization request に暗号化された request データを注入し、AS の利用者同意画面を通じて（復号された）利用者データを平文で表示させることができる。実装はこの攻撃ベクトルを考慮し、適切な対策（例えばデータの一部のみを表示する、可能であれば想定する利用者コンテキストが同一のままかどうかを判断する（利用者認証後））を実装する必要がある。

AS は、client または RS と authorization_details を共有する際の privacy 上の影響を考慮する必要がある。AS は、ローカルポリシーにより決定される「知る必要がある（need to know）」範囲でのみこのデータを共有すべきである（SHOULD）。

14. IANA Considerations

14.1. OAuth Parameters Registration

次のパラメータが、「OAuth Parameters」レジストリ [IANA.OAuth.Parameters]（[RFC6749] により設立）に登録された。

  • Name: authorization_details
  • Parameter Usage Location: authorization request, token request, token response
  • Change Controller: IETF
  • Reference: RFC 9396

14.2. JSON Web Token Claims Registration

次の値が、IANA の「JSON Web Token Claims」レジストリ（[RFC7519] により設立）に登録された。

  • Claim Name: authorization_details
  • Claim Description: authorization_details claim は、Access Token の権利を表す JSON オブジェクト配列を含む。各 JSON オブジェクトには、特定種類の resource に対する認可要件を指定するためのデータが含まれる。
  • Change Controller: IETF
  • Reference: RFC 9396 の Section 9.1

14.3. OAuth Token Introspection Response Registration

次の値が、IANA の「OAuth Token Introspection Response」レジストリ（[RFC7662] により設立）に登録された。

  • Name: authorization_details
  • Description: authorization_details 要素は、Access Token の権利を表す JSON オブジェクト配列を含む。各 JSON オブジェクトには、特定種類の resource に対する認可要件を指定するためのデータが含まれる。
  • Change Controller: IETF
  • Reference: RFC 9396 の Section 9.2

14.4. OAuth Authorization Server Metadata Registration

次の値が、IANA の「OAuth Authorization Server Metadata」レジストリ（[IANA.OAuth.Parameters]。 [RFC8414] により設立）に登録された。

  • Metadata Name: authorization_details_types_supported
  • Metadata Description: AS がサポートする authorization details type を含む JSON 配列
  • Change Controller: IETF
  • Reference: RFC 9396 の Section 10

14.5. OAuth Dynamic Client Registration Metadata Registration

次の値が、IANA の「OAuth Dynamic Client Registration Metadata」レジストリ（[IANA.OAuth.Parameters]。 [RFC7591] により設立）に登録された。

  • Client Metadata Name: authorization_details_types
  • Client Metadata Description: client が使用する authorization details type を示す。
  • Change Controller: IETF
  • Reference: RFC 9396 の Section 10

14.6. OAuth Extensions Error Registration

次の値が、IANA の「OAuth Extensions Error Registry」（[IANA.OAuth.Parameters]。 [RFC6749] により設立）に登録された。

  • Name: invalid_authorization_details
  • Usage Location: token endpoint, authorization endpoint
  • Protocol Extension: OAuth 2.0 Rich Authorization Requests
  • Change Controller: IETF
  • Reference: RFC 9396 の Section 5

15. References

15.1. Normative References

  • [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>.
  • [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, <https://www.rfc-editor.org/info/rfc7519>.
  • [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", RFC 7662, DOI 10.17487/RFC7662, October 2015, <https://www.rfc-editor.org/info/rfc7662>.
  • [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/info/rfc8174>.
  • [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, DOI 10.17487/RFC8414, June 2018, <https://www.rfc-editor.org/info/rfc8414>.
  • [RFC8628] Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, "OAuth 2.0 Device Authorization Grant", RFC 8628, DOI 10.17487/RFC8628, August 2019, <https://www.rfc-editor.org/info/rfc8628>.
  • [RFC8707] Campbell, B., Bradley, J., and H. Tschofenig, "Resource Indicators for OAuth 2.0", RFC 8707, DOI 10.17487/RFC8707, February 2020, <https://www.rfc-editor.org/info/rfc8707>.
  • [RFC0020] Cerf, V., "ASCII format for network interchange", STD 80, RFC 20, DOI 10.17487/RFC0020, October 1969, <https://www.rfc-editor.org/info/rfc20>.

15.2. Informative References

  • [CSC] Cloud Signature Consortium, "Architectures and protocols for remote signature applications", Version 1.0.4.0, June 2019, <https://cloudsignatureconsortium.org/wp-content/uploads/2020/01/CSC_API_V1_1.0.4.0.pdf>.
  • [ETSI] ETSI, "Electronic Signatures and Infrastructures (ESI); Protocols for remote digital signature creation", V1.1.1, ETSI TS 119 432, March 2019, <https://www.etsi.org/deliver/etsi_ts/119400_119499/119432/01.01.01_60/ts_119432v010101p.pdf>.
  • [IANA.OAuth.Parameters] IANA, "OAuth Parameters", <https://www.iana.org/assignments/oauth-parameters>.
  • [JSON.Schema] OpenJS Foundation, "JSON Schema", <https://json-schema.org/>.
  • [OID-CIBA] Fernandez, G., Walter, F., Nennker, A., Tonge, D., and B. Campbell, "OpenID Connect Client-Initiated Backchannel Authentication Flow - Core 1.0", 1 September 2021, <https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html>.
  • [OIDC] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, "OpenID Connect Core 1.0 incorporating errata set 1", 8 November 2014, <https://openid.net/specs/openid-connect-core-1_0.html>.
  • [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, <https://www.rfc-editor.org/info/rfc6749>.
  • [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", RFC 7591, DOI 10.17487/RFC7591, July 2015, <https://www.rfc-editor.org/info/rfc7591>.
  • [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, <https://www.rfc-editor.org/info/rfc8259>.
  • [RFC9101] Sakimura, N., Bradley, J., and M. Jones, "The OAuth 2.0 Authorization Framework: JWT-Secured Authorization Request (JAR)", RFC 9101, DOI 10.17487/RFC9101, August 2021, <https://www.rfc-editor.org/info/rfc9101>.
  • [RFC9126] Lodderstedt, T., Campbell, B., Sakimura, N., Tonge, D., and F. Skokan, "OAuth 2.0 Pushed Authorization Requests", RFC 9126, DOI 10.17487/RFC9126, September 2021, <https://www.rfc-editor.org/info/rfc9126>.
  • [Transaction-Auth] Lodderstedt, T., "Transaction Authorization or why we need to re-think OAuth scopes", 20 April 2019, <https://medium.com/oauth-2/transaction-authorization-or-why-we-need-to-re-think-oauth-scopes-2326e2038948>.

Appendix A. Additional Examples

A.1. OpenID Connect

OpenID Connect [OIDC] は、client（OpenID Connect Relying Party として動作）が受け取りたい claims を、細かな粒度で privacy を保護する形で指定し、さらにそれらの claims を特定の配信メカニズム（すなわち ID Token または userinfo response）に割り当てるために使用できる、JSON ベースの claims request パラメータを規定する。

openid という scope 値と、追加パラメータ claims の組み合わせは、authorization_details と同様に、あらゆる非 OIDC の scope 値と併用して使用できる。

代替として、OpenID Connect のための authorization details type が存在してもよい。本節は、そのような authorization details type がどのようなものになり得るかの例を示すが、この authorization details type を定義することは本仕様の範囲外である。

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

トップレベルのフィールドは、[OIDC] に与えられる定義に基づく。

  • claim_sets: 事前定義された claim set の名前。profile のような対応する scope 値の代替。
  • max_age: Maximum Authentication Age
  • acr_values: 要求される Authentication Context Class Reference (ACR) 値
  • claims: [OIDC] で定義される claims の JSON 構造

これは、いくつかの claim set に対するシンプルな request である。

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

Figure 25: Example of OpenID Connect Request Utilizing "authorization_details"

Note: locations は userinfo endpoint の location を指定する。これは、OpenID Connect において client（Relying Party）が、claims を取得するために Access Token を使用する唯一の場所であるためである。

より高度な例を Figure 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
        }
      }
    }
  }
]

Figure 26: Advanced Example of OpenID Connect Request Utilizing "authorization_details"

A.2. Remote Electronic Signing

次の例は、ETSI TS 119 432 [ETSI] で示された remote electronic signing の概念、および Cloud Signature Consortium (CSC) の remote signature creation 用 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"
  }
]

Figure 27: Example of Electronic Signing

トップレベルのフィールドは次の意味を持つ。

  • credentialID: 署名に使用する証明書の identifier
  • documentDigests: 署名対象の各 document の hash（hash フィールド）を含む配列。加えて、対応する label フィールドは、利用者に対して各 document を識別できるようにする（例：利用者同意で使用する）。
  • hashAlgorithm: hash 値の計算に使用された algorithm

AS は、構造内に列挙された document に対する署名作成について、利用者に同意を求めることが想定される。client は、プロセスの結果として発行された Access Token を用いて、対応する signing service における document signature API を呼び出し、実際に署名を作成する。この Access Token は、client、user ID、および利用者が同意した hash（および signature algorithm）に紐づく。

A.3. Access to Tax Data

この例は、市民の tax declarations と income statements への第三者アクセスを許可する 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"
  }
]

Figure 28: Example of Tax Data Access

トップレベルのフィールドは次の意味を持つ。

  • periods: client がアクセスしたい期間
  • duration_of_access: client がデータへアクセスする意図の期間（日数）
  • tax_payer_id: 納税者の identifier（client が把握している場合）

A.4. eHealth

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

このユースケースでは、理学療法士がローカルの Electronic Health Records (EHR) システムを用いてコンピュータの前に座っている。彼らは、特定の患者の電子患者記録を閲覧したく、さらに、別のシステム（例えば別機関のシステム、または国家サービス）にある患者の journal entry も取得したい。API によりこのデータへのアクセスが提供される。

API において request を認可するために必要な情報は EHR システムだけが把握しており、API に提示されなければならない。

最初の例では、authorization details オブジェクトは organization の identifier を含む。この場合、API は、与えられた organization が機微データへのアクセスを与えるに足る、個人の健康情報を処理するための法的根拠を有するかどうかを知る必要がある。

"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]"
        }
      }
    }
  }
}

Figure 29: eHealth Example

2 つ目の例では、API は request を認可するためにより多くの情報を必要とする。この場合、authorization details オブジェクトは、医療機関に関する追加情報、および request 時点で利用者が持つ現在の職務に関する情報を含む。この追加の詳細レベルは、認可とデータ最小化の双方に使用できる。

[
  {
    "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"
            }
          ]
        }
      }
    }
  }
]

Figure 30: Advanced eHealth Example

フィールドの説明:

  • patient_identifier: OID 形式（名前空間）の system identifier と、その名前空間内での実値から構成される患者の identifier
  • reason_for_request: 利用者が特定の API にアクセスしたい理由
  • requesting_entity: identity、role、組織コンテキストにより requester を指定する。これは認可を補助し、監査目的にも用いられる。

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

Acknowledgements

本仕様の準備中に貴重なフィードバックを提供してくれた Daniel Fett、Sebastian Ebling、Dave Tonge、Mike Jones、Nat Sakimura、Rob Otto に感謝する。

また、本仕様に対して貴重なフィードバックを提供してくれた Vladimir Dzhuvinov、Takahiko Kawasaki、Daniel Fett、Dave Tonge、Travis Spencer、Joergen Binningsboe、Aamund Bremer、Steinar Noem、Francis Pouatcha、Jacob Ideskog、Hannes Tschofenig、Aaron Parecki に感謝する。

Authors' Addresses

Torsten Lodderstedt

  • yes.com
  • Email: torsten@lodderstedt.net

Justin Richer

  • Bespoke Engineering
  • Email: ietf@justin.richer.org

Brian Campbell

  • Ping Identity
  • Email: bcampbell@pingidentity.com