Align kyc-match with commonalities for meta spring25

[fernandopradocabrillo]

What type of PR is this?

Add one of the following kinds:

• correction
• enhancement/feature

What this PR does / why we need it:

This PR replaces outdated PR #115. Align error model and include required info.description sections according to latest Commonalities agreements (v0.5.0)

[ToshiWakayama-KDDI]

Hi @fernandopradocabrillo ,

Thanks very much for creating the PR. Even though this is for commonalities alignment, there are a lot included. Please allow me to take some time to confirm. I need to consult with my product team.

Many thanks,
Toshi

[ToshiWakayama-KDDI]

Hi @fernandopradocabrillo , @GillesInnov35 , all,

We/KDDI would like to keep the optional phoneNumber even when using a three-legged access token, as the KYC Match API has the optional phoneNumber input since its initial version and so KDDI has already provided API Consumers with this
function (optional phoneNumber). If the input phoneNumber is different from the phone number derived from the access token, 403 Invalid_token_context error is returned. This is for API Consumers (and End users) benefit and convenience. In addition to API Consumers (and End users) benefit and convenience, from backward compatibility perspective, we would like to keep this (the optional phoneNumber even when using a three-legged access token). The Mis-use discussion in Commonalities ended with inclusion of KYC Match as the exception, i.e. KYC Match could have the optional phoneNumber input if the sub-project wants to do so, and it is understood that the commonalities template could be customized by the sub project.

Concretely, the above proposal will affect 'Identifying the phoneNumber from the access token' part and 'Error handling' part of the KYC Match YAML proposal.

Is this proposal acceptable to all?

Best regards,
Toshi

[HuubAppelboom]

@ToshiWakayama-KDDI, all.

From KPN side, we have a different proposal than using an error code in case there is a phone number mismatch with the 3 legged authorization code flow. This proposal is much more in line how the results on other data points are returned in Match, and this is also more flexible towards API Consumers and friendly for end users.

The current implementation returns always an error in case an end user enters the wrong phone number , and as a result the verification results on the other data points are not returned.

This is problematic for those API Consumers which are mainly interested in the other data points, for example a name + address check, or a name + date date of birth check. Most of our customers in the Netherlands fall into this category, and for them the phone number is an extra nice to have data point, for example to prevent fraud, but not a must have. In case there is a mismatch, they would have to ask the end user again for the right number etc, or submit the API again without the phone number in the request body.

We think this kind of friction can be entirely avoided if the number verification result is returned in exactly the same way as the result of the other data points, so as a MatchResult which is true, false or not_available.

In case end user happens to have typed the wrong number or made a typing error, the API Consumer can still decide to use the verification results on the other data points, and decide themselves what to do with the phone number that the end user has entered. They can either completely disregard it, or store it as an unverified number in their customer database, or ask the end user again what the correct number is and verify the number again if that is necessary

This proposal is much more friendly towards API Consumers (they can decide what to do with the information), it is in line what we do with the other data points and with the regular Number Verification, and for API Providers that want to charge extra for the included phone number verification, and extra charge may also be much more easier to implement, because you can base the tariff entirely on the data attributes which are present in the request body of the response.

[ToshiWakayama-KDDI]

Hi @HuubAppelboom , all,

Thanks for your comment.

Please let me understand your comment clearly. So, your proposal is: to accept the optional 'phoneNumber' input even though the 3-legged authorization code flow is used, and to return true/false/not_available for 'phoneNumber' as it is one of the parameters/attributes. Is this correct understanding?

If yes, will the input phoneNumber be compared to the phone number derived from the access token, and not the phone number the MNO (API provider) has? (Maybe these two phone numbers are supposed to be the same, though.)

Thanks,
Toshi

[HuubAppelboom]

@ToshiWakayama-KDDI , all Yes, the proposal is to process the phonenumber information from the request body in case of a authorization code flow in exactly the same way as the other data attributes (like name, date of birth, etc).

The phone number associated with the access token in case of the authorization code flow is by definition always the number retrieved from the mobile network, and should always be treated as the correct number, againts which all verifications should be done. In the authorization flow the phone number in the request body is always the phone number the user has entered.

[GillesInnov35]

hi @HuubAppelboom, you've confirmed that in your proposition

the input phoneNumber be compared to the phone number derived from the access token

I'm wondering why the phoneNumber attributes (if provided in the request body) should be managed differently from the others parameters if the objectives of the API is to check and compare provided attributes with those held by the MNO.

Gilles

[HuubAppelboom]

hi @HuubAppelboom, you've confirmed that in your proposition

the input phoneNumber be compared to the phone number derived from the access token

I'm wondering why the phoneNumber attributes (if provided in the request body) should be managed differently from the others parameters if the objectives of the API is to check and compare provided attributes with those held by the MNO.

Gilles

@GillesInnov35 Hi Gilles,

No, I think you misunderstand it. The idea is that we process all the data attributes that are provided in the request body in the same way, including the phone number attribute. All these data attributes are presumably the data the end user has provided to the API consumer. All these attributes are compared to what the MNO holds (based on the phone number associated with the Access Token, because that is in the authorization code flow always correct).

