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 4 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
226 changes: 141 additions & 85 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 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.

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

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Agreed. I will apply.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

done

- 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,23 +299,49 @@ 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
- INVALID_TOKEN_CONTEXT
examples:
GENERIC_403_PERMISSION_DENIED:
description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security
Expand All @@ -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."
Copy link
Collaborator

Choose a reason for hiding this comment

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

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

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

Copy link
Collaborator

Choose a reason for hiding this comment

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

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.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

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.

Generic404:
description: Not found
headers:
Expand All @@ -335,7 +363,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 +389,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 +466,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