Sim swap alignement with commonalities 0.5 #180

bigludo7 · 2024-12-23T15:51:53Z

What type of PR is this?

Add one of the following kinds:

enhancement/feature

What this PR does / why we need it:

Alignement of sim_swap.yaml, sim_swap-retrieveDate.feature and sim_swap-check.feature with commonalities 0.5 rules.
See detail in release note

Which issue(s) this PR fixes:

Fixes #161

Special notes for reviewers:

This is breaking change.

Changelog input

release-note
sim_swap.yaml:
- Change error structure definition to normalize error & status
- Update error code to introduce 429
- Remove 5xx errors
- Change in 422 code
- Add 3-legged token examples
- Improve documentation part

sim_swap-retrieveDate.feature:
- update test case scenario for 422
- Add optional test case for 401 AUTHENTICATION_REQUIRED

sim_swap-check.feature:
- update test case scenario for 422
- Add optional test case for 401 AUTHENTICATION_REQUIRED

Additional documentation

This section can be blank.

docs

Align sim-swap.yaml with commonalities 0.5

Update sim-swap-check.feature with commonalities 0.5

github-actions · 2024-12-23T15:53:00Z

🦙 MegaLinter status: ✅ SUCCESS

Descriptor	Linter	Files	Errors	Elapsed time
✅ ACTION	actionlint	2	0	0.02s
✅ OPENAPI	spectral	2	0	3.21s
✅ REPOSITORY	git_diff	yes	no	0.01s
✅ REPOSITORY	secretlint	yes	no	0.8s
✅ YAML	yamllint	2	0	0.63s

See detailed report in MegaLinter reports

MegaLinter is graciously provided by

gregory1g · 2025-01-06T07:05:03Z

code/API_definitions/sim-swap.yaml


-    This specification defines the `phoneNumber` field as optional in API requests, specifically in cases where the API is accessed using a 3-legged access token, and the phone number can be uniquely identified by the token. This approach simplifies API usage for API consumers by relying on the information associated with the access token used to invoke the API.
+    This API requires the API consumer to identify a device as the subject of the API as follows:


For SimSwap a subject of the API is a phone number, not a device. The "device-centric" language is misleading.

Agreed. I will apply.

gregory1g · 2025-01-06T07:07:57Z

code/API_definitions/sim-swap.yaml

@@ -326,7 +354,7 @@ components:
              value:
                status: 403
                code: INVALID_TOKEN_CONTEXT
-                message: phoneNumber is not consistent with access token
+                message: "{{field}} is not consistent with access token."


What "field" other than the phoneNumber can it be?

I followed what is described in the CAMARA_common.yaml

I tend to think that this error should not be triggered in our case because if you pass a 3-legs access token identifying the phone number and a phone number in the body the 422 UNNECESSARY_IDENTIFIER must be triggered.

Yes, I understood that you follow commonalities. But should we really copy paste its wording 1:1 when we know better. A developer will read this text and can be confused.

And you are right - with the change this PR introduces, this check will not be executed: 422 to be returned without checking if both match or not. Let's remove it.

Yes make sense for me. to remove ut but I would like to hear from @fernandopradocabrillo before to proceed.

Fernando do you think we can remove 403 INVALID_TOKEN_CONTEXT ? as we do not see when this error will be triggered.

code/API_definitions/sim-swap.yaml

gregory1g · 2025-01-06T07:16:54Z

code/API_definitions/sim-swap.yaml

-    ### Restrictions for tokens without an associated authenticated phone number:
-
-    - For scenarios which do not have a phone number associated to the token during the authentication flow, e.g. 2-legged access tokens, the `phoneNumber` field MUST be provided in the API request. This ensures that the phone number is explicit and valid for each API call made with these tokens.
+    - If the subject can be identified from the access token and the optional `phoneNumber` identifier 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 device is identified by these two methods, as the server is unable to make this comparison.


