Initial contribution of Age_Verification.yaml #50

ToshiWakayama-KDDI · 2024-02-02T10:40:23Z

What type of PR is this?

enhancement/feature

What this PR does / why we need it:

Initial contribution of Age_Verification.yaml to create the initial version of Age Verification API (v0.1.0)

Which issue(s) this PR fixes:

Related to Issue Creation of a Pull Request for Age Verification API #46

Special notes for reviewers:

Changelog input

Additional documentation

Update the design proposal for Age Verification API specifications

GillesInnov35 · 2024-02-02T13:21:52Z

To start the discussion

Some functional restrictions may exist, for example:
- User's phone number must be the primary phone number of the contract holder because the age of secondary phone number and (particularly for a minor) must not be stored according to the local law
- the returned attribute isVerified (boolean) could be replaced by a string (enum=Y:Yes, N-AV: No, information available, N-NAV: No, information not available).
Also, some information could be help with the decision,
- does a parental control exist for this user phone number?
- tenure of the contract

GillesInnov35

Thanks

GillesInnov35 · 2024-02-05T14:12:01Z

Proposition of User Story

User Story: KYC Age Verification - Verify the age of a user

Item	Details
Summary	As an application developer of an age-restricted site or application, I want to verifiy the age of a customer with user's information held by the MNO.
Roles, Actors and Scope	Roles: Customer:User Actors: Mobile Network Operators (MNO), hyperscalers, application developers, enterprise. Scope: Any phone line (not limited to 4G, 5G)
Pre-conditions	The preconditions are listed below: The Customer:User has provided mandatory information of its identity Application developer has onboarded to MNO API Application developer has API credentials Privacy legal base requirement has been solved (Customer privacy)
Activities/Steps	Starts when: The customer application server makes a request to the Age Verification service (API) with the age restricted value. Ends when: The MNO service returns *True* if the age has been correctly verified else it returns *False*.
Post-conditions	The application developer can make decision to use this customer data to follow-up its process
Exceptions	Several exceptions might occur during the KYC Age Verification API operations: Unauthorized: Not valid credentials (e.g. use of already expired access token). Not Found: The number provided is not managed by the MNO Invalid input: Not all mandatory input data to invoke operation (e.g. phone number).

Add firstName and FamilyName attributes to be compared with MNO information

Addition of MiddleNames

GillesInnov35 · 2024-03-12T08:49:23Z

Find a draft proposal of API documentation (to be reviewed)
KYC-AgeVerify.MD

with Huub (KPN) proposition: assurance level

ToshiWakayama-KDDI · 2024-04-01T10:16:21Z

Hi @GillesInnov35 , all,

Regarding the draft User Story above, it looks good to me. Just some comments for error corrections:

'Scope: Any phone line (not limlited to 4G, 5G)'

limlited -> limited

'Starts when: The customer application server makes a request to the KYC service (API) with the age restricted value.'

the KYC service (API) -> the Age Verification service (API)

'Exceptions Several exceptions might occur during the KYC Match API operations:'

the KYC Match API operations -> the Age Verificaiton API operations

Thanks.
Toshi

assuranceLevel is now a enum (Low, Substancial, High) and not a score.

GillesInnov35 · 2024-04-10T13:48:23Z

Thanks a lot @ToshiWakayama-KDDI , errors have been corrected.
BR
Gilles

Corrections, updated Design and description

GillesInnov35 · 2024-10-09T14:47:09Z

@ToshiWakayama-KDDI, @HuubAppelboom , @KevScarr, @fernandopradocabrillo I've updated this design proposal. Let me know if it's ok according to your comments
Thanks
BR
Gilles

rartych · 2024-11-28T16:00:35Z

There is a typo in the file name: age-vefification.yaml

GillesInnov35 · 2024-11-28T16:15:56Z

thanks @rartych for your point

ToshiWakayama-KDDI · 2024-11-29T01:48:54Z

hi @GillesInnov35

@ToshiWakayama-KDDI , you're right 400 - OUT OF RANGE should be added with description Client specified an invalid range. Thanks Gilles

Oh, sorry, my mistake.
Status: 400
Code: OUT_OF_RANGE
Message: Client specified an invalid range

Could add the above, please? I still do not know how to propose modification of yaml as Fernando does.

Thanks,
Toshi

GillesInnov35 · 2024-11-29T08:07:47Z

hi @ToshiWakayama-KDDI, the bellow error example exists in the errors section of AgeVerification yaml file. From what I see that is what the next Commonalities version recommend, isn't it ?

       GENERIC_422_SERVICE_NOT_APPLICABLE:
          description: Service is not available for the provided identifier
          value:
            status: 422
            code: SERVICE_NOT_APPLICABLE
            message: The service is not available for the provided identifier.

