%%% title = "OpenID Attachments 1.0 draft" abbrev = "openid-connect-4-ida-attachments-1_0" ipr = "none" workgroup = "eKYC-IDA" keyword = ["security", "openid", "identity assurance", "ekyc", "claims"]
[seriesInfo] name = "Internet-Draft"
value = "openid-connect-4-ida-attachments-1_0-00"
status = "standard"
[[author]] initials="T." surname="Lodderstedt" fullname="Torsten Lodderstedt" organization="sprind.org" [author.address] email = "torsten@lodderstedt.net"
[[author]] initials="D." surname="Fett" fullname="Daniel Fett" organization="Authlete" [author.address] email = "mail@danielfett.de"
[[author]] initials="M." surname="Haine" fullname="Mark Haine" organization="Considrd.Consulting Ltd" [author.address] email = "mark@considrd.consulting"
[[author]] initials="A." surname="Pulido" fullname="Alberto Pulido" organization="Santander" [author.address] email = "alberto.pulido@santander.co.uk"
[[author]] initials="K." surname="Lehmann" fullname="Kai Lehmann" organization="1&1 Mail & Media Development & Technology GmbH" [author.address] email = "kai.lehmann@1und1.de"
[[author]] initials="K." surname="Koiwai" fullname="Kosuke Koiwai" organization="KDDI Corporation" [author.address] email = "ko-koiwai@kddi.com"
%%%
.# Abstract
このドキュメントは，JSON ペイロードのコンテキストでバイナリデータを表現する方法を定義する．これは自然人のアイデンティティに関連する新しい添付ファイルを定義する OpenID Connect の拡張として，またはバイナリデータ要素を持つ他の JSON コンテキストで使用できる．この仕様は，自然人の ID に関連する新しい添付ファイルについて定義する，OpenID Connect の拡張を定義する． 本仕様と前のドラフトは，OpenID Foundation の eKYC および Identity Assurance ワーキンググループの作業である．
.# Introduction {#Introduction}
この仕様では，さまざまなコンテキストで使用するための JWT クレームとして添付ファイル要素を定義する．
添付ファイル要素は， [@OpenID4IDA] で行われた作業，特に ID 保証プロセスの一部として使用されるさまざまなエビデンスの画像を含める方法に触発されたものである．ただし，JSON 以外の構造化データを埋め込んだり参照したりする機能が役立つケースが他にもあると予想される．
.# Warning
This document is not an OIDF International Standard. It is distributed for review and comment. It is subject to change without notice and may not be referred to as an International Standard. Recipients of this draft are invited to submit, with their comments, notification of any relevant patent rights of which they are aware and to provide supporting documentation.
.# Foreword
The OpenID Foundation (OIDF) promotes, protects and nurtures the OpenID community and technologies. As a non-profit international standardizing body, it is comprised by over 160 participating entities (workgroup participant). The work of preparing implementer drafts and final international standards is carried out through OIDF workgroups in accordance with the OpenID Process. Participants interested in a subject for which a workgroup has been established have the right to be represented in that workgroup. International organizations, governmental and non-governmental, in liaison with OIDF, also take part in the work. OIDF collaborates closely with other standardizing bodies in the related fields.
Final drafts adopted by the Workgroup through consensus are circulated publicly for the public review for 60 days and for the OIDF members for voting. Publication as an OIDF Standard requires approval by at least 50% of the members casting a vote. There is a possibility that some of the elements of this document may be subject to patent rights. OIDF shall not be held responsible for identifying any or all such patent rights.
.# Notational conventions
The keywords "shall", "shall not", "should", "should not", "may", and "can" in this document are to be interpreted as described in ISO Directive Part 2 [@!ISODIR2]. These keywords are not used as dictionary terms such that any occurrence of them shall be interpreted as keywords and are not to be interpreted with their natural language meanings.
{mainmatter}
このドキュメントでは，埋め込み添付ファイルと外部添付ファイルの使用方法を定義する．
Normative References については Section 9 参照．
このドキュメントでは，用語と定義は記載されていない．
Identity verification プロセス中でエビデンスが使用される場合，特定のドキュメントアーティファクト(そのエビデンスの画像など)を提示する必要があり，トラストフレームワークに応じて受信者が一定期間保存する必要があるかもしれない．これらのアーティファクトは，例えば，監査や品質管理中などの際に後から確認することができる．これらのアーティファクトには次のものが含まれるが，これらに限定されない:
- 検証プロセス自体を文章化/証明する，記入済みかつ署名済みフォームのスキャン
- エンドユーザーの identity を確認するために使用されるドキュメントのスキャンまたは写真
- 検証プロセスのビデオ録画
- 電子署名の証明書
OpenID Connect を利用していて RP から要求された場合，これらのアーティファクトは ID トークンの一部として含めることが出来，特に [@OpenID4IDA] の verified_claims 要素の一部として含めることで，RP がこれらのアーティファクトを他の verified_claims 情報と一緒に保存することが出来る．
添付ファイルは JSON オブジェクト形式で表現される．本ドキュメントでは2種類の表現が可能である:
(コンテンツ自身を含む) ドキュメントのすべての情報は，以下の要素を持つ JSON オブジェクト内で提供される:
desc: OPTIONAL. ドキュメントの説明. ファイル名または単なるコンテンツの説明にすることができる．使用する言語は指定されていないが，通常 OP の基礎となるトラストフレームワークの管轄に拘束される．
content_type: REQUIRED. ドキュメントのコンテンツ (MIME) タイプ． [@!RFC6838] 参照．マルチパートまたはメッセージメディアタイプは許可されない．例: "image/png"
content: REQUIRED. ドキュメントコンテンツの Base64 エンコード表現. [@!RFC4648]参照.
以下の例は，UserInfo エンドポイントのレスポンス内に埋め込まれた添付ファイルを示す．添付ドキュメントの実際の内容は切り捨てられている:
<{{examples/response/embedded_attachments.json}}
注: 埋め込み添付ファイルはサイズが大きいため，アクセストークンまたは ID トークンなどのオブジェクトに埋め込む場合，必ずしも適切ではない．
External attachments は [@OpenID] で定義されている分散 Claim と似ている．外部ドキュメントへの参照は，以下の要素を持つ JSON オブジェクト内で提供される:
desc: OPTIONAL. ドキュメントの説明. ファイル名または単なるコンテンツの説明にすることができる．使用する言語は指定されていないが，通常 OP の基礎となるトラストフレームワークの管轄に拘束される．
url: REQUIRED. 添付ファイルを取得できる OAuth 2.0 保護されたリソースエンドポイント．プロバイダーは，このエンドポイントを保護し，権限のない者が添付ファイルを取得できないようにする必要がある (SHALL) (通常は，以下で説明するようにアクセストークンを要求する) ．エンドポイント URL は，暗号化ハッシュが digest 要素で与えられた値と一致する添付ファイルを返さなければならない (SHALL)．添付ファイルのコンテンツ MIME タイプは， [@!RFC6838] に従って，content-type HTTP レスポンスヘッダーで示されなければならない (SHALL)．マルチパートまたはメッセージメディアタイプは，使用しないものとする (SHALL NOT)．
access_token: OPTIONAL. 与えられた url から添付ファイルを取得できるようにする string タイプの Access Token．別のトークンタイプまたはメソッドが Client とネゴシエートされていない限り，添付ファイルは OAuth 2.0 Bearer Token Usage [@!RFC6750] プロトコルを使用してリクエストしなければならず (SHALL)， OP はこのメソッドをサポートしなければならない (SHALL)．他のトークンタイプの仕様は本ドキュメントの範囲外である．access_token 要素が利用できない場合，RP は Token Response で OP によって発行された Access Token を利用しなければならず (SHALL)，添付ファイルを要求する時，RP は UserInfo エンドポイントにアクセスするときと同じ方法を使用しなければならない (SHALL)．この要素の値が null の場合，添付ファイルを要求するために Access Token は使用されず，RP は Token Response によって発行された Access Token を使用してはならない (SHALL NOT)．この場合，OP は添付ファイルを保護するための他の有効な方法を組み込み，それに応じて RP に通知/指示しなければならない (SHALL)．
exp: OPTIONAL. "exp" (有効期限) クレームは，url 要素で定義されている，リソースエンドポイントから外部添付ファイルを使用できなくなる有効期限を識別する(たとえば，access_token が期限切れになるか，その時点でドキュメントが削除される可能性がある．)．実装者は，クロックスキューを考慮するために，通常は数分以下の小さな余裕を提供してもよい (MAY)．その値は，[@!RFC7519] に従って NumericDate の値を含む数値でなければならない (SHALL)．
digest: REQUIRED. ペイロードのバイトに対して取得されたドキュメントコンテンツの暗号化ハッシュの詳細を含む JSON オブジェクト(HTTP レスポンスの表現などではなく)．JSON オブジェクトは以下の要素を持つ:
alg: REQUIRED. 暗号化ハッシュの計算に使用されるアルゴリズムを指定する．アルゴリズムは，Client の登録または管理の間に RP と OP の間で事前にネゴシエートされている．value: REQUIRED. Base64 エンコード [@RFC4648] された暗号化ハッシュのバイト．
追加の外部添付ファイルやリソースを取得するためにアクセストークンが使用されないようにするために，外部添付ファイルのアクセストークンは要求されている特定のリソースへバインディングしなければならない (SHOULD)．例えば，url の値を audience としてアクセストークンと関連付けることができる．これにより，リソースサーバーは提示されたアクセストークンの audience がアクセスされた URL と一致するかを確認し，一致しない場合にアクセスを拒否することで，セキュリティを強化する．同じアイデアが Resource Indicators for OAuth 2.0 [@RFC8707] で説明されており，発行されるアクセストークンに関連付けられる1つ以上のリソースを指定するための resource リクエストパラメーターを定義している．
以下の例は external attachments を示す:
<{{examples/response/external_attachments.json}}
クライアントは，次の方法で，依存する各外部添付ファイルを検証しなければならない (SHALL) :
- オブジェクトに必須要素
url，digestが含まれていることを確認．
- リクエスト時の時刻が
exp要素で表される時刻より前であることを確認．
url要素で定義された URL がhttpsスキームを使用していることを確認．
digest要素にalgとvalueキーの両方が含まれていることを確認．
- オブジェクトの
url要素から添付ファイルを取得．
- 添付ファイルのコンテンツ MIME タイプが，content-type HTTP レスポンスヘッダーに示されていることを確認．
- MIME タイプが Multipart でないことを確認 ( [@RFC2046] のセクション5.1を参照) ．
- MIME タイプが "message" メディアタイプでないことを確認 ( [@RFC5322] を参照) ．
- 返却された添付ファイルに，
digestオブジェクトのvalueで指定された値とalg要素値で定義されたアルゴリズムと一致する暗号化ハッシュダイジェストがあることを確認．
これらの要件のいずれかが満たされない場合，添付ファイルの内容は使用せず，破棄し，信頼してはならない．
添付ファイルには，特定の Claim 名を使用して RP から要求されたよりも多くの個人情報が含まれる可能性が高いため，OP はいつどのような種類の添付ファイルが RP に転送されるかを，エンドユーザーが十分に認識していることを確認しなければならない (SHALL)．可能であれば，あるいは適用可能であれば，OP はエンドユーザーがトランザクションに同意する前に，これらの添付ファイルのコンテンツを確認できるようにするべきである (SHOULD)．
External attachments が [@!OpenID-Registration] または [@RFC7592] のいずれかを使用する OpenID Provider のコンテキストで使用される場合，クライアント登録またはクライアント管理のやり取りの一部として，以下のプロパティが利用できることが望ましい:
digest_algorithm: 選択されたダイジェストアルゴリズムを表す文字列値 (外部添付ファイル用) ．値は OP metadata で公表されているように，OP によってサポートされるダイジェスト アルゴリズムの 1 つでなければならない (SHALL)．このプロパティが設定されていない場合，デフォルトで sha-256 が使用される．
[@OpenID] 実装で添付ファイルが使用されている場合， openid-configuration でサポートされている添付ファイルに関する機能を公表するには，OP メタデータの追加要素が必要である([@!OpenID-Discovery] 参照):
attachments_supported: OP が添付ファイルをサポートする場合は必須 (REQUIRED)．OP でサポートされているすべての添付ファイルの種類を含む JSON 配列．可能な値は external と embedded． この配列が存在する場合，少なくとも 1 つのメンバーが必要である (SHALL)． 省略した場合，OP は添付ファイルをサポートしない．
digest_algorithms_supported: OP が外部添付ファイルをサポートする場合は必須．外部添付ファイルのダイジェスト オブジェクト内で alg プロパティとして使用できる，サポートされているすべてのダイジェストアルゴリズムを含む JSON 配列．OP が外部添付ファイルをサポートする場合，少なくともアルゴリズム sha-256 も OP によってサポートされなければならない (SHALL)．指定可能なダイジェスト/ハッシュ アルゴリズム名のリストは，IANA の [@!hash_name_registry] (established by [@RFC6920]) で管理されている．
以下は "openid-configuration" の部分的な例である:
{
...
"attachments_supported": [
"external",
"embedded"
],
"digest_algorithms_supported": [
"sha-256"
],
...
}このセクションには，このドキュメントで説明されているエビデンスと添付ファイルの例を示す JSON スニペットが含まれる．
このセクションでは，verified_claims のリクエストの例を示す．
<{{examples/request/verification_aml_with_attachments.json}}
RP は，Verified Claims とともに添付ファイルの受信を明示的にリクエストできる:
<{{examples/request/verification_with_attachments.json}}
他の Claims と同様に，添付ファイルの Claim もリクエスト内で essential としてマークすることができる．
このセクションでは，verified_claims を含むレスポンスの例を示す．
Note: Embedded attachments の例は切り捨てられた値を含む.
<{{examples/response/document_with_attachments.json}}
<{{examples/response/utility_statement_with_attachments.json}}
<{{examples/response/vouch_with_attachments.json}}
{backmatter}
<title>ISO/IEC Directives, Part 2 - Principles and rules for the structure and drafting of ISO and IEC documents</title> ISO/IEC <title>OpenID Connect Core 1.0 incorporating errata set 1</title> NRI Ping Identity Microsoft Google Salesforce <title>OpenID Connect for Identity Assurance 1.0</title> sprind.org Authlete Considrd.Consulting Ltd Santander 1&1 Mail & Media Development & Technology GmbH KDDI Corporation <title>ISO 3166-1:2020. Codes for the representation of names of countries and their subdivisions -- Part 1: Country codes</title> International Organization for Standardization <title>ISO 3166-3:2020. Codes for the representation of names of countries and their subdivisions -- Part 3: Code for formerly used names of countries</title> International Organization for Standardization <title>Machine Readable Travel Documents, Seventh Edition, 2015, Part 3: Specifications Common to all MRTDs</title> International Civil Aviation Organization <title>Recommendation ITU-T E.164</title> ITU-T <title>OpenID Connect Discovery 1.0 incorporating errata set 1</title> NRI Ping Identity Microsoft Illumila <title>OpenID Connect Dynamic Client Registration 1.0 incorporating errata set 1</title> NRI Ping Identity Microsoft <title>The Base16, Base32, and Base64 Data Encodings</title> SJD <title>The OAuth 2.0 Authorization Framework</title> Microsoft <title>Named Information Hash Algorithm Registry</title> IANAThe following people at yes.com and partner companies contributed to the concept described in the initial contribution to this document: Karsten Buch, Lukas Stiebig, Sven Manz, Waldemar Zimpfer, Willi Wiedergold, Fabian Hoffmann, Daniel Keijsers, Ralf Wagner, Sebastian Ebling, Peter Eisenhofer.
We would like to thank Julian White, Bjorn Hjelm, Stephane Mouy, Alberto Pulido, Joseph Heenan, Vladimir Dzhuvinov, Azusa Kikuchi, Naohiro Fujie, Takahiko Kawasaki, Sebastian Ebling, Marcos Sanz, Tom Jones, Mike Pegman, Michael B. Jones, Jeff Lombardo, Taylor Ongaro, Peter Bainbridge-Clayton, Adrian Field, George Fletcher, Tim Cappalli, Michael Palage, Sascha Preibisch, Giuseppe De Marco, Nick Mothershaw, Hodari McClain, Nat Sakimura and Dima Postnikov for their valuable feedback and contributions that helped to evolve this document.
Copyright (c) 2024 The OpenID Foundation.
The OpenID Foundation (OIDF) grants to any Contributor, developer, implementer, or other interested party a non-exclusive, royalty free, worldwide copyright license to reproduce, prepare derivative works from, distribute, perform and display, this Implementers Draft or Final Specification solely for the purposes of (i) developing specifications, and (ii) implementing Implementers Drafts and Final Specifications based on such documents, provided that attribution be made to the OIDF as the source of the material, but that such attribution does not indicate an endorsement by the OIDF.
The technology described in this document was made available from contributions from various sources, including members of the OpenID Foundation and others. Although the OpenID Foundation has taken steps to help ensure that the technology is available for distribution, it takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any independent effort to identify any such rights. The OpenID Foundation and the contributors to this document make no (and hereby expressly disclaim any) warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to this document, and the entire risk as to implementing this document is assumed by the implementer. The OpenID Intellectual Property Rights policy requires contributors to offer a patent promise not to assert certain patent claims against other contributors and against implementers. The OpenID Foundation invites any interested party to bring to its attention any copyrights, patents, patent applications, or other proprietary rights that may cover technology that may be required to practice this document.
[[ To be removed from the final specification ]]
-00 (WG document)
- Split this content from openid-connect-4-identity-assurance-1_0-13 WG document
- Add RFC4648 as normative reference
本仕様の翻訳は, OpenID ファウンデーションジャパン [@oidfj] KYC ワーキンググループ [@oidfj-kycwg], 翻訳・教育ワーキンググループ [@oidfj-trans] を主体として, 有志のメンバーによって行われました. 質問や修正依頼などについては, Github レポジトリー [@oidfj-github] にご連絡ください.
- Muneomi Sakuta (SoftBank Corp.)
- Yuu Kikuchi (OPTiM Corp.)
- Nov Matake (YAuth.jp)
- Kiyoshi Okuda (Fujitsu Ltd.)