How to implement OpenID Connect eKYC / Identity Assurance

Providers of verified identities are encouraged to utilise the new OpenID Connect extension for eKYC and Identity Assurance. This guide explains how to configure the Connect2id server (v8.0+) and your integrations for that.

1. Configuration

1.1 OpenID provider metadata

Configure the Connect2id server to advertise support for the eKYC / IdA extension, such as the available trust frameworks and verified claims.

Example configuration for eIDAS at level of assurance "High":

op.assurance.supportsVerifiedClaims=true
op.assurance.supportedTrustFrameworks=eidas_ial_high
op.assurance.supportedIdentityEvidenceTypes=qes
op.assurance.supportedVerifiedClaims=name,given_name,family_name,birthdate

1.2 Claims parameter in the consent prompt

Configure the Connect2id server to include the raw claims parameter in the consent prompt during authorisation sessions.

Access to the raw claims parameter is needed so that the verified_claims element can be parsed and examined by the provider specific authentication handler and logic for IdA.

op.authz.includeRawClaimsRequestInPrompt=true

2. Integration

2.1 Authorisation session

For the authorisation session handler to process relying party (RP) requests for verified claims:

  • The handler should parse the raw claims parameter to obtain the verified_claims element. This can be done with Nimbus OAuth 2.0 / OpenID Connect SDK.

    At minimum the handler should find out if the OpenID authentication request is for verified claims and get their names. If the handler is capable it can also check for present verification metadata in the request, which may include constraints and other parameters to the IdA process.

    The raw claims request parameter can be obtained from the claims -> raw_request parameter of the consent prompt or by HTTP GET of the authorisation session object which keeps a record of all request parameters.

  • If the RP has set the purpose parameter to explain why verification is being requested, the provider should display the message in the consent screen to the end-user.

    The RP may also attach a purpose message to each individual requested claim. These messages can be obtained by drilling down into the claims request parameter. For example:

    {
    "userinfo" : {
      "verified_claims" : {
        "claims" : {
          "address" : {
            "essential" : true,
            "purpose" : "Required for insurance policy calculation"
          }
        }
      }
    }
    }
    
  • The handler should put the consented verified claims into the usual claim parameter of the consent object. Prefix each verified claim name with a suitable string, e.g. v: -> v:given_name, so that the claim source can distinguish the verified claims from the regular ones when composing the UserInfo object.

    Example consent for verified (name, address) and regular claims (email):

    {
    "scope" : [ "openid" ],
    "claims" : [ "email", "v:name", "v:address" ]
    }
    

    If a verified claim is to be delivered in the ID token instead of the UserInfo response, prefix its name with id_token:. For example:

    {
    "scope" : [ "openid" ],
    "claims" : [ "id_token:v:name", "id_token:v:address" ]
    }
    
  • Update the claims source of the Connect2id server to detect if the list of the consented claims includes verified ones (e.g. via the suggested v: prefix), and put them into the verified_claims element, together with the necessary verification metadata, as shown in this example.

  • If the authorisation session handler needs to pass data for the construction of the verification element (or its entire JSON object) to the claims source, it can do so via an artificial claim, e.g. verification:{....

3. Future improvements

Connect2id server improvements which are being considered to ease processing of eKYC / IdA requests:

  • The op.authz.includeRawClaimsRequestInPrompt setting to cause the raw claims request parameter to also be included in the authentication prompt. This will allow a provider which supports multiple levels of authentication assurance (ACR / LoA) to find out which one is appropriate for a verified claims request (in the absence of an acr_values request parameter or when it doesn't match the ACR required for verified claims).

  • Update the consent prompt to include the requested verified claims, together with the optional verification metadata and the purpose messages to the handler.

  • Update the consent and the claims source SPI to allow clear indication of the verified claims and to enable passing of optional verification metadata from the authorisation session handler.