Telefonica Proposal #3

monamok · 2022-11-24T08:00:29Z

Telefónica Proposal based on the conversation here

bigludo7

Hello
We have an API close to this proposal in Orange. 2 comments:

Could we align the POST body with MC structure:
{ "mc_claims": { "device_msisdn": "+33640049871" } }
(and I guess device_hashed_msisdn attribute for the second resource)
It will not change the philosophy API and not add complexity but allow people familiar with this pattern to have it.
We have in Orange another resource to retrieve directly the msisdn from the access token (GET operation). This is relevant for some UC - you do not have this requirement on your side ?

Thanks.

DT-DawidWroblewski · 2022-12-07T08:34:09Z

@bigludo7 for a resource call this is something that is common for vMSISDN, so we can align on a POST call to a resource that contains a body you mentioned:

{ "mc_claims": { "device_msisdn": "+33640049871" } }

for GET operation to extract MSISDN out of Access Token - this is one of the solutions available on a market. However, this call should take place during the device authentication process initiated with a request coming to /authorize endpoint. If MSISDN extraction is fine, then "code" is returned and we're following OIDC flow.

The reason why it should take place in auth process is thanks to this approach, we're hiding various means of extracting MSISDN out of...whatever (access token, specific token, HE). For the developer, this is handy, because there is a common flow (OpenID Connect) and MNOs hides complexity.

monamok · 2022-12-07T09:35:11Z

Hello,

About the first comment:

1. Could we align the POST body with MC structure:
   `{   "mc_claims": { "device_msisdn": "+33640049871"   } }`
   (and I guess device_hashed_msisdn attribute for the second resource)
   It will not change the philosophy API and not add complexity but allow people familiar with this pattern to have it.

The reason why we prefer to separate them in two endpoints is to have control over the scopes and be able to manage the permissions separately. In order to have an intial version 0.X we can have them a single endpoint.
But I find it a bit confusing naming it "mc_claims" as it's a new API and not MC. I agree that there might be people familiar with the concept but not necesarily. My suggestion is to use a more user-fiendly name.

About the second point:

2. We have in Orange another resource to retrieve directly the msisdn from the access token (GET operation). This is relevant for some UC - you do not have this requirement on your side ?

This is related to issue #101 that is still under discussion. TEF is strongly against returning PI and sharing that information with 3d-parties. But if already have this UC (I think DT also mentioned that they do as well) we can include it as a separate GET endpoint getting the number from the access token.

Access token can be result of OIDC flow but we insist to have endpoints separeted from the authentication flow.

I will update the yaml and upload it so you can comment on it.

monamok · 2022-12-07T14:47:19Z

I changed the yaml file so there is an single endpoint to verify the number using oneOf structure where it can receive plain phone number or hashed phone number.
Another option is to reuse the same parameter for clear number as well as hashed number and then have a flag to indicate if it's hashed or not. In that case the request body looks like this:
{
"phone_number": "xxx"
"hashed": "false"
}
As you can see in my previous comment, I think mentioning mc_claims in this API is not a good idea because we're trying to agree on having a resource specific API and there is no claims here that we should refer to.

I didn't include the share endpoint (getting the number from the token and returning it) as it's not in our roadmap but if you consider it necesarry you can include it to this version as it's a 0.x version and for the v1.0 we can decide later once issue #101 get resolved.

Please check out the new version.