I agree with the logic of the change, but this is a not-backward compatible change. Currently one may send 3-legged token and the phoneNumber (even if this is not recommended), with this change this will cause a error.

Agree we have a breaking change here but we have to follow commonalities. Indeed, If you use 3-legs access token with a phoneNumber in the body you'll have a 422 UNNECESSARY_IDENTIFIER while previously it worked.

As a reminder we introduced this to avoid 'hidden' number verification

The purpose of my comment was to highlight this, and make sure that the consequences of new commonalities are not overlooked.

code/API_definitions/sim-swap.yaml

removed 403 INVALID_TOKEN_CONTEXT

bigludo7 · 2025-01-09T07:18:36Z

@fernandopradocabrillo @gregory1g Following camaraproject/Commonalities#369 discussion I think it's fair to remove 403 INVALID_TOKEN_CONTEXT example in the yaml.

May I ask you to review this new proposal soon as we have to prepare the RC candidate before Jan17th. We can still modify after but we have to achieve the milestone.

code/API_definitions/sim-swap.yaml

gregory1g · 2025-01-09T07:54:07Z

code/API_definitions/sim-swap.yaml

+                code: SERVICE_NOT_APPLICABLE
+                message: The service is not available for the provided identifier.
+            GENERIC_422_MISSING_IDENTIFIER:
+              description: An identifier is not included in the request and the device or phone number identification cannot be derived from the 3-legged access token


If this error for 3-legged token invocation only it should not say "not included in the request", because this is not allowed for the 3-legged invocation.

If the error is generic it should not explicitly mention 3-legged token (because it could be a 2-legged token). Like "An identifier is not included in the request and the device or phone number identification cannot be derived from access token".

Since "MISSING_IDENTIFIER" error message uses a generic "access token" style, I suggest to use generic style here as well.

This is generic.
I followed commonalities guideline see here.

I suggest @gregory1g that you post your comment in commonalities as it makes sense.

created an issue there: camaraproject/Commonalities#370

according to Eric, commonality's "description" is not a error message to be send, it is a description for the reader of the table in the document. While example of the message is in the "Message example" column. An this is just an example, different API can use different text

Proposal discussed with @fernandopradocabrillo : We propose to add precision about this error in the Test Case

I've reworked the yaml & TC to add all clarification - please review.

code/API_definitions/sim-swap.yaml

Fixe line 47 (device -> phone number)

gregory1g · 2025-01-13T06:38:56Z

code/API_definitions/sim-swap.yaml


-    This specification defines the `phoneNumber` field as optional in API requests, specifically in cases where the API is accessed using a 3-legged access token, and the phone number can be uniquely identified by the token. This approach simplifies API usage for API consumers by relying on the information associated with the access token used to invoke the API.
+    This API requires the API consumer to identify a device (via its phone number) as the subject of the API as follows:


"to identify a device" this is not the case, the API does not need to identify a device at all. MSIDN is subscription ID, not a device ID. And the API implementation does not need to identify the device either.
Considering that API description targets application developers, using "device" is rather misleading. It makes a reader think that this API target exact phone unit like geo location APIs do.

Fixed accordingly

using "device" is rather misleading

One of the advantages of the CAMARA approach is that application developers can use APIs such as SIM Swap without knowing (or learning) the MSISDN at all. All they need to do is identify a device using the subscription, and capture its IP address. I think ruthlessly expunging "device" from our documentation and baking in "phone number" mean this possibility gets overlooked.

It would be nice if we could come up with some "developer friendly" formulation of words which also captures this possibility, as there will be use cases out there that would benefit from this approach if only developers were aware of it.

@eric-murray To be sure to follow you - as in the body we can only use the phone number - you want to highlight the point that via the 3-legged token we can value in the login-hint other identifier like ip?

@bigludo7
No, it was just a general comment - I'm not expecting the documentation to be updated because of it.