for the second point which concerns Out Of Range, I've added the error example. Tell me if it's OK

        GENERIC_400_OUT_OF_RANGE:
          description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested
          value:
            status: 400
            code: OUT_OF_RANGE
            message: Client specified an invalid range.

As the yaml file name is not corect, perhaps we should create a new PR with the last file version in order to have a global approval ?

Thanks
BR
Gilles

ToshiWakayama-KDDI · 2024-11-29T11:15:07Z

Hi @GillesInnov35 ,

hi @ToshiWakayama-KDDI, the bellow error example exists in the errors section of AgeVerification yaml file. From what I see that is what the next Commonalities version recommend, isn't it ?
       GENERIC_422_SERVICE_NOT_APPLICABLE:
          description: Service is not available for the provided identifier
          value:
            status: 422
            code: SERVICE_NOT_APPLICABLE
            message: The service is not available for the provided identifier.

To the best of my knowledge, no, I don't think so. According to the latest updated API Design guidelines https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#61-standardized-use-of-camara-error-responses , my understanding is that "422 DEVICE_NOT_APPLICABLE The service is not available for the provided device. " is existing, instead of previous "422 NOT_SUPPORTED Service not supported for this phoneNumber".

So, my proposal was to add "422 DEVICE_NOT_APPLICABLE The service is not available for the provided device."

I hope I am correct.

Many thanks,
Toshi

ToshiWakayama-KDDI · 2024-11-29T11:20:50Z

Hi @GillesInnov35 ,

for the second point which concerns Out Of Range, I've added the error example. Tell me if it's OK

        GENERIC_400_OUT_OF_RANGE:
          description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested
          value:
            status: 400
            code: OUT_OF_RANGE
            message: Client specified an invalid range.

Thank you so much. It is OK with me.

Thanks,
Toshi

ToshiWakayama-KDDI · 2024-11-29T11:29:07Z

Hi @GillesInnov35 ,

As the yaml file name is not corect, perhaps we should create a new PR with the last file version in order to have a global approval ?

Thanks, again. I didn't notice that. Rafal's pointing by bold finally made me notice it. Yes, we should not to forget it.

Thanks,
Toshi

GillesInnov35 · 2024-11-29T13:05:25Z

@ToshiWakayama-KDDI , regarding the PR#316 (https://github.com/camaraproject/Commonalities/pull/316/files) I don't see any reference to DEVICE.

rartych · 2024-11-29T13:43:23Z

As the yaml file name is not corect, perhaps we should create a new PR with the last file version in order to have a global approval ?

Thanks, again. I didn't notice that. Rafal's pointing by bold finally made me notice it. Yes, we should not to forget it.

You can edit the filename within this PR

following Commonalities for errors handling

code/API_definitions/age-verification.yaml

Thanks Co-authored-by: Fernando Prado Cabrillo <[email protected]>

Co-authored-by: Fernando Prado Cabrillo <[email protected]>

code/API_definitions/age-verification.yaml

Co-authored-by: Fernando Prado Cabrillo <[email protected]>

fernandopradocabrillo · 2024-12-10T12:55:11Z

code/API_definitions/age-verification.yaml

+    If successful, a JSON object is returned containing the following data:
+    - `ageCheck`: Indicate 'true' when the age of the user is the same age or older than the age threshold (age >= age threshold), and 'false' if not (age < age threshold).  Otherwise, 'not_available'.
+    - `verifiedStatus`: true if the information provided was checked against another form of official identification, otherwise false.
+    - `identityMatchScore`: the overall match score of identity information provided in the request compared to what MNO holds.


what values can the match score have? the same as in kyc-match, 0-100?
@GillesInnov35 @ToshiWakayama-KDDI @HuubAppelboom

Hi @fernandopradocabrillo ,

I think 0-100, as specified below:

identityMatchScore:
type: "integer"
minimum: 0
maximum: 100
description: An aggregate match score of user's identity when available in the request body.

Thanks,
Toshi

GillesInnov35 · 2024-12-10T13:02:16Z

hi @fernandopradocabrillo, yes same as kyc-match. Huub has proposed algo to calculate the result PR #81
Gilles

code/API_definitions/age-verification.yaml

Thanks Fernando Co-authored-by: Fernando Prado Cabrillo <[email protected]>

ToshiWakayama-KDDI · 2024-12-16T06:27:02Z

code/API_definitions/age-verification.yaml

