OpenID Connect Identity Assurance / eKYC explained

The digital economy, with recent innovations such as smart contracts, cannot meaningfully evolve into new areas without easy, standard access to verified identities. This fundamental need inspired the new eKYC / Identity Assurance extension to OpenID Connect. Applications and services can now use it to obtain verified person data and metadata.

1. Knowing your customer

For a transaction or contract to be valid and enforceable under the law one crucial and perhaps too obvious criteria which must be met is this - the parties involved must be who they claim to be. This applies to all contracts, on paper as well as those made online.

One relatively simple and universal method to verify a customer's identity online is to submit their credit card or other payment method for validation. But this approach has assurance issues and limitations - in terms of reliably identifying the person, to which the reported annual global credit card fraud exceeding U$20B testifies, and in terms of the details that can be checked, typically limited to name and postal address.

Depending on the type of transaction, perceived risk and government regulations which must be met, such as anti-money laundering laws, a business may require a stronger and more adequate assurance of identity to conduct its transactions digitally and online.

2. Legal and contractual concerns in online transactions

Three concerns normally come up when businesses consider a shift to online transactions:

  • That the identity of the other party, such as legal name and being of legal age, is sufficiently verified to rest assured that the contract governing the transaction is legally valid and enforceable by law.

  • That other data crucial for the contract fulfillment, for example delivery address, wire transfer details or credit score, is also verified.

  • That the business doesn't get dragged into some scam or fraud scheme via the transaction, potentially breaking anti-money laundering or similar laws, and is able to demonstrate it has has performed all due diligence, which also involves assurance of customer identity and collecting required details.

A good scheme for Know Your Customer (KYC) and Identity Assurance (IdA) in general must cater for all of the above concerns.

The OpenID specification for eKYC / IdA may appear a bit complex at first look, but this is to ensure it ticks all boxes regarding the possible legal concerns of adopters, besides it being a protocol with technical merits.

3. OpenID Connect eKYC / IdA is an international effort

The OpenID Connect eKYC / IdA standard is developed at an open working group at the OpenID Foundation, with international participants and the objective to make it useful in various jurisdictions around the world.

As of January 2020 the specification has received contributions from the UK, US, Canada, Germany and Japan.

4. Relationship to OpenID Connect

Those familiar with OpenID Connect will notice how seamlessly the eKYC / IdA extension integrates into the protocol.

OpenID Connect has become a popular internet standard for single sign-on and identity provisioning. Client applications, called relying parties (RP), receive the user's identity in a digitally signed object called ID token. Additional details about the user, called claims, can also be requested and if consented and available the OpenID provider puts them up for retrieval in JSON or signed JWT format at its UserInfo endpoint, in exchange for an access token.

To support the provision of verified identities the core OpenID Connect protocol is extended in two places:

  • A verified_claims element is defined for the optional claims OpenID authentication request parameter.

  • A verified_claims element is defined for the ID token or UserInfo to return the actual verified claims and metadata about the verification.

5. Requesting verified claims

A relying party requests verified claims via the existing claims OpenID authentication request parameter. This parameter is a JSON object, specifies if a claim is to be provided in the issued ID token or at the UserInfo endpoint, also optional requirements and constraints.

Here is an example claims parameter for requesting the claims given_name, family_name and birthdate to be released at the UserInfo endpoint:

{
  "userinfo":{
    "given_name": null,
    "family_name": null,
    "birthdate": null
  }
}

To request the same claims, but with assurance, their names are put within a verified_claims element like this:

{
  "userinfo":{
    "verified_claims":{
      "verification":{
        "trust_framework": null
      },
      "claims":{
        "given_name": null,
        "family_name": null,
        "birthdate": null
      }
    }
  }
}

The provider can also be asked to return various metadata about the verification process, encoded in the verification element. It will be explained later.

To request the verified claims to be returned in the issued ID token the top-level element is set to id_token:

