KYC Claims

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.

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.