[ToshiWakayama-KDDI]

Thanks, @huub. We/KDDI are happy with Huub KPN's proposal and support the proposal to have 'phoneNumber' one of the optional parameters and to return 'phoneNumberMatch' result (true/false/not_available).

Probably four changes will be needed as overviewed below:

1. API General Description
The following points to be added:

• 'phoneNumber' can be input as an optional parameter even when the three-legged access flow is used.
• The phone number is derived from the access token, and it is used for identifier of the subscription contract to check.
• Together with other parameters, 'phoneNumber' will be checked with that of MNO's, and the match result of 'phoneNumber' will be returned.

2. Identifying the phoneNumber from the access token

• In the two-legged access flow case, 'phoneNumber' must be provided. (no change)
• In the three-legged access flow case, the 'phoneNumber' can be input as on optional parameter, but the phone number of the device is derived from the access token and it is used for the key identifier of the subscription.

3. Error handling

• 422 MISSING_IDENTIFIER is still valid. (no change)
• 422 UNNECESSARY_IDENTIFIER is not valid for KYC Match and to be removed.

To note, when the phone number derived from the access token and the input 'phoneNumber' are different, API will return 'false', not an error.

4. API definition

• Add 'phoneNumber' in the request example for 3-legged access token.
• Add 'phoneNumberMatch' parameter definition, and add it in the response example.
• Add 'phoneNumberMatch' definition

Please point out anything missing or wrong, as the above is based on my quick thoughts.

Thanks,
Toshi

[HuubAppelboom]

Thanks, @huub. We/KDDI are happy with Huub KPN's proposal and support the proposal to have 'phoneNumber' one of the optional parameters and to return 'phoneNumberMatch' result (true/false/not_available).

Probably four changes will be needed as overviewed below:

1. API General Description The following points to be added:

• 'phoneNumber' can be input as an optional parameter even when the three-legged access flow is used.
• The phone number is derived from the access token, and it is used for identifier of the subscription contract to check.
• Together with other parameters, 'phoneNumber' will be checked with that of MNO's, and the match result of 'phoneNumber' will be returned.

2. Identifying the phoneNumber from the access token

• In the two-legged access flow case, 'phoneNumber' must be provided. (no change)
• In the three-legged access flow case, the 'phoneNumber' can be input as on optional parameter, but the phone number of the device is derived from the access token and it is used for the key identifier of the subscription.

3. Error handling

• 422 MISSING_IDENTIFIER is still valid. (no change)
• 422 UNNECESSARY_IDENTIFIER is not valid for KYC Match and to be removed.

To note, when the phone number derived from the access token and the input 'phoneNumber' are different, API will return 'false', not an error.

4. API definition

• Add 'phoneNumber' in the request example for 3-legged access token.
• Add 'phoneNumberMatch' parameter definition, and add it in the response example.
• Add 'phoneNumberMatch' definition

Please point out anything missing or wrong, as the above is based on my quick thoughts.

Thanks, Toshi

@ToshiWakayama-KDDI Hi Toshi, to me it looks ok.
Just one question though. Should we mention that it is only relevant for the Authorization Code flow (and not for CIBA, which is also a 3 legged flow) ?

[ToshiWakayama-KDDI]

Hi @HuubAppelboom ,

@ToshiWakayama-KDDI Hi Toshi, to me it looks ok. Just one question though. Should we mention that it is only relevant for the Authorization Code flow (and not for CIBA, which is also a 3 legged flow) ?

Could you advise me why the CIBA case should be excluded, please?

Many thanks,
Toshi

[HuubAppelboom]

Hi @HuubAppelboom ,

@ToshiWakayama-KDDI Hi Toshi, to me it looks ok. Just one question though. Should we mention that it is only relevant for the Authorization Code flow (and not for CIBA, which is also a 3 legged flow) ?

Could you advise me why the CIBA case should be excluded, please?

Many thanks, Toshi

@ToshiWakayama-KDDI In the CIBA Flow the login_hint contains by definition the phone number (that end user has given to the API Consumer). In the Ciba flow, you don't retrieve a phone the real phone number from the network like in the Authorization Code flow. The phone_number in the request body is also always the phone number the end user has given to the API Consumer, so by definition it is always the same as in the login_hint. And because you don't have a phone number retrieved from the network, you can't verify it.

[ToshiWakayama-KDDI]

Hi all,
Here is one of the proposed changes for the optional phoneNumber matching:

• When a three-legged access token is used however, this optional identifier MUST NOT be provided, as the subject will be uniquely identified from the access token.

To be replaced by:

• when a three-legged access token is used, the subject will be uniquely identified from the access token. So, the opitional phoneNumbe is not used for identifying the subject, but, if the optional phoneNumber is input in the API request body, it will be compared with the phone number that tha API Provider (Operator) has in its operational system.

WDYT?

Best,
Toshi

[fernandopradocabrillo]

To reflect current behaviour I proposed the following:

When a three-legged access token is used, the subject will be uniquely identified from the access token. So, the optional phoneNumber is not used for identifying the subject, but, if it is provided in the API request body, it needs to match with the one associated with the access token