{
  "id_token":{
    "verified_claims":{
      "verification":{
        "trust_framework": null
      },
      "claims":{
        "given_name": null,
        "family_name": null,
        "birthdate": null
      }
    }
  }
}

The claims request can mix regular and verified claims, and also choose to mix the two methods for releasing them - UserInfo and ID token. For example:

{
  "userinfo":{
    "verified_claims":{
      "verification":{
        "trust_framework": null
      },
      "claims":{
        "given_name": null,
        "family_name": null,
        "birthdate": null
      }
    }
  },
  "id_token":{
    "email": null
  }
}

An example of a complete OpenID authentication request with the URL-encoded claims parameter:

https://c2id.com/login?
response_type=code
&scope=openid
&client_id=123
&state=ohngaisho4ad0Eef
&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
&claims=%7B%22userinfo%22%3A%7B%22verified_claims%22%3A%7B%22verification%22
 %3A%7B%22trust_framework%22%3Anull%2C%7D%2C%22claims%22%3A%7B%22given_name%22
 %3Anull%2C%22family_name%22%3Anull%2C%22birthdate%22%3Anull%7D%7D%7D%7D

When the request is submitted to the OpenID provider the usual steps of user authentication and consent will take place, and if they pass successfully, upon completion of the OAuth 2.0 code flow the relying party will receive its ID token and access token for the UserInfo endpoint.

6. Delivery of verified claims

If the requested verified claims were consented by the end-user and are actually available to the OpenID provider, they will be returned at the UserInfo endpoint and / or the ID token, as chosen by the relying party. If a particular claim isn't consented or not available at the OpenID provider, it is simply omitted, i.e. this doesn't produce an error.

The claims in the UserInfo response and the ID token payload are delivered in a JSON object, keyed by their name.

For regular claims they reside at the top-level of the JSON object, where sub is the unique identifier of the subject (end-user) at the OpenID provider:

{
  "sub"         : "478e4589-0145-42e2-a54e-bc291f9c7af3",
  "given_name"  : "Alice",
  "family_name" : "Adams",
  "birthdate"   : "1987-12-01"
}

Verified claims are put in a specially designated verified_claims element, which includes the provided claims in a claims sub-element, and requested metadata about the verification that took place in a verification sub-element. We'll talk about that metadata later.

{
  "sub"             : "478e4589-0145-42e2-a54e-bc291f9c7af3",
  "verified_claims" : {
    "verification" : {
       "trust_framework" : "eidas_ial_high"
    },
    "claims"       : {
      "given_name"  : "Alice",
      "family_name" : "Adams",
      "birthdate"   : "1987-12-01"
    }
  }
}

The claims delivered at the UserInfo endpoint are normally returned as a plain JSON object, with the HTTP response having an application/json content type. The OpenID provider also has the option to return the UserInfo as a signed JSON Web Token (JWT), to assert that it vouches for the claims, and even apply additional encryption to the JWT, with a public key registered by the relying party, for additional confidentiality on top of that provided by the TLS layer in HTTPS. The HTTP content type will then be application/jwt.

7. Verification metadata

Besides the mechanics for requesting and delivering verified claims, the OpenID Connect eKYC / IdA spec defines a JSON object for describing the verification that took place. This contextual information can be used by relying parties to examine the verification process and to log it for dispute resolution and audit purposes.

The verification element carries the following details, some required, other optional, depending on the trust framework which governs the verification process.

Element Description
trust_framework

An official identifier for the trust framework which applies to the verification. The framework will typically specify the types of claims that can be provided and the assurance, in terms of how the end-user is identified, where the claims come from and what verification guarantees they have.

The trust framework must also specify which elements in the verification are required and any extensions to it. Because of the relative complexity of the verification element documenting a JSON schema for it can be of great help to developers.

An example trust framework identifier is eidas_ial_high, for the eIDAS scheme in the EU of approved providers, which is typically based on qualified electronic signatures or national eIDs. The minimum available attributes are name and birth date.

