| connect | T. Lodderstedt |
| Internet-Draft | D. Fett |
| Intended status: Standards Track | yes.com |
| Expires: October 26, 2019 | April 24, 2019 |
OpenID Connect for Identity Assurance
openid-connect-4-identity-assurance-02
This specification defines an extension of OpenID Connect for providing Relying Parties with verified person data. This extension is intended to be used to verify the identity of a person in compliance with a certain law.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on October 26, 2019.
Copyright (c) 2019 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
This specification defines an extension to OpenID Connect [OpenID] to address the use case of strong identity verification of a natural person in accordance with certain laws. Examples include Anti Money Laundering Laws, Telecommunication Acts, Anti Terror Laws, and regulations on trust services, such as eIDAS [eIDAS].
In such use cases, the Relying Parties (RPs) need to know the assurance level of the user claims attested by the OpenID Connect Providers (OPs) along with evidences related to the identity verification process (identity assurance).
Identity assurance signficantly differs from authentication assurance, which requires a different, currently unsupported, representation in the OpenID Connect protocol.
The assurance level for authentication is a property of a certain OpenID Connect transaction, determined by the authentication means employed and the underlying user account management processes. The acr claim as defined in Section 2 of the OpenID Connect specification [OpenID] is sufficient to convey this information.
The identity assurance for user claims, i.e. the binding of a certain claim value to the person controlling the respective user account, typically varies among the different user claims. For example, the assurance an OP typically will be able to attest for an e-mail address will be “self-asserted”, “verified by opt-in”, or “verified by the respective e-mail provider via an attribute exchange protocol”. The family name of a user, in contrast, might have been verified in accordance with the respective Anti Money Laundering Law by showing an ID Card to a trained employee of the OP operator.
Identity assurance therefore requires a way to convey assurance data along with and coupled to the respective user claims. This specification proposes a suitable representation and mechanisms the RP will utilize to request verified person data and accompanying identity assurance data.
This section defines some terms relevant to the topic covered in this documents, heavily inspired by NIST SP 800-63A [NIST-SP-800-63a].
The extension specified in this document shall
The scope of the extension is to define mechanisms to assert verified person data.
It SHALL be possible to use existing OpenID Connect claims and other extensions defined beside this extension within the same OpenID Connect transaction and especially to render the same ID token or other representations utilized to convey user claims. For example, OpenID Connect already defines additional claims to inform the RP of the verification status of the phone_number and email claims.
If necessary, this extension will introduce new user claims to cover user attributes not currently covered by OpenID Connect, one example is the place_of_birth.
The extension MUST allow the OP to attest verified and unverified claims in the same response.
The representation defined in this specification is intended to be used to provide RPs with verified person data via any appropriate channel. In the context of OpenID Connnect, verified person data can be attested in ID Tokens or as part of the User Info response. It is also possible to utilize the format described here in OAuth Token Introspection responses (see [RFC7662] and [I-D.ietf-oauth-jwt-introspection-response]) to provide resource servers with verified person data.
This extension defines a way to assert verified claims only. There is no need to cover self-asserted claims, or better put claims without further information about the assurance, since they are already covered by OpenID Connect Core [OpenID].
Even for asserting verified claims, this extension shall attempt to utilize existing OpenID Connect claims if possible and reasonable. It MUST, however, ensure developers cannot interpret non-verified claims as verified claims.
The representation defined in this extension SHALL allow RPs to obtain assertions about verified claims from different OPs using different trust frameworks.
This extension SHALL be usable by OPs operating under a regulation, such as eIDAS, as well as other OPs. The former, called "notified eID system" in eIDAS, can attest identity data without the need to provide further evidences since they are operating under a well-defined regulation with clearly defined liability. For example in case of eIDAS, the respective member state takes the liability for the identities asserted by its notified eID system. The latter do not operate under such well-defined conditions, which typically requires the RP to obtain more data about the identity verification process and assess its applicability in its own legal context.
From a technical perspective, this means this specification needs to support cases, where basically verified person data are provided along with the information about the regulatory framework (trust framework) the OP complies with and the respective level of assurance, whereas there shall also be support to externalize information about the identity verification process with the OP to the RP.
Note: data transfer between OP and RP requires a legal basis that MUST be established upfront or in the course of the OpenID process.
In order to fulfill the requirements of some jurisdictions on identity assurance, this specification defines the following claims for conveying user data (in addition to the claims defined in the OpenID Connect specification [OpenID]:
Strong identity verification typically requires the participants to keep an audit trail of the whole process.
This specification supports building an audit trail across the boundaries between OP and RP by introducing the claim transaction_id.
The transaction_id claim is a string value which
The OP MUST maintain a corresponding audit trail for any transaction which leads to the attestation of verified person data. Those details consist of
The OP MUST store the transaction data as long as it is required to store transaction data for auditing purposes by respective regulations.
The RP requests this claim like any other claim via the claims parameter or as part of a default claim set identified by a scope value.
This extension to OpenID Connect wants to ensure that RPs cannot mixup verified and unverified claims and incidentally process unverified claims as verified claims.
The representation proposed therefore provides the RP with the verified claims within a structured claim verified_person_data. This structured claim is composed of the verification evidences related to a certain verification process and the corresponding user claims which were verified in this process.
The verified_person_data claim consists of the following sub-elements:
This element contains the information about the process conducted to verify a person's identity and bind the respective person data to a user account.
The verification element consists of the following elements:
trust_framework: REQUIRED. String determing the trust framework governing the identity verification process and the identity assurance level of the OP.
An example value is eidas_loa_high, which denotes a notified eID system under eIDAS providing identity assurance at level of assurance "High".
Standardized values are defined in Trust Frameworks.
The trust_framework value determines what further data is provided to the RP in the verification element. A notified eID system under eIDAS, for example, would not need to provide any further data whereas an OP not governed by eIDAS would need to provide verification evidences in order to allow the RP to fulfill its legal obligations. An example of the latter is an OP acting under the German Anti-Money laundering law (de_aml).
date: CONDITIONALLY REQUIRED. Time stamp in ISO 8601:2004 YYYY-MM-DD format representing the date when identity verification took place.
id: CONDITIONALLY REQUIRED. Unique reference to the identity verification process as performed by the OP. Used for backtracing in case of disputes or audits. Note: In contrast to this field, the claim transaction_id refers to the transaction leading the OP to attest the user's verified identity data towards a RP.
method: CONDITIONALLY REQUIRED. Method utilized for identity verification - Depending on the value of "method", there will be different additional sub-elements with the name of the method in the verification element - possible values are
The following elements are contained in an identity_document sub-element.
country: String denoting the country where the document was issued, format: ISO 3166-1 Alpha-2, e.g. "DE".
type: REQUIRED. String denoting the type of the id document, standardized values are defined in Identity Documents.
The OP MAY use other than the predefined values in which case the RPs will either be unable to process the assertion, just store this value for audit purposes, or apply bespoken business logic to it.
issuer: REQUIRED. String representing the issuer of the identity document
number: REQUIRED. String representing the number of the identity document
date_of_issuance: CONDITIONALLY REQUIRED. The date the document was issued as ISO 8601:2004 YYYY-MM-DD format, if this attribute exists for the particular type of document.
date_of_expiry: CONDITIONALLY REQUIRED. The date the document will expire as ISO 8601:2004 YYYY-MM-DD format, if this attribute exists for the particular type of document.
method: The method used to verify the document, predefined values are given in Verification Methods
organization: CONDITIONALLY REQUIRED. String denoting the organization which performed the verification on behalf of the OP. Can be omitted if this is the OP itself.
agent: OPTIONAL. Agent (person) who conducted the verification. The agent may be identified by Name or an identifier which can be resolved into the agent’s name during an audit.
The following elements are contained in an eID sub-element:
country: REQUIRED. Country where the eID was issued: ISO 3166-1 Alpha-2, e.g. DE
type: String denoting the type of eID, standardized values are defined in Identity Documents.
identifier: REQUIRED. person identifier obtained by the OP from the eID system
The claims element contains the user claims which were verified by the process and according to the policies determined by the corresponding verification element.
The claims element MAY contain one or more of the following user claims as defined in Section 5.1 of the OpenID Connect specification [OpenID]
or of the following claims as defined in Section User Claims:
The claims element MAY also contain other claims given the value of the respective claim was verified in the verification process represented by the sibling verification element.
Verified person data can be requested on the level of individual user claims by utilzing the claims parameter as defined in Section 5.5. of the OpenID Connect specification [OpenID].
Bassically, the claim verified_person_data is added to the section userinfo or id_token of the claims parameter.
Since verified_person_data contains the effective user claims in a nested claims element, the syntax is extended to include expressions on nested elements as follows. The verified_person_data element includes a claims element, which in turn includes the desired user claims as keys with a null value. An example is shown in the following:
{
"userinfo":{
"verified_person_data":{
"claims":{
"given_name":null,
"family_name":null,
"birthdate":null,
}
}
}
}
Use of the claims parameter allows the RP to exactly select the user claims needed for its use case. This extension therefore allows RPs to fulfill the requirement for data minimization.
RPs MAY indicate that a certain claim is essential to the sucessful completion of the user journey by utilizing the essential field as defined in Section 5.5.1. of the OpenID Connect specification [OpenID]. The following example designates both given as well as family name as being essential.
{
"userinfo":{
"verified_person_data":{
"claims":{
"given_name":{"essential": true},
"family_name":{"essential": true},
"birthdate":null,
}
}
}
}
Note: A claims sub-element with value null is interpreted as a request for all possible claims. An example is shown in the following:
{
"userinfo":{
"verified_person_data":{
"claims":null
}
}
}
Note: The claims sub-element can be omitted, which is equivalent to a claims element whose value is null.
Note: If the claims sub-element is empty or contains a claim other than the claims listed in the Section claims, the OP will abort the transaction with an invalid_request error.
The RP MAY express requirements regarding the elements in the verification sub-element.
This, again, requires an extension to the syntax as defined in Section 5.5. of the OpenID Connect Core specification [OpenID] due to the nested nature of the verified_person_data claim.
Section 5.5.1 of the OpenID Connect Core specification [OpenID] defines a query syntax that allows for the member value of the claim being requested to be a JSON object with additional information/constraints on the claim. For doing so it defines three members (essential, value and values) with special query meanings and allows for other special members to be defined (while stating that any members that are not understood must be ignored).
This specification re-uses this mechanics and introduces a new such member max_age (see below).
To start with, the RP may limit the possible values of the elements trust_framework, identity_document, and identity_document/method by utilizing the value or values fields.
The following example shows that the RP wants to obtain an attestation based on AML and limited to users who were identified in a bank branch using government issued id documents.
{
"userinfo":{
"verified_person_data":{
"verification":{
"trust_framework":{
"value":"de_aml"
},
"identity_document":{
"type":{
"values":[
"idcard",
"passport"
]
},
"method":{
"value":"pipp"
}
}
},
"claims":null
}
}
}
The RP may also express a requirement regarding the age of the verification data, i.e., the time elapsed since the verification process asserted in the verification element has taken place.
This specification therefore defines a new member max_age.
max_age: OPTIONAL. Only applicable to claims that contain dates or timestamps. Defines the maximum time (in seconds) to be allowed to elapse since the value of the date/timestamp up to the point in time of the request. The IDP should make the calculation of elapsed time starting from the last valid second of the date value. The following is an example of a request for claims where the verification process of the data is not allowed to be older than 63113852 seconds.
The following is an example:
{
"userinfo":{
"verified_person_data":{
"verification":{
"date":{
"max_age":"63113852"
}
},
"claims":null
}
}
}
The OP SHOULD try to fulfill this requirement. If the verification data of the user is older than the requested max_age, the OP MAY attempt to refresh the user’s verification by sending her through a online identity verification process, e.g. by utilizing an electronic ID card or a video identification approach.
If the OP is unable to fulfill the requirement (even in case it is marked as being essential), it will provide the RP with the data available and the RP may decide how to use the data. The OP MUST NOT return an error in case it cannot return all claims requested as essential claims.
The following sections show examples of verified_person_data objects.
The first and second section show JSON snippets of the general identity assurance case, where the RP is provided with verification evidences for different verification methods along with the actual user claims.
The third section illustrate how the contents of this object could look like in case of a notified eID system under eIDAS, where the OP does not need to provide evidences of the identity verification process to the RP.
Subsequent sections contain examples for using the verified_person_data claim on different channels and in combination with other (non-verified) user claims.
{
"verified_person_data":{
"verification":{
"trust_framework":"de_aml",
"date":"2013-02-21",
"id":"676q3636461467647q8498785747q487",
"method":"identity_document",
"identity_document":{
"country":"DE",
"type":"idcard",
"issuer":"Stadt Augsburg",
"number":"53554554",
"date_of_issuance":"2012-04-23",
"date_of_expiry":"2022-04-22",
"method":"pipp",
"organization":"Deutsche Post AG",
"agent":"Steffen Schuster"
}
},
"claims":{
"given_name":"Max",
"family_name":"Meier",
"birthdate":"1956-01-28",
"place_of_birth":{
"country":"DE",
"locality":"Musterstadt"
},
"nationality":"DE",
"address":{
"locality":"Maxstadt",
"postal_code":"12344",
"country":"DE",
"street":"An der Sanddüne 22"
}
}
}
}
{
"verified_person_data":{
"verification":{
"trust_framework":"de_aml",
"date":"2013-02-21",
"id":"676q3636461467647q8498785747q487",
"method":"eID",
"eID":{
"country":"DE",
"type":"idcard",
"identifier":"1d464976-d1fc-4460-a2de-9796d2b120fc"
}
},
"claims":{
"given_name":"Max",
"family_name":"Meier",
"birthdate":"1956-01-28",
"place_of_birth":{
"country":"DE",
"locality":"Musterstadt"
},
"nationality":"DE",
"address":{
"locality":"Maxstadt",
"postal_code":"12344",
"country":"DE",
"street":"An der Sanddüne 22"
}
}
}
}
{
"verified_person_data":{
"verification":{
"trust_framework":"eidas_loa_substantial"
},
"claims":{
"given_name":"Max",
"family_name":"Meier",
"birthdate":"1956-01-28",
"place_of_birth":{
"country":"DE",
"locality":"Musterstadt"
},
"nationality":"DE",
"address":{
"locality":"Maxstadt",
"postal_code":"12344",
"country":"DE",
"street":"An der Sanddüne 22"
}
}
}
}
In this example we assume the RP uses the scope parameter to request the email address and , additionally, the claims parameter, to request verified person data.
The scope value is: scope=openid email
The value of the claims parameter is:
{
"userinfo":{
"verified_person_data":{
"claims":{
"given_name":null,
"family_name":null,
"birthdate":null
}
}
}
}
The respective user info response would be
HTTP/1.1 200 OK
Content-Type: application/json
{
"iss":"https://server.example.com",
"sub":"248289761001",
"email":"janedoe@example.com",
"email_verified":true,
"verified_person_data":{
"verification":{
"trust_framework":"de_aml",
"date":"2013-02-21",
"id":"676q3636461467647q8498785747q487",
"method":"identity_document",
"identity_document":{
"country":"DE",
"type":"idcard",
"issuer":"Stadt Augsburg",
"number":"53554554",
"date_of_issuance":"2012-04-23",
"date_of_expiry":"2022-04-22",
"method":"pipp",
"organization":"Deutsche Post AG",
"agent":"Steffen Schuster"
}
},
"claims":{
"given_name":"Max",
"family_name":"Meier",
"birthdate":"1956-01-28"
}
}
}
In this case, the RP requests verfied person data along with other user claims in the claims parameter and allocates the response to the ID Token (delivered from the token endpoint in case of grant type code).
The claims parameter value is
{
"id_token":{
"email":null,
"preferred_username":null,
"picture":null,
"verified_person_data":{
"claims":{
"given_name":null,
"family_name":null,
"birthdate":null
}
}
}
}
The respective ID Token could be
{
"iss":"https://server.example.com",
"sub":"24400320",
"aud":"s6BhdRkqt3",
"nonce":"n-0S6_WzA2Mj",
"exp":1311281970,
"iat":1311280970,
"auth_time":1311280969,
"acr":"urn:mace:incommon:iap:silver",
"email":"janedoe@example.com",
"preferred_username":"j.doe",
"picture":"http://example.com/janedoe/me.jpg",
"verified_person_data":{
"verification":{
"trust_framework":"de_aml",
"date":"2013-02-21",
"id":"676q3636461467647q8498785747q487",
"method":"identity_document",
"identity_document":{
"country":"DE",
"type":"idcard",
"issuer":"Stadt Augsburg",
"number":"53554554",
"date_of_issuance":"2012-04-23",
"date_of_expiry":"2022-04-22",
"method":"pipp",
"organization":"Deutsche Post AG",
"agent":"Steffen Schuster"
}
},
"claims":{
"given_name":"Max",
"family_name":"Meier",
"birthdate":"1956-01-28"
}
}
}
Note: line breaks for display purposes only
HTTP/1.1 200 OK
Content-Type: application/json
{
"iss":"https://server.example.com",
"sub":"248289761001",
"email":"janedoe@example.com",
"email_verified":true,
"_claim_names":{
"verified_person_data":"src1"
},
"_claim_sources":{
"src1":{
"JWT":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL3NlcnZlci5vd
GhlcmlkcC5jb20iLCJ2ZXJpZmllZF9wZXJzb25fZGF0YSI6eyJ2ZXJpZmljYXRpb24iOnsidHJ1c3RfZnJhb
WV3b3JrIjoiZWlkYXNfbG9hX3N1YnN0YW50aWFsIn0sImNsYWltcyI6eyJnaXZlbl9uYW1lIjoiTWF4IiwiZ
mFtaWx5X25hbWUiOiJNZWllciIsImJpcnRoZGF0ZSI6IjE5NTYtMDEtMjgifX19.sPDOj44--OdSwilFFVhpXZTSjmrGpEDSb2pSocitMsk"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"iss":"https://server.example.com",
"sub":"248289761001",
"email":"janedoe@example.com",
"email_verified":true,
"_claim_names":{
"verified_person_data":"src1"
},
"_claim_sources":{
"src1":{
"endpoint":"https://server.yetanotheridp.com/claim_source",
"access_token":"ksj3n283dkeafb76cdef"
}
}
}
The OP advertises its capabilities with respect to verified person data in its openid-configuration (see [OpenID-Discovery]) using the following new elements:
trust_frameworks_supported This is a JSON array containing all supported trust frameworks and assurance levels.
verified_person_data_supported This JSON array contains all claims supported within verified_person_data.
identity_documents_supported This JSON array contains all identity documents utilized by the OP for identity verification.
verification_methods_supported This element is a JSON array containing at the top level the verification methods as defined in Section verification. eID is a simple JSON string whereas identity_document is contained in a JSON object and is itself an array containing all identity document proofing methods employed by the respective OP.
This is an example openid-configuration snippet:
{
...
"trust_frameworks_supported":[
"nist_800_63A_ial_2",
"nist_800_63A_ial_3"
]
"verified_person_data_supported":[
"given_name",
"family_name",
"birthdate",
"place_of_birth",
"nationality",
"address"
],
"identity_documents_supported":[
"idcard",
"passport",
"driving_permit"
]
"verification_methods_supported":[
{
"identity_document":[
"pipp",
"sripp"
]
},
"eID"
]
...
}
The OP MUST support the claims parameter and needs to publish this in its openid-configuration using the claim claims_parameter_supported.
This specification introduces the request parameter purpose to allow a RP to state the purpose for the transfer of user data it is asking for.
purpose OPTIONAL. String describing the purpose for obtaining certain user data from the OP. The purpose MUST NOT be shorter than 3 characters and MUST NOT be longer than 300 characters. If these rules are violated, the authentication request MUST fail and the OP returns an error invalid_request to the RP.
The OP MUST display this purpose in the respective user consent screen(s) in order to inform the user about the designated use of the data to be transferred or the authorization to be approved.
If the parameter purpose is not present in the request, the OP MAY utilize a description that was pre-configured for the respective RP.
Note: In order to prevent injection attacks, the IDP MUST escape the text appropriately before it will be shown in a user interface. The IDP MUST expect special characters in the URL decoded purpose text provided by the RP. The IDP MUST ensure that any special characters in the purpose text cannot be used to inject code into the web interface of the OP (e.g. cross-site scripting, defacing). Proper escaping MUST be applied by the OP. The OP SHALL NOT remove characters from the purpose text to this end.
The following people at yes.com and partner companies contributed to the concept described in this document: Karsten Buch, Lukas Stiebig, Sven Manz, Waldemar Zimpfer, Willi Wiedergold, Fabian Hoffmann, Daniel Keijsers, Ralf Wagner, Sebastian Ebling, Peter Eisenhofer.
I would like to thank Marcus Sanz, Tom Jones, Mike Pegman, and Jeff Lombardo for their valuable feedback that helped to further shape this specification.
OP and RP MUST establish a legal basis before exchanging any personally identifiable information.
TBD
This section defines trust framework identifiers for use with this specification.
This section defines identity doccument identifiers for use with this specification.
This section defines identity doccument identifiers for use with this specification.
| [OpenID] | Sakimura, N., Bradley, J., Jones, M., de Medeiros, B. and C. Mortimore, "OpenID Connect Core 1.0 incorporating errata set 1", Nov 2014. |
| [OpenID-Discovery] | Sakimura, N., Bradley, J., de Medeiros, B. and E. Jay, "OpenID Connect Discovery 1.0 incorporating errata set 1", Nov 2014. |
| [eIDAS] | European Parliament, "REGULATION (EU) No 910/2014 OF THE EUROPEAN PARLIAMENT AND OF THE COUNCIL on electronic identification and trust services for electronic transactions in the internal market and repealing Directive 1999/93/EC", July 2014. |
| [I-D.ietf-oauth-jwt-introspection-response] | Lodderstedt, T. and V. Dzhuvinov, "JWT Response for OAuth Token Introspection", Internet-Draft draft-ietf-oauth-jwt-introspection-response-02, February 2019. |
| [NIST-SP-800-63a] | NIST, Fentony, James., Lefkovitz, Naomi., Danker, Jamie., Choong, Yee-Yin., Greene, Kristen. and Mary. Theofanos, "NIST Special Publication 800-63A, Digital Identity Guidelines, Enrollment and Identity Proofing Requirements", June 2017. |
| [OxfordPassport] | Cane, P. and Mary. Conaghan, "The New Oxford Companion to Law. ISBN 9780199290543.", 2008. |
| [RFC7662] | Richer, J., "OAuth 2.0 Token Introspection", RFC 7662, DOI 10.17487/RFC7662, October 2015. |
[[ To be removed from the final specification ]]
-02
-01
-00 (WG document)