| + | openid-connect-4-identity-assurance-1_0 | +July 2026 | +
| Lodderstedt, et al. | +Standards Track | +[Page] | +
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.¶
+This extension to OpenID Connect standardizes how relying parties request and receive identity information with additional assurance metadata. This document is aimed at enabling use cases requiring strong assurance, for example, to comply with regulatory requirements such as anti-money laundering laws or access to health data, risk mitigation, or fraud prevention.¶
+In such use cases, the relying party (RP) needs to understand the trustworthiness or assurance level of the claims about the end-user that the OpenID provider (OP) is willing to communicate, along with process-related information and evidence used to verify the end-user claims.¶
+The acr claim, as defined in section 2 of the OpenID Connect specification [OpenID], is suited to assure information about the authentication performed in an OpenID Connect transaction. Identity assurance, however, requires a different representation. While authentication is an aspect of an OpenID Connect transaction, assurance and associated verification and validation details, are properties of a certain claim or a group of claims. Several of them will typically be conveyed to the RP as the result of an OpenID Connect transaction.¶
For example, the assurance an OP typically will be able to give for an e-mail address will be “self-asserted” or "verified". The family name of an end-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 requires a way to convey assurance data along with and coupled to the respective claims about the end-user. This document defines a suitable representation and mechanisms the RP will utilize to request verified claims about an end-user along with assurance data and for the OP to represent these verified claims and accompanying assurance data.¶
+This document is a definition of the technical mechanism to allow a relying party to request one or more verified claim about the end-user and to enable an OpenID provider to provide a relying party with a verified claim ("the tools").¶
+Additional facets needed to deploy a complete solution for identity assurance, such as legal aspects (including liability), trust frameworks, or commercial agreements are out of scope. It is up to the particular deployment to complement the technical solution based on this document with the respective definitions ("the rules").¶
+Note: Although such aspects are out of scope, the aim of the specification is to enable implementations of the technical mechanism to be flexible enough to fulfill different legal and commercial requirements in jurisdictions around the world. Consequently, such requirements will be discussed in this document as examples.¶
+See section 13 for normative references.¶
+For the purposes of this document, the following terms and definitions apply.¶
+ +process in which an end-user provides evidence to an OpenID Connect provider (OP) or claim provider reliably identifying themselves, thereby allowing the OP or claim provider to assert that identification at a useful assurance level¶
+process conducted by the OP or a claim provider to verify the end-user's identity¶
+process in which the OP or a claim provider asserts identity data of a certain end-user with a certain assurance towards an RP, typically expressed by way of an assurance level. Depending on legal requirements, the OP can be required to provide evidence of the identity verification process to the RP¶
+claim about an end-user, typically a natural person, whose binding to a particular end-user account was verified in the course of an identity verification process¶
+server that can provide claim information about a entity; synonomous with "claims provider" in OpenID Connect core¶
+The RP will be able to request the minimal data set it needs (data minimization) and to express requirements regarding this data, the evidence and the identity verification processes employed by the OP.¶
+This extension will be usable by OPs operating under a certain regulation related to identity assurance, such as eIDAS, as well as other OPs operating without such a regulation.¶
+It is assumed that OPs operating under a suitable regulation can assure identity data without the need to provide further evidence since they are approved to operate according to well-defined rules with clearly defined liability. For example in the case of eIDAS, the peer review ensures eIDAS compliance and the respective member state assumes the liability for the identities asserted by its notified eID system.¶
+Every other OP not operating under such well-defined conditions could receive a request to provide the RP data about the identity verification process along with identity evidence to allow the RP to conduct their own risk assessment and to map the data obtained from the OP to other laws. For example, if an OP verifies and maintains identity data in accordance with an anti-money laundering law, an RP might choose to use the identity attributes in a different regulatory context, such as eHealth or the previously mentioned eIDAS.¶
+The concept of this document is that the OP can provide identity data along with metadata about the identity assurance process. It is the responsibility of the RP to assess this data and map it into its own legal context.¶
+From a technical perspective, this means this document allows the OP to provide verified claims along with information about the respective trust framework, but also supports the externalization of information about the identity verification process.¶
+The representation defined in this document can be used to provide RPs with verified claims about the end-user via any appropriate channel. In the context of OpenID Connect, verified claims can be provided in ID Tokens or as part of the UserInfo response. It is also possible to utilize the format described here in OAuth access tokens or token introspection responses to provide resource servers with verified claims.¶
+This extension is intended to be truly international and support identity assurance across different jurisdictions. The extension is therefore extensible to support various trust frameworks, identity evidence and assurance processes.¶
+In order to give implementers as much flexibility as possible, this extension can be used in conjunction with existing OpenID Connect claims and other extensions within the same OpenID Connect assertion (e.g., ID Token or UserInfo response) utilized to convey claims about end-users.¶
+For example, OpenID Connect [OpenID] defines claims for representing family name and given name of an end-user without a verification status. These claims can be used in the same OpenID Connect assertion beside verified claims represented according to this extension.¶
+In the same way, existing claims to inform the RP of the verification status of the phone_number and email claims can be used together with this extension.¶
Even for representing verified claims, this extension utilizes existing OpenID Connect claims if possible and reasonable. The extension will, however, ensure RPs cannot (accidentally) interpret unverified claims as verified claims.¶
+In order to fulfill the requirements of some jurisdictions on identity assurance, the OpenID Connect for IDA claims [OpenID4IDAClaims] specification defines a number of claims for conveying end-user data in addition to the claims defined in the OpenID Connect specification [OpenID].¶
+The basic idea is to use a container element, called verified_claims, to provide the RP with a set of claims along with the respective metadata and verification evidence related to the verification of these claims. This way, it is explicit which claims are verified, reducing the risk of RPs accidentally processing unverified claims as verified claims.¶
This document uses the [IDA-verified-claims] document as the definition of the schema for representation of assured digital identity attributes and identity assurance metadata.¶
+The following example would assert to the RP that the OP has verified the claims provided (given_name and family_name) according to an example trust framework trust_framework_example:¶
{
+ "verified_claims": {
+ "verification": {
+ "trust_framework": "trust_framework_example"
+ },
+ "claims": {
+ "given_name": "Max",
+ "family_name": "Meier"
+ }
+ }
+}
+¶
+This document requires that RPs use the schema defined in [IDA-verified-claims]. There are places in the JSON structure where that schema can be extended by implementers but deviation from the schema as defined would not be correct use of this document.¶
+A verified_claims element can be added to an OpenID Connect UserInfo response and/or an ID Token.¶
Here is an example of the payload of an ID token including verified claims:¶
+{
+ "iss": "https://server.example.com",
+ "sub": "248289761",
+ "aud": "https://rs.example.com/",
+ "exp": 1544645174,
+ "client_id": "s6BhdRkqt3_",
+ "verified_claims": {
+ "verification": {
+ "trust_framework": "example"
+ },
+ "claims": {
+ "given_name": "Max",
+ "family_name": "Mustermann"
+ }
+ }
+}
+¶
+An OP or Authorization Server (AS) can also include aggregated or distributed verified_claims in the above assertions (see Section 6 for more details).¶
Verified claims can be requested on the level of individual claims about the end-user by utilizing the claims parameter as defined in section 5.5 of the OpenID Connect specification [OpenID].¶
Note: A machine-readable definition of the syntax to be used to request verified_claims is given as JSON schema in [verified_claims_request.json], which can be used to automatically validate claims request parameters. The provided JSON schema files are a non-normative implementation of this document and any discrepancies that exist are either implementation bugs or interpretations.¶
To request verified claims, the verified_claims element is added to the userinfo or the id_token element of the claims parameter.¶
Since verified_claims contains the effective claims about the end-user in a nested claims element, the syntax is extended to include expressions on nested elements as follows. The verified_claims element includes a claims element, which in turn includes the desired claims as keys. For each claim, the value is either null (default), or an object. The object may contain restrictions using value or values as defined in [OpenID] and/or the essential key as described below. An example is shown in the following:¶
{
+ "userinfo": {
+ "verified_claims": {
+ "verification": {
+ "trust_framework": null
+ },
+ "claims": {
+ "given_name": null,
+ "family_name": null,
+ "birthdate": null
+ }
+ }
+ }
+}
+¶
+Use of the claims parameter allows the RP to request specified claims about the end-user needed for its use case. This allows RPs to fulfill the requirements for data minimization by requesting only claims needed for its use case.¶
Note: it is not possible to request sub-claims (for example the country subclaim of the address claim) using mechanisms from OpenID Connect Core or this document.¶
RPs can use the essential field as defined in section 5.5.1 of the OpenID Connect specification [OpenID]. The following example shows this for the family and given names.¶
{
+ "userinfo": {
+ "verified_claims": {
+ "verification": {
+ "trust_framework": null
+ },
+ "claims": {
+ "given_name": {
+ "essential": true
+ },
+ "family_name": {
+ "essential": true
+ },
+ "birthdate": null
+ }
+ }
+ }
+}
+¶
+RPs request verification data in the same way they request claims about the end-user. When the claims request parameter is being used, the syntax is based on the rules given in Section 5.3 and extends them for navigation into the structure of the verification element.¶
Elements within verification are requested by adding the respective element as shown in the following example:¶
{
+ "userinfo": {
+ "verified_claims": {
+ "verification": {
+ "trust_framework": null,
+ "time": null
+ },
+ "claims": {
+ "given_name": null,
+ "family_name": null,
+ "birthdate": null
+ }
+ }
+ }
+}
+¶
+It requests the trust framework the OP complies with and the date of the verification of the end-user claims.¶
+The RP shall explicitly request any data it wants the OP to add to the verification element.¶
Therefore, the RP shall set fields one step deeper into the structure if it wants to obtain evidence. One or more entries in the evidence array are used as filter criteria and templates for all entries in the result array. The following example shows a request asking for evidence of type document only.¶
{
+ "userinfo": {
+ "verified_claims": {
+ "verification": {
+ "trust_framework": null,
+ "time": null,
+ "evidence": [
+ {
+ "type": {
+ "value": "document"
+ },
+ "check_details": [
+ {
+ "check_method": {
+ "value": "pipp"
+ }
+ }
+ ],
+ "document_details": {
+ "type": null
+ }
+ }
+ ]
+ },
+ "claims": {
+ "given_name": null,
+ "family_name": null,
+ "birthdate": null
+ }
+ }
+ }
+}
+¶
+The example also requests the OP to add the respective check_method and the document_details elements (including data about the document type), for every evidence array member, to the resulting verified_claims claim.¶
A single entry in the evidence array represents a filter over elements of a certain evidence type. The RP therefore shall specify this type by including the type field including a suitable value sub-element value. The values sub-element shall not be used for the evidence/type field.¶
If multiple entries are present in evidence, these filters are linked by a logical OR.¶
check_details is an array of the processes that have been applied to the evidence. An RP can filter check_details by requesting a particular value for one or more of its sub-elements. If multiple entries for the same sub-element are present this acts as a logical OR between them.¶
assurance_details is an array representing how the evidence and check_details fulfill the requirements of the trust_framework. RP should only request this where they need to know this information. Where assurance_details has been requested by an RP the OP shall return the assurance_details element along with all sub-elements that it has. If an RP wants to filter what types of evidence and check_details they shall specify those to do so.¶
The RP can also request certain data within the document_details element to be present. This again follows the syntax rules used above:¶
{
+ "userinfo": {
+ "verified_claims": {
+ "verification": {
+ "trust_framework": null,
+ "time": null,
+ "evidence": [
+ {
+ "type": {
+ "value": "document"
+ },
+ "check_details": [
+ {
+ "check_method": null
+ }
+ ],
+ "document_details": {
+ "type": null,
+ "issuer": {
+ "country": null,
+ "name": null
+ },
+ "document_number": null,
+ "date_of_issuance": null
+ }
+ }
+ ]
+ },
+ "claims": {
+ "given_name": null,
+ "family_name": null,
+ "birthdate": null
+ }
+ }
+ }
+}
+¶
+The RP can limit the possible values of the elements trust_framework, evidence/check_details, and evidence/document_details/type by utilizing the value or values fields and the element evidence/type by utilizing the value field.¶
Note: Examples on the usage of a restriction on evidence/type were given in the previous section.¶
The following example shows how an RP requests claims either complying with trust framework gold or silver.¶
{
+ "userinfo": {
+ "verified_claims": {
+ "verification": {
+ "trust_framework": {
+ "values": [
+ "gold",
+ "silver"
+ ]
+ }
+ },
+ "claims": {
+ "given_name": null,
+ "family_name": null
+ }
+ }
+ }
+}
+¶
+The following example shows that the RP wants to obtain an attestation based on the German anti-money laundering law (trust framework de_aml) and limited to end-users who were identified in person (physical in person proofing - "check_method": "pipp") using either an idcard or a passport.¶
{
+ "userinfo": {
+ "verified_claims": {
+ "verification": {
+ "trust_framework": {
+ "value": "de_aml"
+ },
+ "evidence": [
+ {
+ "type": {
+ "value": "document"
+ },
+ "check_details": [
+ {
+ "check_method": {
+ "value": "pipp"
+ }
+ }
+ ],
+ "document_details": {
+ "type": {
+ "values": [
+ "idcard",
+ "passport"
+ ]
+ }
+ }
+ }
+ ]
+ },
+ "claims": {
+ "given_name": null,
+ "family_name": null,
+ "birthdate": null
+ }
+ }
+ }
+}
+¶
+The OP shall not ignore some or all of the query restrictions on possible values and shall not deliver available verified/verification data that does not match these constraints.¶
+The RP can also express a requirement regarding the age of certain data, like the time elapsed since the issuance/expiry of certain evidence types or since the verification process asserted in the verification element took place. Section 5.5.1 of the OpenID Connect specification [OpenID] defines a query syntax that allows for new special query members to be defined. This document introduces a new such member max_age, which is applicable to the possible values of any elements containing dates or timestamps (e.g., time, date_of_issuance and date_of_expiry elements of evidence of type document).¶
max_age: Optional. JSON number value only applicable to claims that contain dates or timestamps. It 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 OP 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:¶
+{
+ "userinfo": {
+ "verified_claims": {
+ "verification": {
+ "trust_framework": {
+ "value": "jp_aml"
+ },
+ "time": {
+ "max_age": 63113852
+ }
+ },
+ "claims": {
+ "given_name": null,
+ "family_name": null,
+ "birthdate": null
+ }
+ }
+ }
+}
+¶
+The OP should try to fulfill this requirement. If the verification data of the end-user is older than the requested max_age, the OP can attempt to refresh the end-user’s verification by sending them through an online identity verification process, e.g., by utilizing an electronic ID card or a video identification approach.¶
It is also possible to request different trust frameworks, assurance levels, and other elements of the structure for different claim sets. This requires the RP to send an array of verified_claims objects instead of passing a single object.¶
The following example illustrates this functionality.¶
+{
+ "userinfo": {
+ "verified_claims": [
+ {
+ "verification": {
+ "trust_framework": {
+ "value": "eidas"
+ },
+ "assurance_level": {
+ "value": "high"
+ }
+ },
+ "claims": {
+ "given_name": null,
+ "family_name": null
+ }
+ },
+ {
+ "verification": {
+ "trust_framework": {
+ "value": "eidas"
+ },
+ "assurance_level":{
+ "values":[
+ "high",
+ "substantial"
+ ]
+ }
+ },
+ "claims": {
+ "birthdate": null
+ }
+ }
+ ]
+ }
+}
+¶
+When the RP requests multiple verifications as described above, the OP will process each element in the array independently. The OP will provide verified_claims response elements for every verified_claims request element whose requirements it is able to fulfill. This also means if multiple verified_claims elements contain the same end-user claim(s), the OP delivers the claim in as many verified claims response objects it can fulfill. For example, if the trust framework the OP uses is compatible with multiple of the requested trust frameworks, it provides a verified_claims element for each of them.¶
The RP can combine multiple verified_claims claims in the request with multiple trust_framework and/or assurance_level values using the values element. In that case, the rules given above for processing values are applied for the particular verified_claims request object.¶
{
+ "userinfo": {
+ "verified_claims": [
+ {
+ "verification": {
+ "trust_framework": {
+ "value": "gold"
+ },
+ "evidence": [
+ {
+ "type": {
+ "value": "document"
+ }
+ }
+ ]
+ },
+ "claims": {
+ "given_name": null,
+ "family_name": null
+ }
+ },
+ {
+ "verification": {
+ "trust_framework": {
+ "values": [
+ "silver",
+ "bronze"
+ ]
+ },
+ "evidence": [
+ {
+ "type": {
+ "value": "electronic_record"
+ }
+ }
+ ]
+ },
+ "claims": {
+ "given_name": null,
+ "family_name": null
+ }
+ }
+ ]
+ }
+}
+¶
+In the above example, the RP asks for family and given name either under trust framework gold with an evidence of type document or under trust framework silver or bronze but with an evidence electronic_record.¶
As stated in section 3.3.3.6 of [OpenID], "the OP may choose to return fewer claims about the end-user from the authorization endpoint". This document makes no change to that provision. The OP may also choose to return a subset of the verification element of any verified_claims providing it remains compliant with the verified_claims JSON schema defined in [OpenID4IDAClaims].¶
In some cases, OPs cannot deliver the requested data to an RP, for example, because the data is not available or does not match the RP's requirements. The rules for handling these cases are described in the following.¶
+Extensions of this document can define additional rules or override these rules, for example¶
+Important: The behavior described below is independent from the use of essential (as defined in section 5.5.1 of [OpenID]).¶
When relying on end-user consent to determine the specific data to be shared the end-user may make a choice to release only a subset of the data requested. In this case the OP shall omit from any corresponding ID Token or UserInfo response data that has not had end-user consent for sharing.¶
+Alternatively, when relying on end-user consent to determine the specific data to be shared the end-user may choose to release none of the data requested. In this case standard OpenID Connect authentication error response logic applies, as defined in section 3.1.2.6 of [OpenID].¶
+When the available data does not fulfill the requirements of the RP expressed through value, values, or max_age, the following logic applies:¶
verified_claims/verification, the OP shall omit the whole verified_claims element.¶
+In both cases, the OP shall not return an error to the RP.¶
+If an element is to be omitted according to the rules above, but is a requirement for a valid response, the OP shall omit its parent element as well. This OP shall repeat this process until the response is valid.¶
+If the OP encounters an error, standard OpenID Connect authentication error response logic applies, as defined in section 3.1.2.6 of [OpenID].¶
+Verified claims about the end-user can be requested as part of a pre-defined set by utilizing the scope parameter as defined in section 5.4 of the OpenID Connect specification [OpenID].¶
When using this approach the claims associated with a scope value are administratively defined at the OP. The OP configuration and RP request parameters will determine whether the claims are returned via the ID Token or UserInfo endpoint as defined in section 5.3.2 of the OpenID Connect specification [OpenID].¶
When distributed claims are used the URL that is the value of the endpoint element in any distributed _claim_source sub-element shall use the https URI scheme and the JWT returned should not be accessible via any other URI scheme.¶
For aggregated or distributed claims, every assertion provided by the external claims source shall contain:¶
+typ header parameter with the value provided-claims+jwt,¶
+iss claim identifying the claims source,¶
+sub claim identifying the end-user in the context of the claim source, and¶
+verified_claims element containing one or more verified_claims objects.¶
+To ensure that assertions cannot be confused with OpenID Connect ID Tokens, assertions shall not contain:¶
+ +The verified_claims element in an aggregated or distributed claims object shall have one of the following forms:¶
verified_claims where the name of each object is a name for the respective claim source. Every such named object contains sub-objects called claims and verification expressing data provided by the respective claims source. This allows the RP to look ahead before it actually requests distributed claims in order to prevent extra time, cost, data collisions, etc. caused by these requests.¶
+Note: The two later forms extend the syntax as defined in section 5.6.2 of the OpenID Connect specification [OpenID]) in order to accommodate the specific use cases for verified_claims.¶
The following are examples of assertions including verified claims as aggregated claims¶
+{
+ "iss": "https://server.example.com",
+ "sub": "248289761001",
+ "email": "janedoe@example.com",
+ "email_verified": true,
+ "_claim_names": {
+ "verified_claims": "src1"
+ },
+ "_claim_sources": {
+ "src1": {
+ "JWT": "eyJhbGciOiJQUzI1NiIsImtpZCI6IjFlOWdkazciLCJ0eXAiOiJwcm92aWRlZC1jbGFpbXMrand0In0.eyJpc3MiOiJodHRwczovL3NlcnZlci5vdGhlcm9wLmNvbSIsInN1YiI6ImU4MTQ4NjAzLTg5MzQtNDI0NS04MjViLWMxMDhiOGI2Yjk0NSIsInZlcmlmaWVkX2NsYWltcyI6eyJ2ZXJpZmljYXRpb24iOnsidHJ1c3RfZnJhbWV3b3JrIjoiaWFsX2V4YW1wbGVfZ29sZCJ9LCJjbGFpbXMiOnsiZ2l2ZW5fbmFtZSI6Ik1heCIsImZhbWlseV9uYW1lIjoiTWVpZXIiLCJiaXJ0aGRhdGUiOiIxOTU2LTAxLTI4In19fQ.VAtHwi85ihW98uulbNOBCkyCyD4jeDrTeaMNdI3Wllks1z-LT8kyzN5Iz7Nu2HpMmmCKZpgY552O0fm_-Fr3Vls3BvmJsh1A524jh9VlsCL-1WezJ-DShjMUyP76_3Xbdl-iYHdWLjoQ5hFZQg6GLrLxOGlQXX9b-kxtQm3DV9nFJhOqMl_5_U8IU_A1LfypmRvXuD1Frw8ASS7OmyGOCkuFDOaV7Uu0BuZjYWiMC8Eem4M2A9RhuoLKDBYuVlwIFaHx-cuGcRJZWDg9K5DekIuLE73Iz1Cuh49HumkC9qGqkTV6EARSJeqFxPhjnZNkJY1e1P7Q7cgyT2HywjR6Tw"
+ }
+ }
+}
+¶
+and distributed claims.¶
+{
+ "iss": "https://server.example.com",
+ "sub": "248289761001",
+ "email": "janedoe@example.com",
+ "email_verified": true,
+ "_claim_names": {
+ "verified_claims": "src1"
+ },
+ "_claim_sources": {
+ "src1": {
+ "endpoint": "https://server.yetanotherop.com/claim_source",
+ "access_token": "ksj3n283dkeafb76cdef"
+ }
+ }
+}
+¶
+The following example shows an ID Token containing verified_claims from two different external claim sources, one as aggregated and the other as distributed claims.¶
{
+ "iss": "https://server.example.com",
+ "sub": "248289761001",
+ "email": "janedoe@example.com",
+ "email_verified": true,
+ "_claim_names": {
+ "verified_claims": [
+ "src1",
+ "src2"
+ ]
+ },
+ "_claim_sources": {
+ "src1": {
+ "JWT": "eyJhbGciOiJQUzI1NiIsImtpZCI6IjFlOWdkazciLCJ0eXAiOiJwcm92aWRlZC1jbGFpbXMrand0In0.eyJpc3MiOiJodHRwczovL3NlcnZlci5vdGhlcm9wLmNvbSIsInN1YiI6ImU4MTQ4NjAzLTg5MzQtNDI0NS04MjViLWMxMDhiOGI2Yjk0NSIsInZlcmlmaWVkX2NsYWltcyI6eyJ2ZXJpZmljYXRpb24iOnsidHJ1c3RfZnJhbWV3b3JrIjoiaWFsX2V4YW1wbGVfZ29sZCJ9LCJjbGFpbXMiOnsiZ2l2ZW5fbmFtZSI6Ik1heCIsImZhbWlseV9uYW1lIjoiTWVpZXIiLCJiaXJ0aGRhdGUiOiIxOTU2LTAxLTI4In19fQ.FPYS2Xjz9y9qEOJhBe5nMfL2mTagLDxwISxjM6gv3zRUvU2YBK-GHI_byvK8h46ly1C90ie-X9gOp-DLvpURvyAlZTsvxNL8s0Hi3-SRZCs5huhiCZr5s4FJBG-l0PNrYOIZAHfeQtobJ7muDld3BytS628140V0CHgh_EM8UUjzQmN8NpDaR9HdH0tIeUFqIZEwBluctgwek9eomg3k10dj6NzBUQSSnpgGf_o6f_sYoIAkBhpgRursD5pHbPSOKTGE9cJ882BbHeido746XLxjEfrU5yQwfA0ggVk5I_e-wv-xVXfVGda4WySZfbkwS5PMCMgMJM9ZT_L1pci0yQ"
+ },
+ "src2": {
+ "endpoint": "https://server.yetanotherop.com/claim_source",
+ "access_token": "ksj3n283dkeafb76cdef"
+ }
+ }
+}
+¶
+The next example shows an ID Token containing verified_claims from two different external claim sources along with additional data about the content of the verified claims (look ahead).¶
{
+ "iss": "https://server.example.com",
+ "sub": "248289761001",
+ "email": "janedoe@example.com",
+ "email_verified": true,
+ "_claim_names": {
+ "verified_claims": {
+ "src1": {
+ "verification": {
+ "trust_framework": {
+ "value": "trust_framework_example"
+ }
+ },
+ "claims": {
+ "given_name": null,
+ "family_name": null
+ }
+ },
+ "src2": {
+ "verification": {
+ "trust_framework": {
+ "value": "grids_kyb"
+ },
+ "evidence": [
+ {
+ "type": {
+ "value": "document"
+ },
+ "registry": {
+ "country": {
+ "essential": true,
+ "value": "ES"
+ }
+ },
+ "document": {
+ "SKU": {
+ "value": "REX"
+ }
+ }
+ }
+ ]
+ },
+ "claims": {
+ "given_name": null,
+ "family_name": null,
+ "email": null,
+ "nationalities": null
+ }
+ }
+ }
+ },
+ "_claim_sources": {
+ "src1": {
+ "JWT": "eyJraWQiOiJmMDgxZDI5OC1jNTgzLTQ3NDAtYWQ1NC02ZDUzMTljZjhiNWQiLCJhbGciOiJSUzI1NiJ9.ew0KICAgImlzcyI6ICJodHRwczovL3NlcnZlci5leGFtcGxlLmNvbSIsDQogICAic3ViIjogIjE0ODI4OTc2MiIsDQogICAidmVyaWZpZWRfY2xhaW1zIjogew0KICAgICJ2ZXJpZmljYXRpb24iOiB7DQogICAgICAidHJ1c3RfZnJhbWV3b3JrIjogInRydXN0X2ZyYW1ld29ya19leGFtcGxlIg0KICAgIH0sDQogICAgImNsYWltcyI6IHsNCiAgICAgICJnaXZlbl9uYW1lIjogIk1heCIsDQogICAgICAiZmFtaWx5X25hbWUiOiAiTWVpZXIiDQogICAgfQ0KICB9DQp9.jg_qxYfV0M2IU8On1iK9RBY0Cx9u3jRJ0Qzxe19Ol5VLoUTM7Uxbr3E0ZFCASHWpmz9d2g67XKGHQMppnJKX4SnEdphm6MqjnmZ9E0cirALrC016DX5geFy_0QFC8PAnCttcDgyVCyzCcDxUCaHBSRsrDwGjYe5AjgaDL8S-R72lFQHqch6uj9nhiFBtG24_0EsF6msssQ61WyqS6aju0F0PJms8danIfwc5lHyv-zKuDlY-0kw-fVn4274jY-VofElm4mhsrpo-YJhCKlz0O3CV0g9AW_60TQHCmhn6yoosaTbjlQqh5lREpqULz-MQKnD0wRmYLgBZXtzIhxb7ZA"
+ },
+ "src2": {
+ "endpoint": "https://server.yetanotherop.com/claim_source",
+ "access_token": "ksj3n283dkeafb76cdef"
+ }
+ }
+}
+¶
+Claim sources should sign the assertions containing verified_claims in order to demonstrate authenticity and provide for non-repudiation.
+RP should determine the key material used for validation of the signed assertions is via the claim source's public keys. These keys should be available in the JSON web key set available in the jwks_uri metadata value in the openid-configuration metadata document. This document can be discovered using the iss claim of the particular JWT.¶
The OP can combine aggregated and distributed claims with verified_claims provided by itself (see Appendix D.8).¶
If verified_claims elements are contained in multiple places of a response, e.g., in the ID Token and an embedded aggregated claim, the RP shall preserve the claims source as context of the particular verified_claims element.¶
Note: Any assertion provided by an OP or AS including aggregated or distributed claims can contain multiple instances of the same end-user claim. It is up to the RP to decide how to process these different instances.¶
+Clients shall validate any aggregated and distributed verified_claims they wish to rely on in the following manner:¶
_claim_names and _claim_sources are present in the response.¶
+verified_claims element present in the _claim_names member of the response.¶
+verified_claims element contains a value that is one of the following:
+a. a string that exists as a key name in the _claim_sources element of the response.
+b. a JSON array containing members that all exist as key names in the _claim_sources element of the response.
+c. a JSON object containing elements that all exist as key names in the _claim_sources element of the response and each element is formatted with the syntax as defined for requesting verified_claims.¶
+_claim_sources element is a JSON structured object that has one or more sub-elements.¶
+_claim_sources element have matching values in the _claim_names element of the response.¶
+When verified_claims are delivered as distributed claims, i.e., when a sub-element of the _claim_sources contains the endpoint claim, clients shall also:¶
endpoint element defined in any distributed _claim_sources uses the https URI scheme.¶
+endpoint element defined in any distributed _claim_sources.¶
+endpoint is a JWT as per [RFC7519].¶
+When verified_claims are delivered as aggregated claims, i.e., when a sub-element of the _claim_sources contains the JWT claim, clients shall also:¶
Once the JWT has been delivered either via distributed or aggregated mechanism the client shall:¶
+typ, iss, sub, and verified_claims elements; and that their values are not null or empty.¶
+exp claim or an aud claim.¶
+typ header parameter in the JWT is provided-claims+jwt.¶
+Making a request for verified claims and related verification data can be explicitly requested on the level of individual data elements by utilizing the claims parameter as defined in section 5.5 of the OpenID Connect specification [OpenID].¶
It is also possible to use the scope parameter to request one or more specific pre-defined claim sets as defined in section 5.4 of the OpenID Connect specification [OpenID].¶
Note: The OP shall not provide the RP with any data it did not request. However, the OP may at its discretion omit claims from the response.¶
+The example authorize call in this section will use the following unencoded example claims request parameter:¶
+{
+ "id_token": {
+ "given_name": null,
+ "verified_claims": {
+ "verification": {
+ "trust_framework": null
+ },
+ "claims": {
+ "family_name": null
+ }
+ }
+ }
+ }
+¶
+The following is the non-normative example request that would be sent by the user agent to the authorization server in response to the HTTP 302 redirect from the client initiating the authorization code flow (with line wraps within values for display purposes only):¶
+GET /authorize? + response_type=code + &scope=openid%20email + &client_id=s6BhdRkqt3 + &state=af0ifjsldkj + &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb + &claims=%7B%22id_token%22%3A%20%7B%22 + given_name%22%3A%20null%2C%22 + verified_claims%22%3A%20%7B%22 + verification%22%3A%20%7B%22 + trust_framework%22%3A%20null%7D%2C%22 + claims%22%3A%20%7B%22 + family_name%22%3A%20null%7D%7D%7D%7D HTTP/1.1 + Host: server.example.com +¶ +
The OP advertises its capabilities with respect to verified claims in its openid-configuration (see [OpenID-Discovery]) using the following new elements:¶
+trust_frameworks_supported: Required. JSON array containing all supported trust frameworks. This array shall have at least one member.¶
claims_in_verified_claims_supported: Required. JSON array containing all claims supported within verified_claims. claims that are not present in this array shall not be returned within the verified_claims object. This array shall have at least one member.¶
evidence_supported: Required when one or more type of evidence is supported. JSON array containing all types of identity evidence the OP uses. This array shall have at least one member. Members of this array should only be the types of evidence supported by the OP in the evidence element (see section 5.4.4 of [IDA-verified-claims]).¶
documents_supported: Required when evidence_supported contains "document". JSON array containing all identity document types utilized by the OP for identity verification. This array shall have at least one member.¶
documents_check_methods_supported: Optional. JSON array containing the "check methods" the OP supports for evidences of type "document" (see [predefined_values_page]). When present this array shall have at least one member.¶
electronic_records_supported: Required when evidence_supported contains "electronic_record". JSON array containing all electronic record types the OP supports (see [predefined_values_page]). When present this array shall have at least one member.¶
This is an example openid-configuration snippet:¶
+{
+...
+ "trust_frameworks_supported":[
+ "nist_800_63A"
+ ],
+ "evidence_supported": [
+ "document",
+ "electronic_record",
+ "vouch",
+ "electronic_signature"
+ ],
+ "documents_supported": [
+ "idcard",
+ "passport",
+ "driving_permit"
+ ],
+ "documents_methods_supported": [
+ "pipp",
+ "sripp",
+ "eid"
+ ],
+ "electronic_records_supported": [
+ "secure_mail"
+ ],
+ "claims_in_verified_claims_supported": [
+ "given_name",
+ "family_name",
+ "birthdate",
+ "place_of_birth",
+ "nationalities",
+ "address"
+ ],
+...
+}
+¶
+If the OP supports the claims parameter as defined in section 5.5 of the OpenID Connect specification [OpenID], the OP shall advertise this in its OP metadata using the claims_parameter_supported element.¶
If the OP supports distributed and/or aggregated claim types, as defined in section 5.6.2 of the OpenID Connect specification [OpenID], in verified_claims, the OP shall advertise this in its metadata using the claim_types_supported element.¶
The use of scopes is a potential shortcut to request a pre-defined set of claims, however, the use of scopes might result in more data being returned to the RP than is strictly necessary and not achieving the goal of data minimization. The RP should only request end-user claims and metadata it requires.¶
+Timestamps with a time zone component can potentially reveal the person’s location. To preserve the person’s privacy, timestamps within the verification element and verified claims that represent times should be represented in Coordinated Universal Time (UTC), unless there is a specific reason to include the time zone, such as the time zone being an essential part of a consented time related claim in verified data.¶
+This document focuses on mechanisms to carry end-user claims and accompanying metadata in JSON objects and JSON Web Tokens, typically as part of an OpenID Connect protocol exchange. Since such an exchange is supposed to take place in security sensitive use cases, implementers shall:¶
+This document does not define or require a particular security profile since there are several security +profiles and new security profiles under development. Implementers have the flexibility to select the security profile that best suits +their needs. Implementers might consider [FAPI-1-SP] or [FAPI-2-SP].¶
+Implementers should select a security profile that has a certification program or other resources that allow both OpenID providers and relying parties to ensure they have complied with the profile’s security and interoperability requirements, such as the OpenID Foundation Certification Program, https://openid.net/certification/.¶
+Receiving parties shall ensure the integrity and authenticity of the issued assertions in order to prevent identity spoofing.¶
+Receiving parties shall ensure the confidentiality of all end-user data exchanged between the protocol parties using suitable methods at transport or application layer.¶
+Secure identification of end-users not only depends on the identity verification at the OP but also on the strength of the user authentication at the OP. Combining a strong identification with weak authentication creates a false impression of security while being open to attacks. For example if an OP uses a simple PIN login, an attacker could guess the PIN of another user and identify himself as the other user at an RP with a high identity assurance level. To prevent this kind of attack, RPs should request the OP to authenticate the user at a reasonable level, typically using multi-factor authentication, when requesting verified end-user claims. OpenID Connect supports this by way of the acr_values request parameter.¶
To achieve the full security and interoperability benefits, it is important the implementation of this document, and the underlying OpenID Connect and OAuth specifications, and selected security profile, are complete and correct. The OpenID Foundation provides tools that should be used to confirm that deployments behave as described in the specifications, with information available at: https://openid.net/certification/.¶
+This document focuses on the technical mechanisms to convey verified claims and thus does not define any identifiers for elements such as trust frameworks, documents, check methods. This is left to adopters of the technical specification, e.g., implementers, identity schemes, or jurisdictions.¶
+Each party defining such identifiers shall ensure the collision resistance of these identifiers. This is achieved by including a domain name under the control of this party into the identifier name, e.g., https://mycompany.com/identifiers/cool_check_method.¶
The eKYC and Identity Assurance Working Group maintains a wiki page [predefined_values_page] that can be utilized to share predefined values with other parties.¶
+This section registers the application/provided-claims+jwt media type [RFC2046]
+in the IANA "Media Types" registry [IANA.MediaTypes] in the manner described in [RFC6838],
+which is used to indicate that the content is a JWT describing aggregated claims.¶
typ header of assertions provided as aggregated or distributed claims (see section 5.6.2 of the OpenID Connect specification [OpenID]).¶
+Additional information:¶
+ +The following people at yes.com and partner companies contributed to the concept described in the initial contribution to this document:¶
+We would like to thank the following people for their valuable feedback and contributions that helped to evolve this document:¶
+This section shows examples of requests for verified_claims.¶
{
+ "userinfo": {
+ "verified_claims": {
+ "verification": {
+ "trust_framework": null,
+ "time": null,
+ "evidence": [
+ {
+ "type": {
+ "value": "document"
+ },
+ "check_details": [
+ {
+ "check_method": {
+ "value": "pipp"
+ }
+ }
+ ],
+ "document_details": {
+ "type": null
+ }
+ }
+ ]
+ },
+ "claims": {
+ "given_name": null,
+ "family_name": null,
+ "birthdate": null
+ }
+ }
+ }
+}
+¶
+Note that, as shown in the above example, this document requires that implementations receiving requests are able to distinguish between JSON objects where a key is not present versus where a key is present with a null value.¶
+Support for these null value requests is mandatory for identity providers, so implementers are encouraged to test this behaviour early in their development process. In some programming languages many JSON libraries or HTTP frameworks will, at least by default, ignore null values and omit the relevant key when parsing the JSON.¶
+{
+ "userinfo": {
+ "verified_claims": [
+ {
+ "verification": {
+ "trust_framework": {
+ "value": "gold"
+ },
+ "evidence": [
+ {
+ "type": {
+ "value": "document"
+ }
+ }
+ ]
+ },
+ "claims": {
+ "given_name": null,
+ "family_name": null
+ }
+ },
+ {
+ "verification": {
+ "trust_framework": {
+ "values": [
+ "silver",
+ "bronze"
+ ]
+ },
+ "evidence": [
+ {
+ "type": {
+ "value": "vouch"
+ }
+ }
+ ]
+ },
+ "claims": {
+ "given_name": null,
+ "family_name": null
+ }
+ }
+ ]
+ }
+}
+¶
+{
+ "userinfo": {
+ "verified_claims": {
+ "verification": {
+ "trust_framework": {
+ "value": "it_spid"
+ },
+ "time": null,
+ "evidence": [
+ {
+ "type": {
+ "value": "document"
+ },
+ "check_details": [
+ {
+ "check_method": {
+ "value": "bvr"
+ }
+ }
+ ],
+ "document_details": {
+ "type": null,
+ "issuer": {
+ "country": null,
+ "name": null
+ },
+ "document_number": null,
+ "date_of_issuance": null
+ }
+ }
+ ]
+ },
+ "claims": {
+ "given_name": null,
+ "family_name": null,
+ "birthdate": null
+ }
+ }
+ }
+}
+¶
+{
+ "userinfo": {
+ "verified_claims": {
+ "verification": {
+ "trust_framework": null,
+ "time": null,
+ "evidence": [
+ {
+ "type": {
+ "value": "electronic_signature"
+ },
+ "issuer": null,
+ "serial_number": null,
+ "created_at": null
+ }
+ ]
+ },
+ "claims": {
+ "given_name": null,
+ "family_name": null,
+ "birthdate": null
+ }
+ }
+ }
+}
+¶
+This section shows examples of responses containing verified_claims.¶
The first and second subsections show JSON snippets of the general identity assurance case, where the RP is provided with verification evidence for different check methods along with the actual claims about the end-user.¶
+The third subsection illustrates the possible contents of this object in case of a notified eID system under eIDAS, where the OP does not need to provide evidence of the identity verification process to the RP.¶
+Subsequent subsections contain examples for using the verified_claims claim on different channels and in combination with other (unverified) claims.¶
{
+ "verified_claims": {
+ "verification": {
+ "trust_framework": "nist_800_63A",
+ "assurance_level": "ial2",
+ "assurance_process": {
+ "assurance_details": [
+ {
+ "assurance_type": "evidence_validation",
+ "assurance_classification": "strong",
+ "evidence_ref": [
+ {
+ "check_id": "DL1-93h506th2f45hf"
+ }
+ ]
+ },
+ {
+ "assurance_type": "verification",
+ "assurance_classification": "strong",
+ "evidence_ref": [
+ {
+ "check_id": "v-93jfk284ugjfj2093"
+ }
+ ]
+ }
+ ]
+ },
+ "time": "2021-06-06T05:32Z",
+ "verification_process": "7675D80F-57E0-AB14-9543-26B41FC22",
+ "evidence": [
+ {
+ "type": "document",
+ "check_details": [
+ {
+ "check_method": "vpiruv",
+ "organization": "doc_checker",
+ "check_id": "DL1-93h506th2f45hf",
+ "time": "2021-06-06T05:33Z"
+ },
+ {
+ "check_method": "pvp",
+ "organization": "face_checker",
+ "check_id": "v-93jfk284ugjfj2093"
+ }
+ ],
+ "document_details": {
+ "type": "driving_permit",
+ "document_number": "I1234568",
+ "date_of_issuance": "2019-09-05",
+ "date_of_expiry": "2024-08-01",
+ "issuer": {
+ "name": "CA DMV",
+ "country": "US",
+ "country_code": "USA",
+ "jurisdiction": "CA"
+ }
+ }
+ }
+ ]
+ },
+ "claims": {
+ "given_name": "Inga",
+ "family_name": "Silverstone",
+ "birthdate": "1991-11-06",
+ "place_of_birth": {
+ "country": "USA"
+ },
+ "address": {
+ "locality": "Shoshone",
+ "postal_code": "CA 92384",
+ "country": "USA",
+ "street_address": "114 Old State Hwy 127"
+ }
+ }
+ }
+}
+¶
+Same document under a different trust_framework¶
{
+ "verified_claims": {
+ "verification": {
+ "trust_framework": "uk_diatf",
+ "assurance_level": "medium",
+ "assurance_process": {
+ "policy": "gpg45",
+ "procedure": "m1c",
+ "assurance_details": [
+ {
+ "assurance_type": "evidence_validation",
+ "assurance_classification": "score_3",
+ "evidence_ref": [
+ {
+ "check_id": "DL1-93h506th2f45hf",
+ "evidence_metadata": {
+ "evidence_classification": "score_3_strength"
+ }
+ }
+ ]
+ },
+ {
+ "assurance_type": "verification",
+ "assurance_classification": "score_3",
+ "evidence_ref": [
+ {
+ "check_id": "v-93jfk284ugjfj2093"
+ }
+ ]
+ }
+ ]
+ },
+ "time": "2021-06-06T05:32Z",
+ "verification_process": "7675D80F-57E0-AB14-9543-26B41FC22",
+ "evidence": [
+ {
+ "type": "document",
+ "check_details": [
+ {
+ "check_method": "vpiruv",
+ "organization": "doc_checker",
+ "check_id": "DL1-93h506th2f45hf",
+ "time": "2021-06-06T05:33Z"
+ },
+ {
+ "check_method": "pvp",
+ "organization": "face_checker",
+ "check_id": "v-93jfk284ugjfj2093",
+ "time": "2021-06-08T11:42Z"
+ }
+ ],
+ "document_details": {
+ "type": "driving_permit",
+ "document_number": "I1234568",
+ "date_of_issuance": "2019-09-05",
+ "date_of_expiry": "2024-08-01",
+ "issuer": {
+ "name": "CA DMV",
+ "country": "US",
+ "country_code": "USA",
+ "jurisdiction": "CA"
+ }
+ }
+ }
+ ]
+ },
+ "claims": {
+ "given_name": "Inga",
+ "family_name": "Silverstone",
+ "birthdate": "1991-11-06",
+ "place_of_birth": {
+ "country": "USA"
+ },
+ "address": {
+ "locality": "Shoshone",
+ "postal_code": "CA 92384",
+ "country": "USA",
+ "street_address": "114 Old State Hwy 127"
+ }
+ }
+ }
+}
+¶
+{
+ "verified_claims": {
+ "verification": {
+ "trust_framework": "de_aml",
+ "time": "2012-04-23T18:25Z",
+ "verification_process": "f24c6f-6d3f-4ec5-973e-b0d8506f3bc7",
+ "evidence": [
+ {
+ "type": "document",
+ "check_details": [
+ {
+ "check_method": "pipp",
+ "organization": "Deutsche Post",
+ "check_id": "1aa05779-0775-470f-a5c4-9f1f5e56cf06",
+ "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"
+ }
+ }
+ ]
+ },
+ "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": "medium",
+ "assurance_process": {
+ "policy": "gpg45",
+ "procedure": "m1b",
+ "assurance_details": [
+ {
+ "assurance_type": "evidence_validation",
+ "assurance_classification": "score_2",
+ "evidence_ref": [
+ {
+ "check_id": "DL1-85762937582385820",
+ "evidence_metadata": {
+ "evidence_classification": "score_3_strength"
+ }
+ }
+ ]
+ },
+ {
+ "assurance_type": "verification",
+ "assurance_classification": "score_2",
+ "evidence_ref": [
+ {
+ "check_id": "kbv1-hf934hn09234ng03jj3",
+ "evidence_metadata": {
+ "evidence_classification": "high_kbv"
+ }
+ },
+ {
+ "check_id": "kbv2-nm0f23u9459fj38u5j6",
+ "evidence_metadata": {
+ "evidence_classification": "medium_kbv"
+ }
+ },
+ {
+ "check_id": "kbv3-jf9028h023hj0f9jh23",
+ "evidence_metadata": {
+ "evidence_classification": "medium_kbv"
+ }
+ }
+ ]
+ },
+ {
+ "assurance_type": "counter_fraud",
+ "assurance_classification": "score_2",
+ "evidence_ref": [
+ {
+ "check_id": "GRO-9824hngvp9278hf5tmp924y5h",
+ "evidence_metadata": {
+ "evidence_classification": "mortality_check"
+ }
+ },
+ {
+ "check_id": "fi-2nbf02hfn384ufn",
+ "evidence_metadata": {
+ "evidence_classification": "id_fraud"
+ }
+ }
+ ]
+ }
+ ]
+ },
+ "time": "2021-05-11T14:29Z",
+ "verification_process": "7675D80F-57E0-AB14-9543-26B41FC22",
+ "evidence": [
+ {
+ "type": "document",
+ "check_details": [
+ {
+ "check_method": "data",
+ "organization": "DVLA",
+ "time": "2021-04-09T14:12Z",
+ "check_id": "DL1-85762937582385820"
+ }
+ ],
+ "derived_claims": {
+ "given_name": "Sarah",
+ "family_name": "Meredyth",
+ "birthdate": "1976-03-11"
+ },
+ "document_details": {
+ "type": "driving_permit",
+ "document_number": "MORGA753116SM9IJ35",
+ "serial_number": "ZG21000001",
+ "date_of_issuance": "2021-01-01",
+ "date_of_expiry": "2030-12-31",
+ "issuer": {
+ "name": "DVLA",
+ "country": "UK",
+ "country_code": "GBR",
+ "jurisdiction": "GB-GBN"
+ }
+ }
+ },
+ {
+ "type": "electronic_record",
+ "check_details": [
+ {
+ "check_method": "kbv",
+ "organization": "TheCreditBureau",
+ "check_id": "kbv1-hf934hn09234ng03jj3",
+ "time": "2021-04-09T14:12Z"
+ }
+ ],
+ "record": {
+ "type": "mortgage_account",
+ "source": {
+ "name": "TheCreditBureau"
+ }
+ }
+ },
+ {
+ "type": "electronic_record",
+ "check_details": [
+ {
+ "check_method": "kbv",
+ "organization": "OpenBankingTPP",
+ "check_id": "kbv2-nm0f23u9459fj38u5j6",
+ "time": "2021-04-09T14:12Z"
+ }
+ ],
+ "record": {
+ "type": "bank_account",
+ "source": {
+ "name": "TheBank"
+ }
+ }
+ },
+ {
+ "type": "electronic_record",
+ "check_details": [
+ {
+ "check_method": "kbv",
+ "organization": "GSMA",
+ "check_id": "kbv3-jf9028h023hj0f9jh23",
+ "time": "2021-04-09T15:42Z"
+ }
+ ],
+ "record": {
+ "type": "mno",
+ "source": {
+ "name": "Vodafone"
+ }
+ }
+ },
+ {
+ "type": "electronic_record",
+ "check_details": [
+ {
+ "check_method": "data",
+ "organization": "GRO",
+ "check_id": "GRO-9824hngvp9278hf5tmp924y5h",
+ "time": "2021-04-09T16:12Z"
+ }
+ ],
+ "record": {
+ "type": "death_register",
+ "source": {
+ "name": "General Register Office",
+ "street_address": "PO BOX 2",
+ "locality": "Southport",
+ "postal_code": "PR8 2JD",
+ "country": "UK",
+ "country_code": "GBR",
+ "jurisdiction": "GB-EAW"
+ }
+ }
+ },
+ {
+ "type": "electronic_record",
+ "check_details": [
+ {
+ "check_method": "data",
+ "organization": "NextLex",
+ "check_id": "fi-2nbf02hfn384ufn",
+ "time": "2021-04-09T16:51Z"
+ }
+ ],
+ "record": {
+ "type": "fraud_register",
+ "source": {
+ "name": "National Fraud Database",
+ "jurisdiction": "UK"
+ }
+ }
+ }
+ ]
+ },
+ "claims": {
+ "given_name": "Sarah",
+ "family_name": "Meredyth",
+ "birthdate": "1976-03-11",
+ "place_of_birth": {
+ "country": "UK"
+ },
+ "address": {
+ "locality": "Edinburgh",
+ "postal_code": "EH1 9GP",
+ "country": "UK",
+ "street_address": "122 Burns Crescent"
+ }
+ }
+ }
+}
+¶
+{
+ "verified_claims": {
+ "verification": {
+ "trust_framework": "eidas",
+ "assurance_level": "substantial"
+ },
+ "claims": {
+ "given_name": "Max",
+ "family_name": "Meier",
+ "birthdate": "1956-01-28",
+ "place_of_birth": {
+ "country": "DE",
+ "locality": "Musterstadt"
+ },
+ "nationalities": [
+ "DE"
+ ]
+ }
+ }
+}
+¶
+{
+ "verified_claims": {
+ "verification": {
+ "trust_framework": "se_bankid",
+ "assurance_level": "al_2",
+ "time": "2021-03-03T09:42Z",
+ "verification_process": "4346D80F-57E0-4E26-9543-26B41FC22",
+ "evidence": [
+ {
+ "type": "electronic_record",
+ "check_details": [
+ {
+ "check_method": "data",
+ "time": "2021-02-15T16:51Z"
+ },
+ {
+ "check_method": "token"
+ }
+ ],
+ "record": {
+ "type": "population_register",
+ "source": {
+ "name": "Skatteverket",
+ "country": "Sverige",
+ "country_code": "SWE"
+ },
+ "created_at": "1979-01-22T00:00Z",
+ "date_of_expiry": "2025-12-31"
+ },
+ "derived_claims": {
+ "given_name": "Fredrik",
+ "family_name": "Strömberg",
+ "birthdate": "1979-01-22"
+ }
+ }
+ ]
+ },
+ "claims": {
+ "given_name": "Fredrik",
+ "family_name": "Strömberg",
+ "birthdate": "1979-01-22",
+ "place_of_birth": {
+ "country": "SWE",
+ "locality": "Örnsköldsvik"
+ },
+ "nationalities": [
+ "SE"
+ ],
+ "address": {
+ "locality": "Karlstad",
+ "postal_code": "65344",
+ "country": "SWE",
+ "street_address": "Gatunamn 221b"
+ }
+ }
+ }
+}
+¶
+{
+ "verified_claims": {
+ "verification": {
+ "trust_framework": "uk_diatf",
+ "assurance_level": "very_high",
+ "time": "2020-03-19T13:05Z",
+ "verification_process": "76755DA2-81E1-5N14-9543-26B415B77",
+ "evidence": [
+ {
+ "type": "vouch",
+ "check_details": [
+ {
+ "check_method": "vcrypt",
+ "time": "2020-03-19T12:42Z"
+ },
+ {
+ "check_method": "bvr"
+ }
+ ],
+ "attestation": {
+ "type": "digital_attestation",
+ "reference_number": "6485-1619-3976-6671",
+ "date_of_issuance": "2021-06-04",
+ "date_of_expiry": "2022-06-04",
+ "voucher": {
+ "organization": "HMP Dartmoor"
+ }
+ },
+ "derived_claims": {
+ "given_name": "Sam",
+ "family_name": "Lawler",
+ "birthdate": "1981-04-13"
+ }
+ }
+ ]
+ },
+ "claims": {
+ "given_name": "Sam",
+ "family_name": "Lawler",
+ "birthdate": "1981-04-13",
+ "place_of_birth": {
+ "country": "GBR"
+ },
+ "address": {
+ "postal_code": "98015",
+ "country": "Monaco"
+ }
+ }
+ }
+}
+¶
+{
+ "verified_claims": [
+ {
+ "verification": {
+ "trust_framework": "eidas",
+ "assurance_level": "substantial"
+ },
+ "claims": {
+ "given_name": "Max",
+ "family_name": "Meier",
+ "birthdate": "1956-01-28",
+ "place_of_birth": {
+ "country": "DE",
+ "locality": "Musterstadt"
+ },
+ "nationalities": [
+ "DE"
+ ]
+ }
+ },
+ {
+ "verification": {
+ "trust_framework": "de_aml",
+ "time": "2012-04-23T18:25Z",
+ "verification_process": "f24c6f-6d3f-4ec5-973e-b0d8506f3bc7",
+ "evidence": [
+ {
+ "type": "document",
+ "check_details": [
+ {
+ "check_method": "pipp",
+ "time": "2012-04-22T11:30Z"
+ }
+ ],
+ "document_details": {
+ "type": "idcard"
+ }
+ }
+ ]
+ },
+ "claims": {
+ "address": {
+ "locality": "Maxstadt",
+ "postal_code": "12344",
+ "country": "DE",
+ "street_address": "An der Weide 22"
+ }
+ }
+ }
+ ]
+}
+¶
+This example shows how an OP can mix own claims and claims provided by +external sources in a single ID Token.¶
+{
+ "iss": "https://server.example.com",
+ "sub": "248289761001",
+ "email": "janedoe@example.com",
+ "email_verified": true,
+ "verified_claims": {
+ "verification": {
+ "trust_framework": "trust_framework_example"
+ },
+ "claims": {
+ "given_name": "Max",
+ "family_name": "Meier"
+ }
+ },
+ "_claim_names": {
+ "verified_claims": [
+ "src1",
+ "src2"
+ ]
+ },
+ "_claim_sources": {
+ "src1": {
+ "JWT": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL3NlcnZlci5vdGhlcm9wLmNvbSIsInN1YiI6ImU4MTQ4NjAzLTg5MzQtNDI0NS04MjViLWMxMDhiOGI2Yjk0NSIsInZlcmlmaWVkX2NsYWltcyI6eyJ2ZXJpZmljYXRpb24iOnsidHJ1c3RfZnJhbWV3b3JrIjoiaWFsX2V4YW1wbGVfZ29sZCJ9LCJjbGFpbXMiOnsiZ2l2ZW5fbmFtZSI6Ik1heCIsImZhbWlseV9uYW1lIjoiTWVpZXIiLCJiaXJ0aGRhdGUiOiIxOTU2LTAxLTI4In19fQ.FArlPUtUVn95HCExePlWJQ6ctVfVpQyeSbe3xkH9MH1QJjnk5GVbBW0qe1b7R3lE-8iVv__0mhRTUI5lcFhLjoGjDS8zgWSarVsEEjwBK7WD3r9cEw6ZAhfEkhHL9eqAaED2rhhDbHD5dZWXkJCuXIcn65g6rryiBanxlXK0ZmcK4fD9HV9MFduk0LRG_p4yocMaFvVkqawat5NV9QQ3ij7UBr3G7A4FojcKEkoJKScdGoozir8m5XD83Sn45_79nCcgWSnCX2QTukL8NywIItu_K48cjHiAGXXSzydDm_ccGCe0sY-Ai2-iFFuQo2PtfuK2SqPPmAZJxEFrFoLY4g"
+ },
+ "src2": {
+ "endpoint": "https://server.yetanotherop.com/claim_source",
+ "access_token": "ksj3n283dkeafb76cdef"
+ }
+ }
+}
+¶
+This example shows how a Self-Issued OpenID provider (SIOP) +may include verified claims obtained from different external claim +sources into an ID Token.¶
+{
+ "iss": "https://self-issued.me",
+ "sub": "248289761001",
+ "preferred_username": "superman445",
+ "_claim_names": {
+ "verified_claims": [
+ "src1",
+ "src2"
+ ]
+ },
+ "_claim_sources": {
+ "src1": {
+ "JWT": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL3NlcnZlci5vdGhlcm9wLmNvbSIsInN1YiI6ImU4MTQ4NjAzLTg5MzQtNDI0NS04MjViLWMxMDhiOGI2Yjk0NSIsInZlcmlmaWVkX2NsYWltcyI6eyJ2ZXJpZmljYXRpb24iOnsidHJ1c3RfZnJhbWV3b3JrIjoiaWFsX2V4YW1wbGVfZ29sZCJ9LCJjbGFpbXMiOnsiZ2l2ZW5fbmFtZSI6Ik1heCIsImZhbWlseV9uYW1lIjoiTWVpZXIiLCJiaXJ0aGRhdGUiOiIxOTU2LTAxLTI4In19fQ.FArlPUtUVn95HCExePlWJQ6ctVfVpQyeSbe3xkH9MH1QJjnk5GVbBW0qe1b7R3lE-8iVv__0mhRTUI5lcFhLjoGjDS8zgWSarVsEEjwBK7WD3r9cEw6ZAhfEkhHL9eqAaED2rhhDbHD5dZWXkJCuXIcn65g6rryiBanxlXK0ZmcK4fD9HV9MFduk0LRG_p4yocMaFvVkqawat5NV9QQ3ij7UBr3G7A4FojcKEkoJKScdGoozir8m5XD83Sn45_79nCcgWSnCX2QTukL8NywIItu_K48cjHiAGXXSzydDm_ccGCe0sY-Ai2-iFFuQo2PtfuK2SqPPmAZJxEFrFoLY4g"
+ },
+ "src2": {
+ "endpoint": "https://op.mymno.com/claim_source",
+ "access_token": "ksj3n283dkeafb76cdef"
+ }
+ }
+}
+¶
+This section shows examples of pairs of requests and responses containing verified_claims.¶
In this example we assume the RP uses the scope parameter to request the email address and, additionally, the claims parameter, to request verified claims.¶
The scope value is: scope=openid email¶
The value of the claims parameter is:¶
{
+ "userinfo": {
+ "verified_claims": {
+ "verification": {
+ "trust_framework": null
+ },
+ "claims": {
+ "given_name": null,
+ "family_name": null,
+ "birthdate": null
+ }
+ }
+ }
+}
+¶
+The respective UserInfo response would be¶
+{
+ "sub": "248289761001",
+ "email": "janedoe@example.com",
+ "email_verified": true,
+ "verified_claims": {
+ "verification": {
+ "trust_framework": "de_aml"
+ },
+ "claims": {
+ "given_name": "Max",
+ "family_name": "Meier",
+ "birthdate": "1956-01-28"
+ }
+ }
+}
+¶
+In this case, the RP requests verified claims along with other claims about the end-user in the claims parameter and allocates the response to the ID Token (delivered from the token endpoint in case of grant type authorization_code).¶
The claims parameter value is¶
{
+ "id_token": {
+ "email": null,
+ "preferred_username": null,
+ "picture": null,
+ "verified_claims": {
+ "verification": {
+ "trust_framework": null,
+ "time": null,
+ "verification_process": null,
+ "evidence": [
+ {
+ "type": {
+ "value": "document"
+ },
+ "check_details": [
+ {
+ "check_method": null,
+ "time": null
+ }
+ ],
+ "document_details": {
+ "type": null,
+ "issuer": {
+ "name": null,
+ "country": null
+ },
+ "document_number": null,
+ "date_of_issuance": null,
+ "date_of_expiry": null
+ }
+ }
+ ]
+ },
+ "claims": {
+ "given_name": null,
+ "family_name": null,
+ "birthdate": null
+ }
+ }
+ }
+}
+¶
+The decoded body of 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_claims": {
+ "verification": {
+ "trust_framework": "de_aml",
+ "time": "2012-04-23T18:25Z",
+ "verification_process": "f24c6f-6d3f-4ec5-973e-b0d8506f3bc7",
+ "evidence": [
+ {
+ "type": "document",
+ "check_details": [
+ {
+ "check_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"
+ }
+ }
+ ]
+ },
+ "claims": {
+ "given_name": "Jane",
+ "family_name": "Doe",
+ "birthdate": "1956-01-28"
+ }
+ }
+}
+¶
+The 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, Dima Postnikov and Nat Sakimura for their valuable feedback and contributions that helped to evolve this document.¶
+Copyright (c) 2026 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, Final Specification, or Final Specification Incorporating Errata Corrections solely for the purposes of (i) developing specifications, and (ii) implementing Implementers Drafts, Final Specifications, and Final Specification Incorporating Errata Corrections 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 (found at openid.net) requires contributors to offer a patent promise not to assert certain patent claims against other contributors and against implementers. OpenID 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.¶
+| + | openid-ida-verified-claims-1_0 | +July 2026 | +
| Lodderstedt, et al. | +Standards Track | +[Page] | +
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.¶
+This specification defines a schema for describing assured identity claims and a range of associated identity assurance metadata. Much of this definition will be optional as it depends on which processes were run, and the operational requirements for data-minimization, which elements of the JSON schema described in this document will be needed for a specific transaction.¶
+This specification defines the schema of JSON objects used to describe identity assurance relating to a natural person. It consists of the definition of a new claim called verified_claims that will be registered with the IANA "JSON Web Token Claims Registry" established by [RFC7519]. As part of the definition of the verified_claims claim there is also be an element defined called verification that provides a flexible container for identity assurance metadata. It is anticipated that the verification element may be used by other spec authors and implementers where the verification metadata is needed independently of the end-user verified claims.¶
See section 6 for normative references.¶
+For the purposes of this document, the following terms and definitions apply.¶
+ +server that can return claims and verified claims about an entity¶
+Note 1 to entry : A claim provider could be an OpenID Connect provider, a verifiable claim issuer or other application component that provides verified claims.¶
+[SOURCE: [OpenID], 1.2, modified - added requirement to return verified claims]¶
+application that receives claims from the claim provider¶
+process in which an end-user provides evidence to a provider reliably identifying themselves, thereby allowing the provider to assert that identification at a useful assurance level.¶
+process conducted by the provider to verify the end-user's identity.¶
+process in which the provider asserts identity data of a certain end-user with a certain assurance towards another consuming entity (such as a relying party or verifier as described in [W3C_VCDM]), typically expressed by way of an assurance level¶
+Note 1 to entry: Depending on legal requirements, the provider can be required to provide evidence of the identity verification process to the consuming entity.¶
+claims about an end-user, typically a natural person, whose binding to a particular end-user account was verified in the course of an identity verification process.¶
+The specified JSON structures defined in this document should be usable by any protocol that needs to pass assured digital identity attributes or needs to transfer identity assurance metadata between systems using the [JSON] Data Interchange Format.¶
+This specification defines a generic mechanism to add verified claims to JSON-based assertions. It uses a container element, called verified_claims, to provide the claim recipient with a set of claims along with the respective metadata and verification evidence related to the verification of these claims. This way, claim recipients cannot mix up verified claims and unverified claims and accidentally process unverified claims as verified claims.¶
The following example would assert to the claim recipient that the claim provider has verified the claims provided (given_name and family_name) according to an example trust framework trust_framework_example:¶
{
+ "verified_claims": {
+ "verification": {
+ "trust_framework": "trust_framework_example"
+ },
+ "claims": {
+ "given_name": "Max",
+ "family_name": "Meier"
+ }
+ }
+}
+¶
+The normative definition is given in the following.¶
+verified_claims: A single object or an array of objects, each object comprising the following sub-elements:¶
claims: Required. Object that is the container for the verified claims about the end-user.¶
+verification: Required. Object that contains data about the verification process.¶
+Note: Implementations shall ignore any sub-element not defined in this specification or extensions of this specification. Extensions to this specification that specify additional sub-elements under the verified_claims element may be created by the OpenID Foundation, ecosystem or scheme operators or indeed singular implementers using this specification.¶
A machine-readable syntax definition of verified_claims is given as JSON schema in [verified_claims.json], it can be used to automatically validate JSON documents containing a verified_claims element. The provided JSON schema files are a non-normative implementation of this specification and any discrepancies that exist are either implementation bugs or interpretations.¶
Extensions of this specification, including trust framework definitions, can define further constraints on the data structure.¶
+The claims element contains the claims about the end-user which were verified by the process and according to the policies determined by the corresponding verification element described in the next section.¶
The claims element may contain any of the following claims as defined in section 5.1 of the OpenID Connect specification [OpenID]¶
name¶
+given_name¶
+middle_name¶
+family_name¶
+birthdate¶
+address¶
+and the claims defined in [OpenID4IDAClaims].¶
+The claims element may also contain other claims provided the value of the respective claim was verified in the verification process represented by the sibling verification element.¶
Claim names may be annotated with language tags as specified in section 5.2 of the OpenID Connect specification [OpenID].¶
+The claims element may be empty, to support use cases where verification is required but no claims data needs to be shared.¶
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 can be used independently of OpenID Connect and OpenID Connect for Identity Assurance where there is a need for representation of identity assurance metadata in a different application protocol or digital identity data format such as [W3C_VCDM].¶
The verification element consists of the following elements:¶
trust_framework: Required. String determining the trust framework governing the identity verification process of the claim provider.
+An example value is eidas, which denotes a notified eID system under eIDAS [eIDAS].¶
Claim recipients should ignore verified_claims claims containing a trust framework identifier they do not understand.¶
The trust_framework value determines what further data is provided to the claim recipient in the verification element. A notified eID system under eIDAS, for example, would not need to provide any further data whereas a claim provider not governed by eIDAS would need to provide verification evidence in order to allow the claim recipient to fulfill its legal obligations. An example of the latter is a claim provider acting under the German anti-money laundering law (de_aml).¶
assurance_level: Optional. String determining the assurance level associated with the end-user claims in the respective verified_claims. The value range depends on the respective trust_framework value. For example, the trust framework eidas can have the identity assurance levels low, substantial and high. For information on predefined trust framework and assurance level values see [predefined_values_page].¶
assurance_process: Optional. JSON object representing the assurance process that was followed. This reflects how the evidence meets the requirements of the trust_framework and assurance_level. The factual record of the evidence and the procedures followed are recorded in the evidence element; this element is used to cross reference the evidence to the assurance_process followed. This has one or more of the following sub-elements:¶
policy: Optional. String representing the standard or policy that was followed.¶
+procedure: Optional. String representing a specific procedure from the policy that was followed.¶
+assurance_details: Optional. JSON array denoting the details about how the evidence complies with the policy. When present this array shall have at least one member. Each member can have the following sub-elements:¶
assurance_type: Optional. String denoting which part of the assurance_process the evidence fulfills.¶
+assurance_classification: Optional. String reflecting how the evidence has been classified or measured as required by the trust_framework.¶
+evidence_ref: Optional. JSON array of the evidence being referred to. When present this array shall have at least one member.¶
check_id: Required. Identifier referring to the check_id key used in the check_details element of members of the evidence array. The claim provider shall ensure that check_id is present in the check_details when evidence_ref element is used.¶
+evidence_metadata: Optional. Object indicating any metadata about the evidence that is required by the assurance_process in order to demonstrate compliance with the trust_framework. It has the following sub-elements:¶
+evidence_classification: Optional. String indicating how the process demonstrated by the check_details for the evidence is classified by the assurance_process in order to demonstrate compliance with the trust_framework.¶
+time: Optional. Time stamp in ISO 8601 [ISO8601] YYYY-MM-DDThh:mm[:ss]TZD format representing the date and time when the identity verification process took place. This time might deviate from the time element within check_details since the latter represents the time when a certain evidence check was completed whereas this element represents the time when the overall verification process was completed. Moreover, the overall verification process and evidence verification can be conducted by different parties (see organization within check_details). Presence of this element might be required for certain trust frameworks.¶
verification_process: Optional. Unique reference to the identity verification process as performed by the claim provider. Used for identifying and retrieving details in case of disputes or audits. Presence of this element might be required for certain trust frameworks.¶
evidence: Optional. JSON array containing information about the evidence the claim provider used to verify the end-user's identity as separate JSON objects. Every object contains the property type which determines the type of the evidence. The claim recipient uses this information to process the evidence property appropriately.¶
Important: Implementations shall ignore any sub-element not defined in this specification or extensions of this specification.¶
+Based on the definition above and that there are a significant number of optional sub-elements it is informative to show a minimum conformant verified_claims payload. There can be optionally much more detail included in an openid-ida-verified-claims conformant verified_claims element when further detail needs to be transferred. The example is not normative.¶
{
+ "verified_claims": {
+ "verification": {
+ "trust_framework": "de_aml"
+ },
+ "claims": {}
+ }
+ }
+¶
+Members of the evidence array are JSON objects.¶
The following types of evidence are defined:¶
+document: Verification based on the content of a physical or electronic document provided by the end-user, e.g. a passport, ID card, PDF signed by a recognized authority, etc.¶
+electronic_record: Verification based on data or information obtained electronically from an approved, recognized, regulated or certified source, e.g. a government organization, bank, utility provider, credit reference agency, etc.¶
+vouch: Verification based on an attestation given by an approved or recognized natural person declaring they believe that the claim(s) presented by the end-user are, to the best of their knowledge, genuine and true.¶
+electronic_signature: Verification based on the use of an electronic signature that can be uniquely linked to the end-user and is capable of identifying the signatory, e.g. an eIDAS Advanced Electronic Signature (AES) or Qualified Electronic Signature (QES).¶
+Depending on the evidence type additional elements are defined, as described in the following.¶
+document
+ The following elements are contained in an evidence sub-element where type is document.¶
type: Required with value set to document.¶
check_details: Optional. JSON array representing the checks done in relation to the evidence. When present this array shall have at least one member. Each member of the check_details array has the following requirements:¶
check_method: Required. String representing the check done, this includes processes such as checking the authenticity of the document, or verifying the user's biometric against an identity document. For information on predefined check_details values see [predefined_values_page].¶
+organization: Optional. String denoting the legal entity that performed the check. This should be included if the claim provider did not perform the check itself.¶
+check_id: Optional. Identifier referring to the event where a check (either verification or validation) was performed. The claim provider shall ensure that this is present when evidence_ref element is used. The claim provider shall ensure that the transaction identifier can be resolved into transaction details during an audit.¶
+time: Optional. Time stamp in ISO 8601 [ISO8601] YYYY-MM-DDThh:mm[:ss]TZD format representing the date when the check was completed.¶
+document_details: Optional. JSON object representing the document used to perform the identity verification. It consists of the following properties:¶
type: Required. String denoting the type of the document. For information on predefined document values see [predefined_values_page]. The claim provider may use other predefined values in which case the claim recipients will either be unable to process the assertion, just store this value for audit purposes, or apply bespoke business logic to it.¶
+document_number: Optional. String representing an identifier/number that uniquely identifies a document that was issued to the end-user. This is used on one document and will change if it is reissued, e.g., a passport number, certificate number, etc.¶
+serial_number: Optional. String representing an identifier/number that identifies the document irrespective of any personalization information (this usually only applies to physical artifacts and is present before personalization).¶
+date_of_issuance: Optional. The date the document was issued as ISO 8601 [ISO8601] YYYY-MM-DD format.¶
+date_of_expiry: Optional. The date the document will expire as ISO 8601 [ISO8601] YYYY-MM-DD format.¶
+issuer: Optional. JSON object containing information about the issuer of this document. This object consists of the following properties:¶
name: Optional. Designation of the issuer of the document.¶
+address claim (see [OpenID])¶
+country_code: Optional. String denoting the country or supranational organization that issued the document as [ISO3166-1] Alpha-3 codes or [ICAO-Doc9303] 3-letter codes, e.g., "USA" or "JPN". ISO Alpha-2 codes or ICAO 2-letter codes may be used in some circumstances for compatibility reasons.
+Note: [ICAO-Doc9303] refers to [ISO3166-1] and only the codes not in ISO3166 are defined in the ICAO doc.¶
+jurisdiction: Optional. String containing the name of the region(s)/state(s)/province(s)/municipality(ies) that issuer has jurisdiction over (if this information is not common knowledge or derivable from the address).¶
+attachments: Optional. Array of JSON objects representing attachments like photocopies of documents or certificates. Structure of members of the attachments array is described in [Attachments].¶
derived_claims: Optional. JSON object containing claims about the end-user which were derived from the document described in the evidence array member it is part of. When used the derived_claims element has the following conditions:¶
derived_claims element may contain any of the claims defined in section 5.1 of the OpenID Connect specification [OpenID] and the claims defined in [OpenID4IDAClaims].¶
+derived_claims element may also contain other end-user claims (not defined in the OpenID Connect specification [OpenID] nor in [OpenID4IDAClaims]) derived from the document described in the evidence array member it is part of.¶
+derived_claims element shall have corresponding claims in the claims element of verified_claims.¶
+derived_claims element is used it should be present in all members of the evidence array and all claims under the claims element of verified_claims should have a corresponding claim in at least one derived_claims element.¶
+derived_claims element shall not be empty.¶
+electronic_record
+ The following elements are contained in an evidence sub-element where type is electronic_record.¶
type: Required with value set to electronic_record.¶
check_details: Optional. JSON array representing the checks done in relation to the evidence. Each member of the check_details array has the following requirements:¶
check_method: Required. String representing the check done. For information on predefined check_method values see [predefined_values_page].¶
+organization: Optional. String denoting the legal entity that performed the check. This should be included if the claim provider did not perform the check itself.¶
+check_id: Optional. Identifier referring to the event where a check (either verification or validation) was performed. The claim provider shall ensure that this is present when evidence_ref element is used. The claim provider shall ensure that the transaction identifier can be resolved into transaction details during an audit.¶
+time: Optional. Time stamp in ISO 8601 [ISO8601] YYYY-MM-DDThh:mm[:ss]TZD format representing the date when the check was completed.¶
+record: Optional. JSON object representing the record used to perform the identity verification. It consists of the following properties:¶
type: Required. String denoting the type of electronic record. For information on predefined identity evidence values see [predefined_values_page]. The claim provider may use other predefined values in which case the claim recipients will either be unable to process the assertion, just store this value for audit purposes, or apply bespoke business logic to it.¶
+created_at: Optional. The time the record was created as ISO 8601 [ISO8601] YYYY-MM-DDThh:mm[:ss]TZD format.¶
+date_of_expiry: Optional. The date the evidence will expire as ISO 8601 [ISO8601] YYYY-MM-DD format.¶
+source: Optional. JSON object containing information about the source of this record. This object consists of the following properties:¶
name: Optional. Designation of the source of the electronic_record.¶
+address claim (see [OpenID]): Optional.¶
+country_code: Optional. String denoting the country or supranational organization that issued the evidence as [ISO3166-1] Alpha-3 codes or [ICAO-Doc9303] 3-letter codes, e.g., "USA" or "JPN". ISO Alpha-2 codes or ICAO 2-letter codes may be used in some circumstances for compatibility reasons.
+Note: [ICAO-Doc9303] refers to [ISO3166-1] and only the codes not in ISO3166 are defined in the ICAO doc.¶
+jurisdiction: Optional. String containing the name of the region(s) / state(s) / province(s) / municipality(ies) that source has jurisdiction over (if it is not common knowledge or derivable from the address).¶
+attachments: Optional. Array of JSON objects representing attachments like photocopies of documents or certificates. Structure of members of the attachments array is described in [Attachments].¶
derived_claims: Optional. JSON object containing claims about the end-user which were derived from the electronic record described in the evidence array member it is part of.¶
derived_claims element may contain any of the claims defined in section 5.1 of the OpenID Connect specification [OpenID] and the claims defined in [OpenID4IDAClaims].¶
+derived_claims element may also contain other end-user claims (not defined in the OpenID Connect specification [OpenID] nor in [OpenID4IDAClaims]) derived from the electronic record described in the evidence array member it is part of.¶
+derived_claims element shall not be empty.¶
+vouch
+ The following elements are contained in an evidence sub-element where type is vouch.¶
type: Required with value set to vouch.¶
check_details: Optional. JSON array representing the checks done in relation to the vouch. Each member of the check_details array has the following requirements:¶
check_method: Required. String representing the check done, this includes processes such as checking the authenticity of the vouch, or verifying the user as the person referenced in the vouch. For information on predefined check_method values see [predefined_values_page].¶
+organization: Optional. String denoting the legal entity that performed the check. This should be included if the claim provider did not perform the check itself.¶
+check_id: Optional. Identifier referring to the event where a check (either verification or validation) was performed. The claim provider shall ensure that this is present when evidence_ref element is used. The claim provider shall ensure that the transaction identifier can be resolved into transaction details during an audit.¶
+time: Optional. Time stamp in ISO 8601 [ISO8601] YYYY-MM-DDThh:mm[:ss]TZD format representing the date when the check was completed.¶
+attestation: Optional. JSON object representing the attestation that is the basis of the vouch. It consists of the following properties:¶
type: Required. String denoting the type of vouch. For information on predefined vouch values see [predefined_values_page]. The claim provider may use other than the predefined values in which case the claim recipients will either be unable to process the assertion, just store this value for audit purposes, or apply bespoke business logic to it.¶
+reference_number: Optional. String representing an identifier/number that uniquely identifies a vouch given about the end-user.¶
+date_of_issuance: Optional. The date the vouch was made as ISO 8601 [ISO8601] YYYY-MM-DD format.¶
+date_of_expiry: Optional. The date the evidence will expire as ISO 8601 [ISO8601] YYYY-MM-DD format.¶
+voucher: Optional. JSON object containing information about the entity giving the vouch. This object consists of the following properties:¶
name: Optional. String containing the name of the person giving the vouch/reference in the same format as defined in section 5.1 (Standard Claims) of the OpenID Connect Core specification.¶
+birthdate: Optional. String containing the birthdate of the person giving the vouch/reference in the same format as defined in section 5.1 (Standard Claims) of the OpenID Connect Core specification.¶
+address claim (see [OpenID]): Optional.¶
+country_code: Optional. String denoting the entity giving the vouch as [ISO3166-1] Alpha-3 codes or [ICAO-Doc9303] 3-letter codes, e.g., "USA" or "JPN". ISO Alpha-2 codes or ICAO 2-letter codes may be used in some circumstances for compatibility reasons.
+Note: [ICAO-Doc9303] refers to [ISO3166-1] and only the codes not in ISO3166 are defined in the ICAO doc.¶
+occupation: Optional. String containing the occupation or other authority of the person giving the vouch/reference.¶
+organization: Optional. String containing the name of the organization the voucher is representing.¶
+attachments: Optional. Array of JSON objects representing attachments like photocopies of documents or certificates. Structure of members of the attachments array is described in [Attachments].¶
derived_claims: Optional. JSON object containing claims about the end-user which were derived from the vouch described in the evidence array member it is part of (an example is presented later in this document).¶
derived_claims element may contain any of the claims defined in section 5.1 of the OpenID Connect specification [OpenID] and the claims defined in [OpenID4IDAClaims].¶
+derived_claims element may also contain other end-user claims (not defined in the OpenID Connect specification [OpenID] nor in [OpenID4IDAClaims]) derived from the vouch described in the evidence array member it is part of.¶
+derived_claims element shall not be empty.¶
+electronic_signature
+ The following elements are contained in an electronic_signature evidence sub-element.¶
type: Required with value set to electronic_signature.¶
signature_type: Required. String denoting the type of signature used as evidence. The value range might be restricted by the respective trust framework.¶
issuer: Required. String denoting the certification authority that issued the signer's certificate.¶
serial_number: Required. String containing the serial number of the certificate used to sign.¶
created_at: Optional. The time the signature was created as ISO 8601 [ISO8601] YYYY-MM-DDThh:mm[:ss]TZD format.¶
attachments: Optional. Array of JSON objects representing attachments like photocopies of documents or certificates. Structure of members of the attachments array is described in [Attachments].¶
derived_claims: Optional. JSON object containing claims about the end-user which were derived from the electronic signature described in the evidence array member it is part of.¶
derived_claims element may contain any of the claims defined in section 5.1 of the OpenID Connect specification [OpenID] and the claims defined in [OpenID4IDAClaims].¶
+derived_claims element may also contain other end-user claims derived from the electronically signed object described in the evidence array member it is part of, such as elements of an advanced electronic signature described under eIDAS used to uniquely link the signed object to the signatory.¶
+derived_claims element shall not be empty.¶
+During the identity verification process, specific document artifacts could be collected 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 supported by the claim provider and requested by the claim recipient, these elements can be included in the verified claims response allowing the claims recipient to store these artifacts along with the verified claims information.¶
+An attachment is represented by a JSON element. The definition of attachments and the schema representing them are described in [Attachments].¶
+{
+ "verified_claims": {
+ "verification": {
+ "trust_framework": "eidas",
+ "assurance_level": "substantial"
+ },
+ "claims": {
+ "given_name": "Max",
+ "family_name": "Meier",
+ "birthdate": "1956-01-28",
+ "place_of_birth": {
+ "country": "DE",
+ "locality": "Musterstadt"
+ },
+ "nationalities": [
+ "DE"
+ ]
+ }
+ }
+}
+¶
+{
+ "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": "pvp",
+ "time": "2012-04-22T11:30Z"
+ },
+ {
+ "check_method": "vpip"
+ }
+ ],
+ "document_details": {
+ "type": "de_erp_replacement_idcard",
+ "issuer": {
+ "name": "Stadt Augsburg",
+ "country": "DE"
+ },
+ "document_number": "53554554",
+ "date_of_issuance": "2010-04-23",
+ "date_of_expiry": "2020-04-22"
+ }
+ },
+ {
+ "type": "document",
+ "check_details": [
+ {
+ "check_method": "vpip",
+ "time": "2012-04-22T11:30Z"
+ }
+ ],
+ "document_details": {
+ "type": "utility_statement",
+ "issuer": {
+ "name": "Stadtwerke Musterstadt",
+ "country": "DE",
+ "region": "Niedersachsen",
+ "street_address": "Energiestrasse 33"
+ },
+ "date_of_issuance": "2013-01-31"
+ }
+ }
+ ]
+ },
+ "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": "eidas",
+ "assurance_level": "substantial"
+ },
+ "claims": {
+ "given_name": "Max",
+ "family_name": "Meier",
+ "birthdate": "1956-01-28",
+ "place_of_birth": {
+ "country": "DE",
+ "locality": "Musterstadt"
+ },
+ "nationalities": [
+ "DE"
+ ]
+ }
+ },
+ {
+ "verification": {
+ "trust_framework": "de_aml",
+ "time": "2012-04-23T18:25Z",
+ "verification_process": "f24c6f-6d3f-4ec5-973e-b0d8506f3bc7",
+ "evidence": [
+ {
+ "type": "document",
+ "check_details": [
+ {
+ "check_method": "pipp",
+ "time": "2012-04-22T11:30Z"
+ }
+ ],
+ "document_details": {
+ "type": "idcard"
+ }
+ }
+ ]
+ },
+ "claims": {
+ "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",
+ "document_details": {
+ "type": "de_erp_replacement_idcard",
+ "document_number": "53554554",
+ "date_of_expiry": "2020-04-22"
+ },
+ "derived_claims": {
+ "given_name": "Max",
+ "family_name": "Meier",
+ "birthdate": "1956-01-28",
+ "nationalities": [
+ "DE"
+ ]
+ },
+ "check_details": [
+ {
+ "check_method": "vpip",
+ "time": "2012-04-22T11:30Z"
+ }
+ ]
+ },
+ {
+ "type": "document",
+ "document_details": {
+ "type": "utility_statement",
+ "date_of_issuance": "2013-01-31"
+ },
+ "derived_claims": {
+ "given_name": "Maximillion",
+ "family_name": "Meier",
+ "address": {
+ "locality": "Maxstadt",
+ "postal_code": "12344",
+ "country": "DE",
+ "street_address": "An der Weide 22"
+ }
+ },
+ "check_details": [
+ {
+ "check_method": "vpip",
+ "time": "2012-04-22T11:30Z"
+ }
+ ]
+ }
+ ]
+ },
+ "claims": {
+ "given_name": "Max",
+ "family_name": "Meier",
+ "birthdate": "1956-01-28",
+ "nationalities": [
+ "DE"
+ ],
+ "address": {
+ "locality": "Maxstadt",
+ "postal_code": "12344",
+ "country": "DE",
+ "street_address": "An der Weide 22"
+ }
+ }
+ }
+}
+¶
+The working group has identified no security considerations that pertain directly to this specification.¶
+The data structures described in this specification will contain personal information. Standards referencing this specification and implementers using this specification should consider the secure transport of these structures and security and privacy implications that may arise from their use.¶
+This specification requests registration of the following value in the IANA "JSON Web Token Claims Registry" established by [RFC7519].¶
+verified_claims
+ verified_claims¶
+The following people at yes.com and partner companies contributed to the concept described in the initial contribution to this specification:¶
+We would like to thank the following people for their valuable feedback and contributions that helped to evolve this document:¶
+Copyright (c) 2026 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, Final Specification, or Final Specification Incorporating Errata Corrections solely for the purposes of (i) developing specifications, and (ii) implementing Implementers Drafts, Final Specifications, and Final Specification Incorporating Errata Corrections 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 (found at openid.net) requires contributors to offer a patent promise not to assert certain patent claims against other contributors and against implementers. OpenID 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.¶
+