Other pre-defined trust framework identifiers are de_aml, eidas_ial_substantial, nist_800_63A_ial_2, nist_800_63A_ial_3 and jp_aml, jp_mpiupa. Verified identity providers are free to define other identifiers if needed.

time

Timestamp when the verification took place.

Optional unless required by the trust framework.

verification_process

Unique identifier for the verification that took place at the OpenID provider, intended for dispute resolution and audits.

Optional unless required by the trust framework.

evidence

Information about the evidence used to identify the end-user at the OpenID provider.

Three types of evidences are currently specified, each one expands to its own object with metadata:

  • id_document - Verification based on a government issued identity document, which can be paper based or electronic.
  • utility_bill - Verification based on a utility bill.
  • qes - Verification based on a eIDAS Qualified Electronic Signature.

Optional unless required by the trust framework.

Example verification object for an eIDAS based verification where the person is identified at a "High" assurance level:

{
  "trust_framework"      : "eidas_ial_high",
  "time"                 : "2020-01-08T12:12:59+02:00",
  "verification_process" : "6994ca5a-3615-4347-9062-c9037d847d3b"
}

Example verification object for an identity-card based verification according to the de_aml trust framework conforming with German Anti-Money Laundering Law where physical in-Person proofing (pipp) has taken place:

{
  "trust_framework"      : "de_aml",
  "time"                 : "2020-01-08T12:12:59+02:00",
  "verification_process" : "09793984-ab11-49c5-a800-09d8151f637f",
  "evidence"             : [ {
    "type"     : "id_document",
    "method"   : "pipp",
    "document" : {
       "type"             : "idcard",
       "issuer"           : { "name" : "Stadt Berlin", "country" : "DE" },
       "number"           : "53554554",
       "date_of_issuance" : "2012-04-23",
       "date_of_expiry"   : "2022-04-22"
    }
  } ]
}

Note that each verification parameter, such as trust_framework, time and verification_process, must be specifically requested, otherwise it won't be returned. The IdA / eKYC standard adheres to the principles of privacy and data minimisation, so any piece data must be specifically requested.

Relying parties can also use the verification element within the claims request parameter to shape or constrain the verification process. Note that this feature is somewhat complex to implement and may not be supported by all providers of verified claims.

{
  "userinfo": {
    "verified_claims": {
      "verification": {
        "trust_framework": {
          "value": "jp_aml"
        },
        "time": {
          "max_age": 63113852
        }
      },
      "claims": {
        "given_name": null,
        "family_name": null,
        "birthdate": null
      }
    }
  }
}

8. Advertising OpenID provider support for verified claims

OpenID Connect providers have a neat feature, a well-known endpoint where a JSON document, called OpenID provider metadata, is published. It lists its standard OAuth 2.0 / OpenID Connect server endpoints, capabilities and supported encryption algorithms. Developers of relying party applications use this metadata configure their software.

The URL of the endpoint is obtained by appending .well-known/openid-configuration to the issuer (base) URL of the provider, for example:

Issuer URL https://demo.c2id.com
OpenID provider metadata URL https://demo.c2id.com/.well-known/openid-configuration

Regular OpenID providers list the names of the end-user claims that are made available in the claims_supported parameter, which is a JSON array. Note that not all supported claims may be publicly listed by the OpenID provider, for privacy or other reasons.

The OpenID Connect for eKYC / IdA extends the metadata with additional parameters, to indicate if the provider supports verified claims, their names, the supported trust frameworks and other metadata that may be useful.

  • verified_claims_supported {true|false} Indicates support for OpenID Connect Identity Assurance. If omitted the default value is false.

  • trust_frameworks_supported {string array} List of the supported trust frameworks if OpenID Connect Identity Assurance is supported, omitted or empty if none.

  • evidence_supported {string array} List of the evidence types if OpenID Connect Identity Assurance is supported, omitted or empty if none.

  • id_documents_supported {string array} List of the identity document types if OpenID Connect Identity Assurance is supported, omitted or empty if none.

  • id_documents_verification_methods_supported {string array} List of the identity document verification methods if OpenID Connect Identity Assurance is supported, omitted or empty if none.

  • claims_in_verified_claims_supported {string array} List of the supported verified claims if OpenID Connect Identity Assurance is supported, omitted or empty if none.