TIM Italy and TIM Brasil reviews points and contributions proposal: Suggest to converge on a YAML from previous proposal A+B+C: A) Proposal by TEF (Telefonica Proposal #3) B) Proposal by DT (Initial content for Number Verify #2) C) Proposal initially by TIM Brasil (IP and Port header input parameters) Review points include in new YAML file version regarding path /authorize: IP and Port as optional input header parameters oAuth2 already mapped in DT (Initial content for Number Verify #2) Error code handling according to CAMARA others API (e.g., the Traffic Influence API)

monamok · 2022-12-14T09:50:25Z

Dear all, could you please review my previous comment and the last changes that were made. Today is the deadline and from Telefónica we hope we can meet it together.

monamok · 2022-12-15T12:33:16Z

Dear all, as it was agreed in this morning meeting I updated the proposal.

@bigludo7 I added a new endpoint for the share operation as you requested. It's a GET operation and returns the phone number. As I already mentioned, sharing PI is not in Telefónica roadmap but having in mind that you have this use case and the commonality issue for the PI is still open and under discussion, we can have it in this version and we'll adjust it later for v1.0, depending on that issue's result.
Please check it out if it covers your requirements. Thank you.

bigludo7

Thanks @monamok - This is good for my perspective.

monamok · 2022-12-15T17:40:15Z

Thanks @monamok - This is good for my perspective.

Thank you @bigludo7.

@DT-DawidWroblewski could you please review it and if you agree please go ahead and merge it.

monamok · 2022-12-19T09:53:06Z

Dear @DT-DawidWroblewski, would it be possible to get your comments/approval-merge today?
Thanks.

DT-DawidWroblewski · 2022-12-19T12:33:59Z

@monamok working on it...

DT-DawidWroblewski · 2022-12-19T12:36:04Z

code/API_definitions/number_verification.yaml

+  title: Number Verification
+  description: |-
+    Service Enabling Network Function API to verify that the provided **phone number** is the one used in the device. It verifies that the user is using a device with the same *phone number* as it is declared.
+    It also make it possible for a Service provider to verify the number itself by returning the phone number retrieved from the authenticated user's access token.


are we assuming here that MSISDN is somehow returned in Access Token? should it be JWT? where MSISDN is then returned?

The API doesn't return the Token. In order to use the API, a previous step of three legged authentication is needed and the phone number that is associated to the access token will be used to compare with the input data.

Hi @monamok !

this particular sentence makes confision:

...verify the number itself by returning the phone number retrieved from the authenticated user's access token.

I read it like:

as a sw developer i can retrieve phone number from authenticated user's access token, so that I can verify phone number.

maybe sth like this is better:

as a sw developer I can retrieve information about phone number of the device, so that I can confirm that end user possess the device.

what do yo think?

I rephrased it. Please take a look :)

code/API_definitions/number_verification.yaml

DT-DawidWroblewski · 2022-12-20T08:38:40Z

code/API_definitions/number_verification.yaml


    # Resources and Operations overview
    This API currently provides two endpoints where both require a **3-legged token** and authentication via **mobile network** (excluding for example by SMS/OTP or user/password as an authentication method):
-    - The first one checks if the user phone number matches the MSISDN associated with the mobile device. It can receive either a hashed phone number or a clear phone number as input and it compares the received input with the authenticated user's MSISDN retrieved from the access token in order to respond **true/false**.
+    - The first one checks if the user mobile phone number matches the phone number associated with the mobile device. It can receive either a hashed phone number or a clear phone number as input and it compares the received input with the authenticated user's phone number retrieved from the access token in order to respond **true/false**.


phone number retrieved from the access token --> phone number associated to the access token

DT-DawidWroblewski · 2022-12-20T08:39:34Z

code/API_definitions/number_verification.yaml

@@ -96,7 +96,7 @@ paths:
      description: |-
        Returns the phone number so the API clients can verify the number themselves:
         - It will be done for the user that has authenticated via mobile network and so their `sub` is in the access token
-         - It returns the authenticated user's `MSISDN` retrieved from the access token
+         - It returns the authenticated user's `device phone number` retrieved from the access token


device phone number retrieved from the access token --> device phone number associated to the access token

DT-DawidWroblewski

thx!

DT-DawidWroblewski · 2022-12-20T08:50:08Z

merging under condition that Number Verify based Mobile Connect Verified MSISDN yaml is also available inside PR, although I'm not able to merge it by myself and waiting for @bigludo7 approval.

initial version

3167c0c

monamok mentioned this pull request Nov 24, 2022

Initial content for Number Verify #2

Merged

monamok added 2 commits November 24, 2022 09:31

file relocation

6df52b2

minor fix

cd0beb0

monamok requested a review from DT-DawidWroblewski as a code owner November 29, 2022 08:09

error status updated

