Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Sim swap alignement with commonalities 0.5 #180

Merged
merged 13 commits into from
Jan 16, 2025
Merged

Sim swap alignement with commonalities 0.5 #180

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
8749bf3
Align sim-swap.yaml with commonalities 0.5
bigludo7 Dec 23, 2024
43a76ba
Update sim-swap-check.feature with commonalities 0.5
bigludo7 Dec 23, 2024
178f304
Update sim-swap-retrieveDate.feature with Commonalities 0.5
bigludo7 Dec 23, 2024
8d3ccaa
Fix MegaLinter issues for the examples
bigludo7 Dec 23, 2024
0b7a44e
Add precision that phoneNumber is used to identify the device
bigludo7 Jan 6, 2025
393e05f
Removed 403 INVALID_TOKEN_CONTEXT
bigludo7 Jan 9, 2025
ce7b6ca
Update sim-swap.yaml
bigludo7 Jan 9, 2025
57cbe1f
Align 429 message examples with the code
bigludo7 Jan 10, 2025
dfa475e
Improve GENERIC_422_MISSING_IDENTIFIER description
bigludo7 Jan 10, 2025
25752f6
reworked MISSING_IDENTIFIER TC
bigludo7 Jan 10, 2025
d536b53
Clarify lines 49-51 in documentation
bigludo7 Jan 15, 2025
e524399
Update code/API_definitions/sim-swap.yaml
bigludo7 Jan 15, 2025
1774ca9
Update code/API_definitions/sim-swap.yaml
bigludo7 Jan 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
229 changes: 139 additions & 90 deletions code/API_definitions/sim-swap.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,33 +40,23 @@ info:

The "Camara Security and Interoperability Profile" provides details on how a client requests an access token. Please refer to Identify and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the Profile.

Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation.
Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the API Provider, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation.

It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control.

# Identifying a phone number from the access token
# Identifying the device from the access token

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:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"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.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed accordingly

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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.

- 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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"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.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed accordingly

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

## Handling of phone number information:
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.

### Optional `phoneNumber` field for 3-legged tokens:
## Error handling:

- 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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed accordingly


### Validation mechanism:

- The server will extract the phone number identification from the access token, if available.
- If the API request additionally includes a `phoneNumber` field when using a 3-legged access token, the API will validate that the phone number provided matches the one associated with the access token.
- If there is a mismatch, the API will respond with a 403 - INVALID_TOKEN_CONTEXT error, indicating that the phone number information in the request does not match the token.

### Error handling for unidentifiable phone number:

- If the `phoneNumber` field is not included in the request and the phone number information cannot be derived from the 3-legged access token, the server will return a 422 `UNIDENTIFIABLE_PHONE_NUMBER` error.

### 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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


# Further info and support

Expand All @@ -78,7 +68,7 @@ info:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
version: wip
x-camara-commonalities: 0.4.0
x-camara-commonalities: 0.5.0
externalDocs:
description: Product documentation at Camara
url: https://github.com/camaraproject/SimSwap
Expand Down Expand Up @@ -109,6 +99,12 @@ paths:
application/json:
schema:
$ref: "#/components/schemas/CreateSimSwapDate"
examples:
RETRIEVE_3LEGS:
$ref: "#/components/examples/RETRIEVE_3LEGS"
RETRIEVE_2LEGS:
$ref: "#/components/examples/RETRIEVE_2LEGS"

