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.