+    - `POST /ageverify`
+
+      Takes the network subscription identifier (e.g. the mobile phone number for a mobile network subscriber) and check the age of the user is older than the age's threshold in the request.
+      If information of the user's identity such as `givenName`, `familyName`, `address` match with information held by the MNO.


Suggestion to replace this sentence with the below for more clarification.

Additionally, as optional function, provides (1) if age check is done against another form of official identification or not (verifiedStatus) and (2) how close the information of user's identity such as such as givenName, familyName, address etc. is to information held by the MNO (identityMatchScore).

Thanks,
Toshi

ToshiWakayama-KDDI · 2024-12-16T06:30:24Z

code/API_definitions/age-verification.yaml

+    ## Inputs
+
+    The endpoint request body is a JSON object with the following parameters:
+    - `phoneNumber`: The network subscription identifier (i.e. the phone number of the subscriber). [Required only in case a 2-legged flow has been agreed between API Provider and API Consumer; otherwise, none]


Suggestion to replace this sentence with below based on Huub's comment #50 (comment) :

phoneNumber: The network subscription identifier (i.e. the phone number of the subscriber). [Required only in case a 2-legged flow has been agreed between API Provider and API Consumer; otherwise, do not include phoneNumber]

(change to 'otherwise, none)

Thanks,
Toshi

wdyt @ToshiWakayama-KDDI ? It sounds more restrictive

Suggested change

- `phoneNumber`: The network subscription identifier (i.e. the phone number of the subscriber). [Required only in case a 2-legged flow has been agreed between API Provider and API Consumer; otherwise, none]

- `phoneNumber`: The network subscription identifier (i.e. the phone number of the subscriber). [Required only in case a 2-legged flow has been agreed between API Provider and API Consumer following CAMARA directives; otherwise, phoneNumber must not be included]

ToshiWakayama-KDDI · 2024-12-16T06:41:32Z

code/API_definitions/age-verification.yaml

+    If successful, a JSON object is returned containing the following data:
+    - `ageCheck`: Indicate 'true' when the age of the user is the same age or older than the age threshold (age >= age threshold), and 'false' if not (age < age threshold).  Otherwise, 'not_available'.
+    - `verifiedStatus`: true if the information provided was checked against another form of official identification, otherwise false.
+    - `identityMatchScore`: the overall match score of identity information provided in the request compared to what MNO holds.


Suggestion to add notes to these two sentences for more clarificaiton as below:

verifiedStatus: true if the information provided was checked against another form of official identification, otherwise false.
Note: It is optional if an API provider wants to indicate this status.

identityMatchScore: the overall match score of identity information provided in the request compared to what MNO holds.
Note: It is optional for an API provider to return the match score. If an API provider decides not to return the match score, even though any of idDocument, name, givenName, familyName, middieNames, familyNameAtBirth, birthdate, email are included in the request body, no identityMatchScore parameter will not be returned.

I have commented similar suggestion already #50 (comment), but it has not been captured yet.

Thanks,
Toshi

Hi @ToshiWakayama-KDDI! Thanks for the proposal. From TEF we are thinking in something similar. We would like to complete the text stating that, additionally to what you include about not returning the identityScore, it can also be calculated using internal data from the MNO and not only from the input received. For example if the line is part of a multi-line contract so we cannot be sure if it is the owner of the line, if it has parental control activated it may indicate that it is a line used by a child, etc

Suggested change

- `identityMatchScore`: the overall match score of identity information provided in the request compared to what MNO holds.

- `identityMatchScore`: The overall score of identity information available in the Operator, information either provided in the request body comparing it to the one that the MNO holds or directly using internal MNO's information. It is optional for the Operator to return the Identity match score.

ToshiWakayama-KDDI · 2024-12-16T11:59:26Z

Hi @GillesInnov35 , @fernandopradocabrillo ,

Please advise me if the following 'Errors' part is described in the Commonalities API Design Guidelines. I cannot find it by myself...

## Errors
If the authentication token is not valid, a `401 UNAUTHENTICATED` error is returned
If the API call contain a formatting or other error, a `400 INVALID_ARGUMENT` error is returned.
If the network subscription cannot be identified from the provided parameters (e.g. the subscription identifier is not associated with any customer of the CSP), a `404 IDENTIFIER_NOT_FOUND` error is returned.
If the API consumer has a valid access token but is not authorised to obtain tenure information for the specified network subscription, then a `403 PERMISSION_DENIED` error is returned.
Other errors may be returned as specified below.

Many thanks,
Toshi

rartych · 2024-12-16T12:49:49Z

code/API_definitions/age-verification.yaml

+
+    If the network subscription cannot be identified from the provided parameters (e.g. the subscription identifier is not associated with any customer of the CSP), a `404 IDENTIFIER_NOT_FOUND` error is returned.
+
+    If the API consumer has a valid access token but is not authorised to obtain tenure information for the specified network subscription, then a `403 PERMISSION_DENIED` error is returned.


I guess here tenure is not related:

Suggested change

If the API consumer has a valid access token but is not authorised to obtain tenure information for the specified network subscription, then a `403 PERMISSION_DENIED` error is returned.

If the API consumer has a valid access token but is not authorised to obtain age verification information for the specified network subscription, then a `403 PERMISSION_DENIED` error is returned.

hi @rartych , thanks for your comment. You're right it concerns Age Verification and not Tenure. But

if the API consumer has a valid access token but is not authorised to verify the age of the user of the line

WDYT
Gilles

wdyt?

Suggested change

If the API consumer has a valid access token but is not authorised to obtain tenure information for the specified network subscription, then a `403 PERMISSION_DENIED` error is returned.

If the API consumer has a valid access token but is not authorised to request an age verification for the specified network subscription, then a `403 PERMISSION_DENIED` error is returned.

Initial contribution of Age_Verification.yaml

2c40283

ToshiWakayama-KDDI requested review from fernandopradocabrillo and GillesInnov35 as code owners February 2, 2024 10:40

ToshiWakayama-KDDI mentioned this pull request Feb 2, 2024

Creation of a Pull Request for Age Verification API #46

Closed

Update age-verification.yaml

ed7003f

Update the design proposal for Age Verification API specifications

GillesInnov35 previously approved these changes Feb 2, 2024

View reviewed changes

Update age-vefification.yaml

0335b85

GillesInnov35 dismissed their stale review via 0335b85 February 16, 2024 09:14

GillesInnov35 added 3 commits March 5, 2024 10:20

Update age-vefification.yaml

ea5d63a

Add firstName and FamilyName attributes to be compared with MNO information

Update age-vefification.yaml

da5d59c

Addition of MiddleNames

Update age-vefification.yaml

6673fe5

Update age-vefification.yaml

ae2c024

with Huub (KPN) proposition: assurance level

HuubAppelboom approved these changes Mar 27, 2024

View reviewed changes

Update age-vefification.yaml

d35564d

assuranceLevel is now a enum (Low, Substancial, High) and not a score.

GillesInnov35 mentioned this pull request May 22, 2024

Add Age Verification to KnowYourCustomer SP's Scope in README #81

Open

GillesInnov35 added 9 commits May 22, 2024 16:22

Update age-vefification.yaml

52f2ca6

Update age-vefification.yaml

754c2e0

Update age-vefification.yaml

82647d1

Update age-vefification.yaml

830e390

Update age-vefification.yaml

4bd8a34

Update age-vefification.yaml

c4863dd

Update age-vefification.yaml

007c6c0

Update age-vefification.yaml

abc4093

Update age-vefification.yaml

b4a2009

Corrections, updated Design and description

Update age-vefification.yaml

bb7e933

Update age-vefification.yaml

b382392

GillesInnov35 added 2 commits November 29, 2024 14:46

Update and rename age-vefification.yaml to age-verification.yaml

cb50467

Update age-verification.yaml

42b9298

following Commonalities for errors handling

fernandopradocabrillo reviewed Dec 5, 2024

View reviewed changes

code/API_definitions/age-verification.yaml Show resolved Hide resolved

fernandopradocabrillo reviewed Dec 5, 2024

View reviewed changes

code/API_definitions/age-verification.yaml Show resolved Hide resolved

GillesInnov35 and others added 2 commits December 5, 2024 14:25

Update code/API_definitions/age-verification.yaml

f9ed877

Thanks Co-authored-by: Fernando Prado Cabrillo <[email protected]>

Update code/API_definitions/age-verification.yaml

a9a9787

Co-authored-by: Fernando Prado Cabrillo <[email protected]>

fernandopradocabrillo reviewed Dec 10, 2024

View reviewed changes

code/API_definitions/age-verification.yaml Outdated Show resolved Hide resolved

fernandopradocabrillo reviewed Dec 10, 2024

View reviewed changes

code/API_definitions/age-verification.yaml Outdated Show resolved Hide resolved

GillesInnov35 and others added 2 commits December 10, 2024 12:19

Update code/API_definitions/age-verification.yaml

e60ddc3

Co-authored-by: Fernando Prado Cabrillo <[email protected]>

Update code/API_definitions/age-verification.yaml

a0dd209

Co-authored-by: Fernando Prado Cabrillo <[email protected]>

fernandopradocabrillo reviewed Dec 10, 2024

View reviewed changes

code/API_definitions/age-verification.yaml Outdated Show resolved Hide resolved

Update code/API_definitions/age-verification.yaml

22359e3

Thanks Fernando Co-authored-by: Fernando Prado Cabrillo <[email protected]>

ToshiWakayama-KDDI commented Dec 16, 2024

View reviewed changes

rartych reviewed Dec 16, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Initial contribution of Age_Verification.yaml #50

Initial contribution of Age_Verification.yaml #50

ToshiWakayama-KDDI commented Feb 2, 2024

GillesInnov35 commented Feb 2, 2024 •

edited

Loading

GillesInnov35 left a comment

GillesInnov35 commented Feb 5, 2024 •

edited

Loading

GillesInnov35 commented Mar 12, 2024

ToshiWakayama-KDDI commented Apr 1, 2024

GillesInnov35 commented Apr 10, 2024

GillesInnov35 commented Oct 9, 2024

rartych commented Nov 28, 2024

GillesInnov35 commented Nov 28, 2024

ToshiWakayama-KDDI commented Nov 29, 2024

GillesInnov35 commented Nov 29, 2024

ToshiWakayama-KDDI commented Nov 29, 2024

ToshiWakayama-KDDI commented Nov 29, 2024

ToshiWakayama-KDDI commented Nov 29, 2024

GillesInnov35 commented Nov 29, 2024

rartych commented Nov 29, 2024

fernandopradocabrillo Dec 10, 2024

ToshiWakayama-KDDI Dec 16, 2024

GillesInnov35 commented Dec 10, 2024

ToshiWakayama-KDDI Dec 16, 2024

ToshiWakayama-KDDI Dec 16, 2024

fernandopradocabrillo Dec 16, 2024

ToshiWakayama-KDDI Dec 16, 2024

fernandopradocabrillo Dec 16, 2024

ToshiWakayama-KDDI commented Dec 16, 2024

rartych Dec 16, 2024

GillesInnov35 Dec 16, 2024

fernandopradocabrillo Dec 16, 2024

	- `phoneNumber`: The network subscription identifier (i.e. the phone number of the subscriber). [Required only in case a 2-legged flow has been agreed between API Provider and API Consumer; otherwise, none]
	- `phoneNumber`: The network subscription identifier (i.e. the phone number of the subscriber). [Required only in case a 2-legged flow has been agreed between API Provider and API Consumer following CAMARA directives; otherwise, phoneNumber must not be included]

	- `identityMatchScore`: the overall match score of identity information provided in the request compared to what MNO holds.
	- `identityMatchScore`: The overall score of identity information available in the Operator, information either provided in the request body comparing it to the one that the MNO holds or directly using internal MNO's information. It is optional for the Operator to return the Identity match score.


		If the network subscription cannot be identified from the provided parameters (e.g. the subscription identifier is not associated with any customer of the CSP), a `404 IDENTIFIER_NOT_FOUND` error is returned.

		If the API consumer has a valid access token but is not authorised to obtain tenure information for the specified network subscription, then a `403 PERMISSION_DENIED` error is returned.

Initial contribution of Age_Verification.yaml #50

Are you sure you want to change the base?

Initial contribution of Age_Verification.yaml #50

Conversation

ToshiWakayama-KDDI commented Feb 2, 2024

What type of PR is this?

What this PR does / why we need it:

Which issue(s) this PR fixes:

Special notes for reviewers:

Changelog input

Additional documentation

GillesInnov35 commented Feb 2, 2024 • edited Loading

GillesInnov35 left a comment

Choose a reason for hiding this comment

GillesInnov35 commented Feb 5, 2024 • edited Loading

Proposition of User Story

GillesInnov35 commented Mar 12, 2024

ToshiWakayama-KDDI commented Apr 1, 2024

GillesInnov35 commented Apr 10, 2024

GillesInnov35 commented Oct 9, 2024

rartych commented Nov 28, 2024

GillesInnov35 commented Nov 28, 2024

ToshiWakayama-KDDI commented Nov 29, 2024

GillesInnov35 commented Nov 29, 2024

ToshiWakayama-KDDI commented Nov 29, 2024

ToshiWakayama-KDDI commented Nov 29, 2024

ToshiWakayama-KDDI commented Nov 29, 2024

GillesInnov35 commented Nov 29, 2024

rartych commented Nov 29, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

GillesInnov35 commented Dec 10, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ToshiWakayama-KDDI commented Dec 16, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

GillesInnov35 commented Feb 2, 2024 •

edited

Loading

GillesInnov35 commented Feb 5, 2024 •

edited

Loading