Using a 2-legged access token and explicit identifier will very much be the exception for CAMARA APIs, and yet it is the definition of the explicit identifier that dominates the API description. For the normal case of a 3-legged access token, the token itself is not classified as a "device" token or "phone number" token. The very same token could be used for both a "phone number" API (such as SIM Swap) and a "device" API (such as Device Status).

If 3-legged tokens were the only option, we would not have to go through these mental gymnastics of documenting an API as either a "device" API or a "phone number" API. It is to be hoped that we can come to some agreement on a common formulation for the documentation that reveals this capability to developers without confusing them.

SimSwap can potentially processes an IP as an input

For a 3-legged access token, the "processing" will already have been done. The SIM Swap API itself does not need to do anything different.

I take the point that IP as a device identifier is not persistent. An API consumer cannot capture the IP address and expect to use that the following week to check the SIM Swap status of the associated subscription. But if they immediately obtain an access token for that IP, then they can check the SIM Swap status for the subscription used by that device, all without even knowing what the MSISDN is.

It is this possibility I think gets overlooked - using "phone number" APIs without knowing the phone number.

my point was that SimSwap does not target a device, it targets an MSISDN.

SIM Swap targets the mobile subscription. The API consumer does not need to know the MSISDN to use the API.

@gregory1g @eric-murray Does this discussion prevent me to merge this PR? with the M3 at the horizon we need to move forward for the yaml & work on the other asset. I can try to copy paste your comment in the discussion?

@bigludo7
No changes needed, just proceed with the M3 as planned.

Probably the full range of use cases that can be supported by an API can be better advertised through developer portals rather than the YAML documentation anyway. But we can maybe think later on how we can better document what a developer needs to know or needs access to in order to use an API.

gregory1g · 2025-01-13T06:45:38Z

code/API_definitions/sim-swap.yaml


-    This specification defines the `phoneNumber` field as optional in API requests, specifically in cases where the API is accessed using a 3-legged access token, and the phone number can be uniquely identified by the token. This approach simplifies API usage for API consumers by relying on the information associated with the access token used to invoke the API.
+    This API requires the API consumer to identify a device (via its phone number) as the subject of the API as follows:
+    - When the API is invoked using a two-legged access token, the subject will be identified from the optional `phoneNumber` identifier, which therefore MUST be provided.


"the subject will be identified from the optional phoneNumber identifier" says that the phoneNumner is not the subject of the API, but just a helper to identify the device. This is confusing. The original terminology was simpler to understand. Especially when one also reads documentation for other API which really target a device.

Fixed accordingly

gregory1g · 2025-01-13T06:47:17Z

code/API_definitions/sim-swap.yaml


-    - When using a 3-legged access token, the phone number associated with the access token must be considered as the phone number for the API request. This means that the `phoneNumber` field is not required in the request, and if included it must identify the same phone number, therefore **it is recommended NOT to include it in these scenarios** to simplify the API usage and avoid additional validations.
+    - If the subject cannot be identified from the access token and the optional `phoneNumber` identifier is not included in the request, then the server will return an error with the `422 MISSING_IDENTIFIER` error code.


Suggestion: use "phoneNumer" instead of "subject" - it is still a single word and it is simpler to understand.

Fixed accordingly

@gregory1g

Clarify lines 49-51 in documentation following @gregory1g comments

code/API_definitions/sim-swap.yaml

fernandopradocabrillo

LGTM

Co-authored-by: Fernando Prado Cabrillo <fernando.pradocabrillo@telefonica.com>

bigludo7 · 2025-01-15T17:14:34Z

Thanks @fernandopradocabrillo
I've applied your suggestion so I need again your approval.

@gregory1g : Any blocker on your side for approval?

gregory1g · 2025-01-16T12:55:04Z

lgtm

bigludo7 added 3 commits December 23, 2024 16:42

Align sim-swap.yaml with commonalities 0.5

8749bf3

Align sim-swap.yaml with commonalities 0.5

Update sim-swap-check.feature with commonalities 0.5