c0b8099

monamok requested a review from bigludo7 as a code owner December 5, 2022 16:20

basepath edited

5444cd9

bigludo7 reviewed Dec 6, 2022

View reviewed changes

two endpoints converted into a single one

fa537ba

monamok requested a review from bigludo7 December 7, 2022 17:13

paulocesardiaslima mentioned this pull request Dec 8, 2022

TIM Italy and TIM Brasil contributions proposal paulocesardiaslima/NumberVerification#1

Open

paulocesardiaslima mentioned this pull request Dec 8, 2022

TIM Italy and TIM Brasil contributions proposal DT-DawidWroblewski/NumberVerification#2

Closed

get device-phone-number included by Orange petition

ada82ae

bigludo7 previously approved these changes Dec 15, 2022

View reviewed changes

DT-DawidWroblewski reviewed Dec 19, 2022

View reviewed changes

reviwer comments appiled

ce51b33

monamok dismissed bigludo7’s stale review via ce51b33 December 19, 2022 16:34

monamok requested a review from DT-DawidWroblewski December 19, 2022 16:49

MSISDN removed

c128846

Description improved

59a8cf7

DT-DawidWroblewski reviewed Dec 20, 2022

View reviewed changes

descriptions edited

1f73c8c

DT-DawidWroblewski approved these changes Dec 20, 2022

View reviewed changes

monamok requested a review from bigludo7 December 20, 2022 09:45

DT-DawidWroblewski merged commit f4f99b4 into camaraproject:main Dec 20, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Telefonica Proposal #3

Telefonica Proposal #3

monamok commented Nov 24, 2022 •

edited

Loading

bigludo7 left a comment

DT-DawidWroblewski commented Dec 7, 2022

monamok commented Dec 7, 2022

monamok commented Dec 7, 2022 •

edited

Loading

monamok commented Dec 14, 2022

monamok commented Dec 15, 2022

bigludo7 left a comment

monamok commented Dec 15, 2022

monamok commented Dec 19, 2022

DT-DawidWroblewski commented Dec 19, 2022

DT-DawidWroblewski Dec 19, 2022

monamok Dec 19, 2022 •

edited

Loading

DT-DawidWroblewski Dec 20, 2022

monamok Dec 20, 2022

DT-DawidWroblewski Dec 20, 2022

monamok Dec 20, 2022

DT-DawidWroblewski Dec 20, 2022

monamok Dec 20, 2022

DT-DawidWroblewski left a comment

DT-DawidWroblewski commented Dec 20, 2022

Telefonica Proposal #3

Telefonica Proposal #3

Conversation

monamok commented Nov 24, 2022 • edited Loading

bigludo7 left a comment

Choose a reason for hiding this comment

DT-DawidWroblewski commented Dec 7, 2022

monamok commented Dec 7, 2022

monamok commented Dec 7, 2022 • edited Loading

monamok commented Dec 14, 2022

monamok commented Dec 15, 2022

bigludo7 left a comment

Choose a reason for hiding this comment

monamok commented Dec 15, 2022

monamok commented Dec 19, 2022

DT-DawidWroblewski commented Dec 19, 2022

DT-DawidWroblewski Dec 19, 2022

Choose a reason for hiding this comment

monamok Dec 19, 2022 • edited Loading

Choose a reason for hiding this comment

DT-DawidWroblewski Dec 20, 2022

Choose a reason for hiding this comment

monamok Dec 20, 2022

Choose a reason for hiding this comment

DT-DawidWroblewski Dec 20, 2022

Choose a reason for hiding this comment

monamok Dec 20, 2022

Choose a reason for hiding this comment

DT-DawidWroblewski Dec 20, 2022

Choose a reason for hiding this comment

monamok Dec 20, 2022

Choose a reason for hiding this comment

DT-DawidWroblewski left a comment

Choose a reason for hiding this comment

DT-DawidWroblewski commented Dec 20, 2022

monamok commented Nov 24, 2022 •

edited

Loading

monamok commented Dec 7, 2022 •

edited

Loading

monamok Dec 19, 2022 •

edited

Loading