required: true
responses:
"200":
Expand Down Expand Up @@ -137,12 +133,8 @@ paths:
$ref: "#/components/responses/Generic404"
"422":
$ref: "#/components/responses/Generic422"
"500":
$ref: "#/components/responses/Generic500"
"503":
$ref: "#/components/responses/Generic503"
"504":
$ref: "#/components/responses/Generic504"
"429":
$ref: "#/components/responses/Generic429"
/check:
post:
security:
Expand All @@ -163,6 +155,11 @@ paths:
application/json:
schema:
$ref: "#/components/schemas/CreateCheckSimSwap"
examples:
CHECK_3LEGS:
$ref: "#/components/examples/CHECK_3LEGS"
CHECK_2LEGS:
$ref: "#/components/examples/CHECK_2LEGS"
required: true
responses:
"200":
Expand All @@ -184,12 +181,8 @@ paths:
$ref: "#/components/responses/Generic404"
"422":
$ref: "#/components/responses/Generic422"
"500":
$ref: "#/components/responses/Generic500"
"503":
$ref: "#/components/responses/Generic503"
"504":
$ref: "#/components/responses/Generic504"
"429":
$ref: "#/components/responses/Generic429"
components:
securitySchemes:
openId:
Expand Down Expand Up @@ -281,7 +274,16 @@ components:
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
allOf:
- $ref: "#/components/schemas/ErrorInfo"
- type: object
properties:
status:
enum:
- 400
code:
enum:
- INVALID_ARGUMENT
examples:
GENERIC_400_INVALID_ARGUMENT:
description: Invalid Argument. Generic Syntax Exception
Expand All @@ -297,36 +299,55 @@ components:
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
allOf:
- $ref: "#/components/schemas/ErrorInfo"
- type: object
properties:
status:
enum:
- 401
code:
enum:
- UNAUTHENTICATED
- AUTHENTICATION_REQUIRED
examples:
GENERIC_401_UNAUTHENTICATED:
description: Request cannot be authenticated
value:
status: 401
code: UNAUTHENTICATED
message: Request not authenticated due to missing, invalid, or expired credentials.
GENERIC_401_AUTHENTICATION_REQUIRED:
description: New authentication is needed, authentication is no longer valid
value:
status: 401
code: AUTHENTICATION_REQUIRED
message: New authentication is required.
Generic403:
description: Forbidden
headers:
x-correlator:
$ref: '#/components/headers/x-correlator'
$ref: "#/components/headers/x-correlator"
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
allOf:
- $ref: "#/components/schemas/ErrorInfo"
- type: object
properties:
status:
enum:
- 403
code:
enum:
- PERMISSION_DENIED
examples:
GENERIC_403_PERMISSION_DENIED:
description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security
value:
status: 403
code: PERMISSION_DENIED
message: Client does not have sufficient permissions to perform this action.
GENERIC_403_INVALID_TOKEN_CONTEXT:
description: Reflect some inconsistency between information in some field of the API and the related OAuth2 Token
value:
status: 403
code: INVALID_TOKEN_CONTEXT
message: phoneNumber is not consistent with access token
Generic404:
description: Not found
headers:
Expand All @@ -335,7 +356,17 @@ components:
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
allOf:
- $ref: "#/components/schemas/ErrorInfo"
- type: object
properties:
status:
enum:
- 404
code:
enum:
- NOT_FOUND
- IDENTIFIER_NOT_FOUND
examples:
GENERIC_404_NOT_FOUND:
description: Resource is not found
Expand All @@ -351,68 +382,69 @@ components:
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
allOf:
- $ref: "#/components/schemas/ErrorInfo"
- type: object
properties:
status:
enum:
- 422
code:
enum:
- SERVICE_NOT_APPLICABLE
- MISSING_IDENTIFIER
- UNNECESSARY_IDENTIFIER
examples:
GENERIC_422_NOT_SUPPORTED:
description: Not Supported
GENERIC_422_SERVICE_NOT_APPLICABLE:
description: Service not applicable for the provided identifier
value:
status: 422
code: NOT_SUPPORTED
message: Service not supported for this phoneNumber
UNIDENTIFIABLE_PHONE_NUMBER:
description: The phone number is not included in the request and the phone number information cannot be derived from the 3-legged access token
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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is generic.
I followed commonalities guideline see here.

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

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

created an issue there: camaraproject/Commonalities#370

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

value:
status: 422
code: UNIDENTIFIABLE_PHONE_NUMBER
message: The phone number cannot be identified
Generic500:
description: Internal Server Error
headers:
x-correlator:
$ref: "#/components/headers/x-correlator"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
GENERIC_500_INTERNAL:
description: Problem in Server side. Regular Server Exception
code: MISSING_IDENTIFIER
message: The device cannot be identified.
GENERIC_422_UNNECESSARY_IDENTIFIER:
description: An explicit identifier is provided when a device or phone number has already been identified from the access token
value:
status: 500
code: INTERNAL
message: Unknown server error. Typically a server bug.
Generic503:
description: Service Unavailable
status: 422
code: UNNECESSARY_IDENTIFIER
message: The device is already identified by the access token.
Generic429:
description: Too Many Requests
headers:
x-correlator:
$ref: "#/components/headers/x-correlator"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
allOf:
- $ref: "#/components/schemas/ErrorInfo"
- type: object
properties:
status:
enum:
- 429
code:
enum:
- QUOTA_EXCEEDED
- TOO_MANY_REQUESTS
examples:
GENERIC_503_UNAVAILABLE:
description: Service is not available. Temporary situation usually related to maintenance process in the server side
GENERIC_429_QUOTA_EXCEEDED:
description: Request is rejected due to exceeding a business quota limit
value:
status: 503
code: UNAVAILABLE
message: Service Unavailable.
Generic504:
description: Gateway Timeout
headers:
x-correlator:
$ref: "#/components/headers/x-correlator"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
GENERIC_504_TIMEOUT:
description: API Server Timeout
status: 429
code: QUOTA_EXCEEDED
message: Either out of resource quota or reaching rate limiting.
GENERIC_429_TOO_MANY_REQUESTS:
description: API Server request limit is overpassed
value:
status: 504
code: TIMEOUT
message: Request timeout exceeded.
status: 429
code: TOO_MANY_REQUESTS
message: Either out of resource quota or reaching rate limiting.
examples:
RETRIEVE_DATE:
summary: Lastest SIM swap date is send back
Expand All @@ -427,3 +459,20 @@ components:
value:
latestSimChange: null
monitoredPeriod: 120
CHECK_2LEGS:
summary: Check request without 3-legged access tokens
value:
phoneNumber: "+346661113334"
maxAge: 120
CHECK_3LEGS:
summary: Check request with 3-legged access tokens
value:
maxAge: 120
RETRIEVE_2LEGS:
summary: Retrieve request without 3-legged access tokens
value:
phoneNumber: "+346661113334"
RETRIEVE_3LEGS:
summary: Retrieve request with 3-legged access tokens
value:
{}
Loading
Loading