An example snippet for an OpenID provider which supports verified claims:

{
  "issuer"                              : "https://c2id.com",
  "userinfo_endpoint"                   : "https://c2id.com/userinfo",
  "claims_supported"                    : [ "email",
                                            "name",
                                            "given_name",
                                            "family_name",
                                            "birthdate" ],
  "verified_claims_supported"           : true,
  "trust_frameworks_supported"          : [ "eidas_ial_high" ],
  "evidence_supported"                  : [ "qes" ],
  "claims_in_verified_claims_supported" : [ "name",
                                            "given_name",
                                            "family_name",
                                            "birthdate" ],
  ...
}

9. UI hints for the consent screen

A recent survey indicates customers abandon 53% of transactions online. After "lack of visible security", the second top reason is too much information being asked for.

In the spirit of data minimisation relying parties shouldn't request more than the necessary set of claims to perform the transaction. Conversion and the overall quality of the user experience increases when customers are in the clear why the particular details are being required.

The ekYC / IdA extension defines an optional parameter to the OpenID authentication request, called purpose, which lets the relying party explain why the verification is being requested. The provider is expected to display the message in the consent screen.

The extension goes a step further and even allows the relying party to give an explanation for each individual requested claim within the claims request parameter, for example:

{
  "userinfo": {
    "verified_claims": {
      "verification": {
        "trust_framework": null
      },
      "claims": {
        "address": {
          "essential": true,
          "purpose": "Required for insurance policy calculation"
        }
      }
    }
  }
}

10. Standard and custom claims

The OpenID Connect core specification and the eKYC / IdA extension define a number of standard claims.

Useful OpenID Connect core claims in the context of eKYC / IdA:

  • name
  • given_name
  • middle_name
  • family_name
  • birthdate
  • address

Additional standard claims defined in eKYC / IdA:

  • place_of_birth, with sub-members country, region and locality
  • nationalities
  • birth_family_name
  • birth_given_name
  • birth_middle_name
  • salutation
  • title
  • msisdn

When a provider needs to define a custom claim, it's good practise to prefix the claim name with a unique string, such as an URL based on the OpenID provider's issuer URL.

For example:

https://claims.some-idp.com/iban

11. Verified claims support in the OpenID Connect SDK and the Connect2id server

The open source OAuth 2.0 / OpenID Connect SDK introduced support for verified claims in version 6.21, allowing those to be constructed and parsed with type safety and observing the schema for the verified_claims element.

The Connect2id server for single sign-on and identity provisioning introduced support for eKYC / IdA in release 8.0.

12. Complementary security standards

To uphold a high standard of security against theft of PII providers of verified identities will typically require strong client authentication and access tokens with cryptographic protection against leaks and unauthorised replay. This can be obtained by utilising OAuth 2.0 mutual-TLS client authentication and certificate-bound access tokens (RFC 8705), which is incorporated in the FAPI security profile.

The mTLS extension and the FAPI profile are readily supported by the Connect2id server.

13. FAQ

13.1 Where is the complete specification?

The specification can be found on the page of the eKYC / IdA working group at the OpenID Foundation:

https://openid.net/wg/ekyc-ida/

13.2 Does the provision of verified identities according to this spec also imply any legal liability for them?

The provision of identities with eKYC by itself doesn't imply any legal liability about the "verified" quality of the claims, this must be governed by the service contract and its terms and conditions. Consult with a lawyer.


comments powered by Disqus