| openid-connect-4-ida-attachments-1_0 | April 2024 | |
| Lodderstedt, et al. | Standards Track | [Page] |
This specification defines an extension of OpenID Connect that defines new attachments relating to the identity of a natural person. The work and the preceding drafts are the work of the eKYC and Identity Assurance working group of the OpenID Foundation.¶
This specification defines an attachment element as a JWT claim that MAY be used in various contexts.¶
Attachment element was inspired by the work done on [OpenID4IDA] and in particular how to include images of various pieces of evidence used as part of an identity assurance process, however, it is anticipated that there may be other cases where the ability to embed or refer to non-JSON structured data may be useful.¶
This definition was inspired by the work done on [OpenID4IDA] and in particular how to include images of various pieces of evidence used as part of an assurance process, however, it is anticipated that there may be other cases where the ability to embed or refer to non-JSON structured data may be useful.¶
Where attachments are used in identity verification process, specific document artifacts will be created and depending on the trust framework, will be required to be stored for a specific duration. These artifacts can later be reviewed during audits or quality control for example. These artifacts include, but are not limited to:¶
When requested by the RP, these artifacts can be attached to the Verified Claims response allowing the RP to store these artifacts along with the Verified Claims information.¶
An attachment is represented by a JSON object. This specification allows two types of representations:¶
All the information of the document (including the content itself) is provided within a JSON object having the following elements:¶
desc: OPTIONAL. Description of the document. This can be the filename or just an explanation of the content. The used language is not specified, but is usually bound to the jurisdiction of the underlying trust framework of the OP.¶
content_type: REQUIRED. Content (MIME) type of the document. See [RFC6838]. Multipart or message media types are not allowed. Example: "image/png"¶
content: REQUIRED. Base64 encoded representation of the document content.¶
txn: OPTIONAL. Identifier referring to the verification or validation transaction that generated a particular attachment. When used in the context of an [OpenID4IDA] response the OP SHOULD ensure this matches a txn contained within check_method when check_method needs to reference the embedded attachment.¶
The following example shows embedded attachments within a UserInfo endpoint response. The actual contents of the attached documents are truncated:¶
{
"sub": "248289761001",
"email": "janedoe@example.com",
"attachments": [
{
"desc": "Front of id document",
"content_type": "image/png",
"content": "Wkd0bWFtVnlhWFI2Wlc0Mk16VER2RFUyY0RRMWFUbDBNelJ1TlRjd31dzdaM1pTQXJaWGRsTXpNZ2RETmxDZwo="
},
{
"desc": "Back of id document",
"content_type": "image/png",
"content": "iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAYAAABytg0kAADSFsjdkhjwhAABJRU5ErkJggg=="
}
]
}
¶
Note: Due to their size, embedded attachments may not be appropriate when embedding in objects such as Access Tokens or ID Tokens.¶
External attachments are similar to distributed Claims as defined in [OpenID]. The reference to the external document is provided in a JSON object with the following elements:¶
desc: OPTIONAL. Description of the document. This can be the filename or just an explanation of the content. The used language is not specified, but is usually bound to the jurisdiction of the underlying trust framework or the OP.¶
url: REQUIRED. OAuth 2.0 resource endpoint from which the attachment can be retrieved. Providers MUST protect this endpoint, ensuring that the attachment cannot be retrieved by unauthorized parties (typically by requiring an access token as described below). The endpoint URL MUST return the attachment whose cryptographic hash matches the value given in the digest element. The content MIME type of the attachment MUST be indicated in a content-type HTTP response header, as per [RFC6838]. Multipart or message media types SHALL NOT be used.¶
access_token: OPTIONAL. Access Token as type string enabling retrieval of the attachment from the given url. The attachment MUST be requested using the OAuth 2.0 Bearer Token Usage [RFC6750] protocol and the OP MUST support this method, unless another Token Type or method has been negotiated with the Client. Use of other Token Types is outside the scope of this specification. If the access_token element is not available, RPs MUST use the Access Token issued by the OP in the Token response and when requesting the attachment the RP MUST use the same method as when accessing the UserInfo endpoint. If the value of this element is null, no Access Token is used to request the attachment and the RP MUST NOT use the Access Token issued by the Token response. In this case the OP MUST incorporate other effective methods to protect the attachment and inform/instruct the RP accordingly.¶
exp: OPTIONAL. The "exp" (expiration time) claim identifies the expiration time on or after which the External Attachment will not be available from the resource endpoint defined in the url element (e.g. the access_token may expire or the document may be removed at that time). Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew. Its value MUST be a number containing a NumericDate value as per as per [RFC7519].¶
digest: REQUIRED. JSON object containing details of a cryptographic hash of the document content taken over the bytes of the payload (and not, e.g., the representation in the HTTP response). The JSON object has the following elements:¶
alg: REQUIRED. Specifies the algorithm used for the calculation of the cryptographic hash. The algorithm has been negotiated previously between RP and OP during Client Registration or Management.¶
value: REQUIRED. Base64-encoded [RFC4648] bytes of the cryptographic hash.¶
txn: OPTIONAL. Identifier referring to the verification or validation transaction that generated a particular attachment. When used in the context of an [OpenID4IDA] response the OP SHOULD ensure this matches a txn contained within check_method when check_method needs to reference the embedded attachment.¶
It is RECOMMENDED that access tokens for external attachments have a binding to the specific resource being requested so that the access token may not be used to retrieve additional external attachments or resources. For example, the value of url could be tied to the access token as audience. This enhances security by enabling the resource server to check whether the audience of a presented access token matches the accessed URL and reject the access when they do not match. The same idea is described in Resource Indicators for OAuth 2.0 [RFC8707], which defines the resource request parameter whereby to specify one or more resources which should be tied to an access token being issued.¶
The following example shows external attachments:¶
{
"verified_claims": {
"verification": {
"trust_framework":"eidas",
"assurance_level": "substantial",
"evidence": [
{
"type": "document",
"method": "pipp",
"time": "2012-04-22T11:30Z",
"document_details": {
"type": "idcard",
"issuer": {
"name": "Stadt Augsburg",
"country": "DE"
},
"document_number": "53554554",
"date_of_issuance": "2010-03-23",
"date_of_expiry": "2020-03-22"
},
"attachments": [
{
"desc": "Front of id document",
"digest": {
"alg": "sha-256",
"value": "qC1zE5AfxylOFLrCnOIURXJUvnZwSFe5uUj8t6hdQVM="
},
"url": "https://example.com/attachments/pGL9yz4hZQ",
"access_token": "ksj3n283dke",
"exp": 1676552089
},
{
"desc": "Back of id document",
"digest": {
"alg": "sha-256",
"value": "2QcDeLJ/qeXJn4nP+v3nijMgxOBCT9WJaV0LjRS4aT8="
},
"url": "https://example.com/attachments/4Ag8IpOf95"
},
{
"desc": "Signed document",
"digest": {
"alg": "sha-256",
"value": "i3O7U79LiyKmmesIgULKT2Q8LAxNO0CpwJVcbepaYf8="
},
"url": "https://example.com/attachments/4Ag8IpOf95",
"access_token": null,
"exp": 1676552189
}
]
}
]
},
"claims": {
"given_name": "Max",
"family_name": "Mustermann",
"birthdate": "1956-01-28"
}
}
}
¶
Clients MUST validate each external attachment they wish to rely on in the following manner:¶
url, digest.¶
exp element.¶
url element uses the https scheme.¶
url element in the object.¶
digest object's value key.¶
If any of these requirements are not met the content of the attachment SHOULD NOT be used, SHOULD be discarded and MUST NOT be relied upon.¶
As attachments will most likely contain more personal information than was requested by the RP with specific Claim names, an OP MUST ensure that the End-User is well aware of when and what kind of attachments are about to be transferred to the RP. If possible or applicable, the OP SHOULD allow the End-User to review the content of these attachments before giving consent to the transaction.¶
During Client Registration (see [OpenID-Registration]) as well as during Client Management [RFC7592] the following additional properties are available:¶
digest_algorithm: String value representing the chosen digest algorithm (for external attachments). The value MUST be one of the digest algorithms supported by the OP as advertised in the OP metadata. If this property is not set, sha-256 will be used by default.¶
If attachments are used in [OpenID] implementations an additional element of OP Metadata is required to advertise its capabilities with respect to supported attachments in its openid-configuration (see [OpenID-Discovery]):¶
attachments_supported: REQUIRED when OP supports attachments. JSON array containing all attachment types supported by the OP. Possible values are external and embedded. When present this array MUST have at least one member. If omitted, the OP does not support attachments.¶
digest_algorithms_supported: REQUIRED when OP supports external attachments. JSON array containing all supported digest algorithms which can be used as alg property within the digest object of external attachments. If the OP supports external attachments, at least the algorithm sha-256 MUST be supported by the OP as well. The list of possible digest/hash algorithm names is maintained by IANA in [hash_name_registry] (established by [RFC6920]).¶
This is an example openid-configuration snippet:¶
{
...
"attachments_supported": [
"external",
"embedded"
],
"digest_algorithms_supported": [
"sha-256"
],
...
}
¶
This section contains JSON snippets showing examples of evidences and attachments described in this document.¶
This section shows examples of requests for verified_claims.¶
{
"userinfo": {
"verified_claims": {
"verification": {
"trust_framework": {
"value": "de_aml"
},
"evidence": [
{
"type": {
"value": "document"
},
"method": {
"value": "pipp"
},
"document_details": {
"type": {
"values": [
"idcard",
"passport"
]
}
},
"attachments": null
}
]
},
"claims": {
"given_name": null,
"family_name": null,
"birthdate": null
}
}
}
}
¶
RPs can explicitly request to receive attachments along with the Verified Claims:¶
{
"userinfo": {
"verified_claims": {
"verification": {
"trust_framework": null,
"attachments": null
},
"claims": {
"given_name": null,
"family_name": null,
"birthdate": null
}
}
}
}
¶
As with other Claims, the attachment Claim can be marked as essential in the request as well.¶
This section shows examples of responses containing verified_claims.¶
{
"verified_claims": {
"verification": {
"trust_framework": "de_aml",
"time": "2012-04-23T18:25Z",
"verification_process": "f24c6f-6d3f-4ec5-973e-b0d8506f3bc7",
"evidence": [
{
"type": "document",
"method": "pipp",
"time": "2012-04-22T11:30Z",
"document_details": {
"type": "idcard",
"issuer": {
"name": "Stadt Augsburg",
"country": "DE"
},
"document_number": "53554554",
"date_of_issuance": "2010-03-23",
"date_of_expiry": "2020-03-22"
},
"attachments": [
{
"desc": "Front of id document",
"digest" : {
"alg": "sha-256",
"value": "n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg="
},
"url": "https://example.com/attachments/pGL9yz4hZQ"
},
{
"desc": "Back of id document",
"digest" : {
"alg": "sha-256",
"value": "/WGgOvT3fYcPwh4F5+gGeAlcktgIz7O1wnnuBMdKyhM="
},
"url": "https://example.com/attachments/4Ag8IpOf95"
}
]
}
]
},
"claims": {
"given_name": "Max",
"family_name": "Meier",
"birthdate": "1956-01-28",
"place_of_birth": {
"country": "DE",
"locality": "Musterstadt"
},
"nationalities": [
"DE"
],
"address": {
"locality": "Maxstadt",
"postal_code": "12344",
"country": "DE",
"street_address": "An der Weide 22"
}
}
}
}
¶
{
"verified_claims": {
"verification": {
"trust_framework": "de_aml",
"time": "2012-04-23T18:25Z",
"verification_process": "513645-e44b-4951-942c-7091cf7d891d",
"evidence": [
{
"type": "document",
"check_details": [
{
"check_method": "vpip"
}
],
"time": "2021-04-09T14:12Z",
"document_details": {
"type": "utility_statement",
"date_of_issuance": "2013-01-31",
"issuer": {
"name": "Stadtwerke Musterstadt",
"country": "DE",
"region": "Niedersachsen",
"street_address": "Energiestrasse 33"
}
},
"attachments": [
{
"desc": "scan of bill",
"content_type": "application/pdf",
"content": "iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAYAAABytg0kAADSFsjdkhjwhAABJRU5ErkJggg=="
}
]
}
]
},
"claims": {
"given_name": "Max",
"family_name": "Meier",
"birthdate": "1956-01-28",
"place_of_birth": {
"country": "DE",
"locality": "Musterstadt"
},
"nationalities": [
"DE"
],
"address": {
"locality": "Maxstadt",
"postal_code": "12344",
"country": "DE",
"street_address": "An der Weide 22"
}
}
}
}
¶
{
"verified_claims": {
"verification": {
"trust_framework": "uk_diatf",
"assurance_level": "high",
"assurance_process": {
"policy": "gpg45",
"procedure": "h1b"
},
"time": "2020-09-23T14:12Z",
"verification_process": "99476DA2-ACDC-5N13-10WC-26B415B52",
"evidence": [
{
"type": "vouch",
"check_details": [
{
"check_method": "vpip"
},
{
"check_method": "pvr"
}
],
"time": "2020-02-23T07:52Z",
"attestation": {
"type": "written_attestation",
"reference_number": "6485-1619-3976-6671",
"date_of_issuance": "2020-02-13",
"voucher": {
"given_name": "Peter",
"family_name": "Crowe",
"occupation": "Executive Principal",
"organization": "Kristin School"
}
},
"attachments": [
{
"desc": "scan of vouch",
"content_type": "application/pdf",
"content": "d16d2552e35582810e5a40e523716504525b6016ae96844ddc533163059b3067=="
}
]
}
]
},
"claims": {
"given_name": "Megan",
"family_name": "Howard",
"birthdate": "2000-01-31",
"place_of_birth": {
"country": "NZL"
},
"address": {
"locality": "Croydon",
"country": "UK",
"street_address": "69 Kidderminster Road"
}
}
}
}
¶
The following people at yes.com and partner companies contributed to the concept described in the initial contribution to this specification: 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 specification.¶
Copyright (c) 2023 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 specification 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 specification 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 specification 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 specification, and the entire risk as to implementing this specification 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 specification.¶
[[ To be removed from the final specification ]]¶
-00 (WG document)¶