43a76ba

Update sim-swap-check.feature with commonalities 0.5

Update sim-swap-retrieveDate.feature with Commonalities 0.5

178f304

bigludo7 requested a review from fernandopradocabrillo as a code owner December 23, 2024 15:51

Fix MegaLinter issues for the examples

8d3ccaa

gregory1g suggested changes Jan 6, 2025

View reviewed changes

bigludo7 added 2 commits January 6, 2025 18:34

Add precision that phoneNumber is used to identify the device

0b7a44e

Removed 403 INVALID_TOKEN_CONTEXT

393e05f

removed 403 INVALID_TOKEN_CONTEXT

gregory1g reviewed Jan 9, 2025

View reviewed changes

bigludo7 added 4 commits January 9, 2025 10:11

Update sim-swap.yaml

ce7b6ca

Fixe line 47 (device -> phone number)

Align 429 message examples with the code

57cbe1f

Improve GENERIC_422_MISSING_IDENTIFIER description

dfa475e

reworked MISSING_IDENTIFIER TC

25752f6

gregory1g reviewed Jan 13, 2025

View reviewed changes

Clarify lines 49-51 in documentation

d536b53

Clarify lines 49-51 in documentation following @gregory1g comments

bigludo7 requested a review from gregory1g January 15, 2025 08:28

fernandopradocabrillo reviewed Jan 15, 2025

View reviewed changes

code/API_definitions/sim-swap.yaml Outdated Show resolved Hide resolved

fernandopradocabrillo reviewed Jan 15, 2025

View reviewed changes

code/API_definitions/sim-swap.yaml Outdated Show resolved Hide resolved

fernandopradocabrillo previously approved these changes Jan 15, 2025

View reviewed changes

Update code/API_definitions/sim-swap.yaml

e524399

Co-authored-by: Fernando Prado Cabrillo <fernando.pradocabrillo@telefonica.com>

bigludo7 dismissed fernandopradocabrillo’s stale review via e524399 January 15, 2025 17:13

Update code/API_definitions/sim-swap.yaml

1774ca9

Co-authored-by: Fernando Prado Cabrillo <fernando.pradocabrillo@telefonica.com>

fernandopradocabrillo self-requested a review January 16, 2025 08:47

fernandopradocabrillo approved these changes Jan 16, 2025

View reviewed changes

gregory1g approved these changes Jan 16, 2025

View reviewed changes

bigludo7 merged commit d4eb8b8 into main Jan 16, 2025
2 checks passed

bigludo7 deleted the sim-swap-align-comm0.5 branch January 16, 2025 15:10


		This specification defines the `phoneNumber` field as optional in API requests, specifically in cases where the API is accessed using a 3-legged access token, and the phone number can be uniquely identified by the token. This approach simplifies API usage for API consumers by relying on the information associated with the access token used to invoke the API.
		This API requires the API consumer to identify a device as the subject of the API as follows:


		- When using a 3-legged access token, the phone number associated with the access token must be considered as the phone number for the API request. This means that the `phoneNumber` field is not required in the request, and if included it must identify the same phone number, therefore it is recommended NOT to include it in these scenarios to simplify the API usage and avoid additional validations.
		- If the subject cannot be identified from the access token and the optional `phoneNumber` identifier is not included in the request, then the server will return an error with the `422 MISSING_IDENTIFIER` error code.

Sim swap alignement with commonalities 0.5 #180

Sim swap alignement with commonalities 0.5 #180

Conversation

bigludo7 commented Dec 23, 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

github-actions bot commented Dec 23, 2024 • edited Loading

🦙 MegaLinter status: ✅ SUCCESS

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

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

bigludo7 commented Jan 9, 2025

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

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

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

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

fernandopradocabrillo left a comment

Choose a reason for hiding this comment

bigludo7 commented Jan 15, 2025

gregory1g commented Jan 16, 2025

github-actions bot commented Dec 23, 2024 •

edited

Loading