[ToshiWakayama-KDDI]

Hi all,
This is another one of proposed changes for the optional phoneNumber matching:

This approach simplifies API usage for API consumers using a three-legged access token to invoke the API by relying on the information that is associated with the access token and was identified during the authentication process.

The above is to be deleted, as it does not apply.

It may be worth adding some note, instead, like:
Note: This approach is a bit different from most of other APIs aligning with Commonalities v0.5, however, Commonalites v0.5 allows KYC Match to follow this approach.

WDYT?

Best,
Toshi

[GillesInnov35]

thanks @ToshiWakayama-KDDI, I think all those specifications should be described in API guidelines and not in yaml to avoid a complex overview with detailed secenarios. But as currently no guidelines are available we could add them.

Gilles

[fernandopradocabrillo]

I'd avoid mentioning specific Commonalities releases and versions inside the yaml. I'm inclined to think that right now the best thing would be to remove this sentence and complete the error responses detailing the behaviour of the API.
I'll upload a proposal and you tell me what you think about it.

[ToshiWakayama-KDDI]

Hi all,
This is another one of proposed changes for the optional phoneNumber matching:

• If the subject can be identified from the access token and the optional phoneNumber field is also included in the request, then the server will return an error with the 422 UNNECESSARY_IDENTIFIER error code. This will be the case even if the same phoneNumber is identified by these two methods, as the server is unable to make this comparison.

Just to remove the above part, as the above is for using a three-legged access token and we would accept the opitional phoneNumber field.

WDYT?

Best,
Toshi

[fernandopradocabrillo]

yes, removed

[ToshiWakayama-KDDI]

Hi all,
Just a comment relating to the proposal of the optional phoneNumber matching. My understanding is that the above sentence applies to the cases when using a two-legged access token (so the subject cannot be identified from the access token), and if the optional phoneNumber field, which is 'must' for using a two-legged access token, is not indluded in the request, 422 MISSING_IDENTIFIER is returned.

Best,
Toshi

[fernandopradocabrillo]

Hi Toshi, yes, that is the intended case for this error. Or at least the only one I've seen across APIs in different workgroups

[ToshiWakayama-KDDI]

Hi all,
This is another proposed change for the optional phoneNumber matching:
Is it worth adding '*Required' to phoneNumber: '+34629255833', as it must be included in two-logged access token cases?

Best,
Toshi

[fernandopradocabrillo]

This can be better describe in the info.description section. I have complete the text, take a look and let me know

[ToshiWakayama-KDDI]

Hi all,
This is another proposed change for the optional phoneNumber matching:
Just to add below (phoneNumber paramter) above idDocument
phoneNumber: '+34629255833'

WDYT?

Best,
Toshi

[fernandopradocabrillo]

I have upodate the examples and descriptions

[ToshiWakayama-KDDI]

Hi all,
This is another proposed change for the optional phoneNumber matching:

L174 examples:
L175 KYC_Match200Example:
L176 value:
L177 idDocumentMatch: 'true'

Just to add the following between L176 value: and L177 idDocumentMatch: 'true'
phoneNumberMatch: 'true'

Best,
Toshi

[ToshiWakayama-KDDI]

Hi all,
This is another proposed change for the optional phoneNumber matching:

L348 KYC_MatchResponse:
L349 type: object
L350 properties:
L351 idDocumentMatch:
L352 allOf:
L353 - $ref: '#/components/schemas/MatchResult'
L354 - description: Indicates whether Id number associated to the ID document of the customer matches with the one on the Operator's system.

Just to add the following four lines between L350 properties: and L351 idDocumentMatch:

• phoneNumberMatch:
• allOf:
• -- $ref: '#/components/schemas/MatchResult'
• -- description: Indicates whether the phone number of the customer input by he API Consumer matches with the one on the Operator's system.

I think this is the last one. Sorry that I put my proposed changes in a bit rude way, as I needed to hurry. If you do not understand what each proposal is please let me know.

Many thanks,
Toshi

[fernandopradocabrillo]

Hi all,
As we don't have margin to discuss the inclusion of the phoneNumberMatch property and its functionality and having in mind the exception in error behaviour requested by KDDI, I have updated the PR to revert the functionality to the same behaviour that we have always have.
The PR also contains required changes from Commonalities v0.5.0: required info.descriptions, error format with enums, etc nothing disruptive.

Thanks

[GillesInnov35]

Thanks a lot Fernando.

[ToshiWakayama-KDDI]

Hi all, As we don't have margin to discuss the inclusion of the phoneNumberMatch property and its functionality and having in mind the exception in error behaviour requested by KDDI, I have updated the PR to revert the functionality to the same behaviour that we have always have. The PR also contains required changes from Commonalities v0.5.0: required info.descriptions, error format with enums, etc nothing disruptive.

Thanks

Thanks, @fernandopradocabrillo ,

I agree with your point that we do not much time to discuss the inclusion of the phoneNumberMatch. I have proposed some changes already, but now I know it is not that simple. Let's discuss this for the next version.

So the latest proposal is LGTM, and I will approve.

Thanks,
Toshi