Within Mobile Connect the claims parameter is used to specify specific claims and associated values to be returned from the relevant Resource Endpoint when making a KYC match request. The value is a JSON object listing the requested claims. Below is a sample JSON object.

{  
   "premiuminfo":{  
      "given_name":{  
         "value":"henrydorsett"
      },
      "family_name":{  
         "value":"case"
      },
      "houseno_or_housename":{  
         "value":"1"
      },
      "postal_code":{  
         "value":"19840701"
      },
      "town":{  
         "value":"chibacity"
      },
      "country":{  
         "value":"japan"
      }
   }
}

Normalisation

The Mobile Connect KYC Match service allows attribute values to be included in the OIDC Authorization Request claims parameter in a plain text format or in a hashed form. In plain text form the attributes can be presented in a number of different ways – lower case, upper case, capitalised, use of abbreviations, spurious spaces, etc. This text can be normalised by the operator to align with their internal data processes, so reducing false negatives.

This normalisation process cannot happen if the input values is hashed in the request. In order to minimise the number of false negative matches that could occur it is necessary to ensure that the operators and service provider agree a set of normalisation rules in advance. For example this could be:

  • All whitespace characters removed
  • All characters converted to lower case
  • All strings truncated to 20 characters

Hashing

The match data may be hashed in the request so that user data is not transmitted or shared. If the operator supports or requires hashed requests then the mc_kyc_hashed scope should be used. The hashing algorithm to be used will be published in the operators Provider Metadata document. Below you can see the Sandbox hashing algorithm statement.

   "mc_hash_algs_supported":[  
      "SHA-256"
   ],

When the request uses hashed claims it is important to ensure that the data is normalised correctly. The operator will normalise their data before hashing and comparing. If no or different normalisation is used then a large number of false negatives may occur.

KYC Claims values

The table below indicates the possible claims values. The claims must include a name (either given_name + family_name or name) and an address (either houseno_or_housename + postal_code + (optionally town and/or country or address). The birthdate claim is optional. When making a hashed request the values should have a _hash suffix. For example name becomes name_hash.

The table below shows both plain and hashed attribute names.

Attribute Usage Description

given_name

or

given_name_hash

REQUIRED*

Given name(s) or first name(s) of the end-user. Multiple given names are supported, names being separated by space characters. Always used in conjunction with the family_name attribute.

family_name

or

family_name_hash

REQUIRED*

The family name(s), surname(s) or last name(s) of the end-user. All can be present, with the names being separated by space characters. Always used in conjunction with the given_name attribute.

name

or

name_hash

REQUIRED*

Concatenated given_name and family_name.

houseno_or_housename

or

houseno_or_housename_hash

REQUIRED

Registered house number or house name.

postal_code

or

postal_code_hash

REQUIRED

Registered zip code or post code.

town

or

town_hash

OPTIONAL

Registered city or town name.

country

or

country_hash

OPTIONAL

Registered country.

address

or

address_hash

REQUIRED

Concatenated houseno_or_housename, postal_code and optionally town and country.

birthdate

or

birthdate_hash

OPTIONAL

The end-user's birthday, represented as an ISO 8601:2004 YYYY-MM-DD format. The year MAY be 0000, indicating that it is omitted.

 

Claims qualifiers

The claims object can also include optional claims qualifiers that that provide guidance to the ID gateway and indicate expectations of the claims that should be returned in the response. Mobile connect supports the following qualifiers essential, value and values. The example below shows how the can be used.

{  
   "premiuminfo":{  
      "name_hash":{  
         "value":"10b182c8d5395b6f9279848b5bcc070071644cb09548b2fd5dad09dbb290ba3a"
      },
      "name_match":{  
         "essential":true, values:["Y","N-AV", "N-AD", "N-NA"]
      },
      "address_hash":{  
         "value":"ab7898d762572dbe066ccd14f25d9b8f3c1dc405a24ae4f1b611755ac517b8ff"
      }
      "address_match":{  
         "essential":true, values:["Y","N-AV", "N-AD", "N-NA"]
      }
      "account_state" :{
         "value":"active"
      }
   }
}

Claims qualifiers are specified in section 5.5.1 of OpenID Connect Core 1.0

 

* Either given_name + family_name OR name is required.

† Either houseno_or_housename + postal_code OR address is required.