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

Jump to bottom

New specific 403 token error and guidelines alignment #19

Merged
merged 8 commits into from
Feb 21, 2023
Merged

New specific 403 token error and guidelines alignment #19

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
e9a2ed6
new specific 403 token error added
monamok Feb 1, 2023
215c723
reformat
monamok Feb 1, 2023
21ca9cf
error status changed into integer to be aligned with the guidelines
monamok Feb 2, 2023
8311920
status range changed
monamok Feb 3, 2023
8b18c18
fix
monamok Feb 8, 2023
44400db
reviewer comments applied
monamok Feb 15, 2023
05e4681
specific error edited
monamok Feb 21, 2023
54639c9
IP replaced by mobile network
monamok Feb 21, 2023
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
19 changes: 10 additions & 9 deletions code/API_definitions/CAMARA/NUMBER_VERIFICATION_API.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,12 +23,12 @@ Before starting to use the API, the developer needs to know about the below spec

Two endpoints are defined in Number Verification API:

- POST /number-verification/v0/verify : Verifies if the specified phone number (clear or hashed format) matches the one that the user is currently using.
- POST /number-verification/v0/verify : Verifies if the specified phone number (plain text or hashed format) matches the one that the user is currently using.
- GET /number-verification/v0/device-phone-number : Returns the phone number associated with the access token so API clients can verify the number themselves.

**Authentication**

Security access keys such as OAuth 2.0 3-legged Access Tokens used by Client applications to invoke this API with dedicated scope. Client must authenticate via IP to use this service.
Security access keys such as OAuth 2.0 3-legged Access Tokens used by Client applications to invoke this API with dedicated scope. Client **must use network based authentication methods** to use this service.
Copy link
Collaborator

Choose a reason for hiding this comment

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

this looks good


Sample API invocations are presented in Section 4.6.

Expand All @@ -50,7 +50,7 @@ Following table defines API endpoints of exposed REST based for Number Verificat

| **Endpoint** | **Operation** | **Description** |
| -------- | --------- | ----------- |
| POST /number-verification/v0/verify | **Request to verify a number** | Create request in order to verify if the specified phone number (clear or hashed format) matches the one that the user is currently using |
| POST /number-verification/v0/verify | **Request to verify a number** | Create request in order to verify if the specified phone number (plain text or hashed format) matches the one that the user is currently using |
Copy link
Collaborator

Choose a reason for hiding this comment

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

looks good

| GET /number-verification/v0/device-phone-number | **Request to get the device phone number** | Create a request to get the phone number associated with the access token so the API clients can verify the number themselves |


Expand All @@ -61,7 +61,7 @@ Following table defines API endpoints of exposed REST based for Number Verificat
| -------------------------- |
| **HTTP Request**<br> POST /number-verification/v0/verify<br>**Query Parameters**<br> No query parameters are defined.<br>**Path Parameters**<br> No path parameters are defined.<br>**Request Body Parameters**<br> **One of:** <br> **phone_number**: A phone number belonging to the user. 'E164 with +' format.<br> **hashed_phone_number**: Hashed phone number. SHA-256 (in hexadecimal representation) of the mobile phone number in 'E164 with +' format.

<br>**Response**<br> **200: OK**<br> Response body: <br>**device_phone_number_verified** : Boolean <br> **400:** **INVALID_ARGUMENT**<br> **401:** **UNAUTHENTICATED** <br> **403:** **PERMISSION_DENIED** <br> **403:** **NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_IP** <br> **500:** **INTERNAL**<br> **503:** **UNAVAILABLE**<br> **504:** **TIMEOUT**<br>
<br>**Response**<br> **200: OK**<br> Response body: <br>**device_phone_number_verified** : Boolean <br> **400:** **INVALID_ARGUMENT** <br> **401:** **UNAUTHENTICATED** <br> **403:** **PERMISSION_DENIED** <br> **403:** **NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK** <br> **403:** **NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT** <br> **500:** **INTERNAL**<br> **503:** **UNAVAILABLE**<br> **504:** **TIMEOUT**<br>
<br>

<br>
Expand All @@ -70,7 +70,7 @@ Following table defines API endpoints of exposed REST based for Number Verificat
| -------------------------- |
| **HTTP Request**<br> GET /number-verification/v0/device-phone-number<br>**Query Parameters**<br> No query parameters are defined.<br>**Path Parameters**<br> No path parameters are defined.<br>**Request Body Parameters**<br> No body

<br>**Response**<br> **200: OK**<br> Response body: <br>**device_phone_number** : The device phone number associated to the access token. 'E164 with +' format. <br> **400:** **INVALID_ARGUMENT**<br> **401:** **UNAUTHENTICATED** <br> **403:** **PERMISSION_DENIED** <br> **403:** **NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_IP** <br> **500:** **INTERNAL**<br> **503:** **UNAVAILABLE**<br> **504:** **TIMEOUT**<br>
<br>**Response**<br> **200: OK**<br> Response body: <br>**device_phone_number** : The device phone number associated to the access token. 'E164 with +' format. <br> **400:** **INVALID_ARGUMENT**<br> **401:** **UNAUTHENTICATED** <br> **403:** **PERMISSION_DENIED** <br> **403:** **NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK** <br> **403:** **NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT** <br> **500:** **INTERNAL** <br> **503:** **UNAVAILABLE**<br> **504:** **TIMEOUT**<br>
<br>

<br>
Expand All @@ -87,10 +87,11 @@ Following table provides an overview of common error names, codes, and messages
|1 |400 | INVALID_ARGUMENT | "Client specified an invalid argument, request body or query param" |
|2 |401 | UNAUTHENTICATED | "Request not authenticated due to missing, invalid, or expired credentials" |
|3 |403 | PERMISSION_DENIED | "Client does not have sufficient permissions to perform this action" |
|4 |403 | NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_IP | "Client must authenticate via IP to use this service" |
|5 |500 | INTERNAL | "Server error" |
|6 |503 | UNAVAILABLE | "Service unavailable" |
|7 |504 | TIMEOUT | "Request timeout exceeded. Try later." |
|4 |403 | NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK | "Client must authenticate via the mobile network to use this service" |
|5 |403 | NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT | "Phone number cannot be deducted from access token context" |
|6 |500 | INTERNAL | "Server error" |
|7 |503 | UNAVAILABLE | "Service unavailable" |
|8 |504 | TIMEOUT | "Request timeout exceeded. Try later." |

<br>

Expand Down
51 changes: 27 additions & 24 deletions code/API_definitions/CAMARA/number_verification.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,9 @@ info:

# 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 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 associated to 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 or a plain text phone number as input and it compares the received input with the authenticated user's phone number associated to the access token in order to respond **true/false**.
Copy link
Collaborator

Choose a reason for hiding this comment

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

Looks good

- The next one retrieves the phone number associated to the user's token and returns it so the verification can be made by the service provider.
version: 0.1.0
version: 0.2.0
monamok marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Collaborator

Choose a reason for hiding this comment

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

let's sync versions with MC yaml

termsOfService: http://example.com/terms/
contact:
name: API Support
Expand All @@ -34,20 +34,20 @@ servers:
description: Base path for the number verification API
tags:
- name: Phone number verify
description: API operation to verify a phone number received as input. It can be received either in clear or hashed format.
description: API operation to verify a phone number received as input. It can be received either in plain text or hashed format.
Copy link
Collaborator

Choose a reason for hiding this comment

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

looks good

- name: Phone number share
description: API operation to return the phone number associated to the access token.
paths:
/verify:
post:
tags:
- Phone number verify
summary: Verifies if the received hashed phone number matches the phone number associated with the access token
summary: Verifies if the received hashed/plain text phone number matches the phone number associated with the 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.

looks good

description: |-
Verifies if the specified phone number (clear or hashed format) matches the one that the user is currently using.
Verifies if the specified phone number (plain text or hashed format) matches the one that the user is currently using.
Copy link
Collaborator

Choose a reason for hiding this comment

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

looks good

- The number verification will be done for the user that has authenticated via mobile network and so their `sub` is in the access token
- It returns true/false depending on if the hashed phone number received as input matches the authenticated user's `device phone number` associated to the access token
operationId: hashedPhoneNumberVerify
operationId: phoneNumberVerify
Copy link
Collaborator

Choose a reason for hiding this comment

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

looks good

parameters:
- in: header
name: x-correlator
Expand Down Expand Up @@ -78,7 +78,7 @@ paths:
'401':
$ref: '#/components/responses/Unauthenticated'
'403':
$ref: '#/components/responses/NotAuthenticatedByIpPermissionDenied'
$ref: '#/components/responses/PhoneNumberVerificationPermissionDenied'
monamok marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Collaborator

Choose a reason for hiding this comment

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

looks good

'500':
$ref: '#/components/responses/Internal'
'503':
Expand Down Expand Up @@ -122,7 +122,7 @@ paths:
'401':
$ref: '#/components/responses/Unauthenticated'
'403':
$ref: '#/components/responses/NotAuthenticatedByIpPermissionDenied'
$ref: '#/components/responses/PhoneNumberVerificationPermissionDenied'
monamok marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Collaborator

Choose a reason for hiding this comment

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

looks good

'500':
$ref: '#/components/responses/Internal'
'503':
Expand Down Expand Up @@ -188,13 +188,14 @@ components:
- message
properties:
status:
type: string
pattern: '^[1-5][0-9][0-9]$'
type: integer
minimum: 400
maximum: 599
DT-DawidWroblewski marked this conversation as resolved.
Show resolved Hide resolved
description: HTTP response status code
message:
type: string
description: A human readable description of what the event represent
NotAuthenticatedByIpPermissionDenied:
PhoneNumberVerificationPermissionDenied:
monamok marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Collaborator

Choose a reason for hiding this comment

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

looks good

allOf:
- type: object
required:
Expand All @@ -204,7 +205,8 @@ components:
type: string
enum:
- PERMISSION_DENIED
- NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_IP
- NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK
- NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT
Copy link
Collaborator

Choose a reason for hiding this comment

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

looks good

default: PERMISSION_DENIED
description: Client does not have sufficient permissions to perform this action.
- $ref: '#/components/schemas/ModelError'
Expand Down Expand Up @@ -234,7 +236,7 @@ components:
examples:
response:
value:
status: "400"
status: 400
monamok marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Collaborator

Choose a reason for hiding this comment

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

looks good

code: INVALID_ARGUMENT
message: Client specified an invalid argument, request body or query param
Unauthenticated:
Expand Down Expand Up @@ -262,14 +264,15 @@ components:
examples:
response:
value:
status: "401"
status: 401
monamok marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Collaborator

Choose a reason for hiding this comment

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

looks good

code: UNAUTHENTICATED
message: Request not authenticated due to missing, invalid, or expired credentials
NotAuthenticatedByIpPermissionDenied:
PhoneNumberVerificationPermissionDenied:
monamok marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Collaborator

Choose a reason for hiding this comment

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

looks good

description: |-
Client does not have sufficient permission.
In addition to regular scenario of `PERMISSION_DENIED`, another scenario may exist:
- Client authentication was not via mobile network. In order to check the authentication method, AMR parameter value in the 3-legged user's access token can be used and make sure that the authentication was not either by SMS+OTP nor username/password (`{"code": "NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_IP","message": "Client must authenticate via IP to use this service"}`)
In addition to regular scenario of `PERMISSION_DENIED`, other scenarios may exist:
monamok marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Collaborator

Choose a reason for hiding this comment

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

looks good

- Client authentication was not via mobile network. In order to check the authentication method, AMR parameter value in the 3-legged user's access token can be used and make sure that the authentication was not either by SMS+OTP nor username/password (`{"code": "NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK","message": "Client must authenticate via the mobile network to use this service"}`)
- Phone number cannot be deducted from access token context.(`{"code": "NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT","message": "Phone number cannot be deducted from access token context"}`)
Copy link
Collaborator

Choose a reason for hiding this comment

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

I'm not so convinced about the approach that we share info about the context. Can we simplify the response and use just 401 Unauthorized, invalid_token?

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 think 401 is unauthenticated and in this case the user has authenticated but it's kind of forbidden because they autheticated using a wrong method for example, and so the token lacks informations that is needed to go on with the process. We're just saying that the token is not what it's supposed to be and it can be helpful for the developer. I prefer 403 to 401. Specific errors are specially to give some more information and telling why they're not allowed to do something and they're more developer-friendly in general.

Copy link
Collaborator

Choose a reason for hiding this comment

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

looks good

headers:
x-correlator:
description: Correlation id for the different services
Expand All @@ -278,13 +281,13 @@ components:
content:
application/json:
schema:
$ref: '#/components/schemas/NotAuthenticatedByIpPermissionDenied'
$ref: '#/components/schemas/PhoneNumberVerificationPermissionDenied'
monamok marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Collaborator

Choose a reason for hiding this comment

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

looks good

examples:
response:
value:
status: "403"
code: NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_IP
message: Client must authenticate via IP to use this service
status: 403
monamok marked this conversation as resolved.
Show resolved Hide resolved
code: NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK
message: Client must authenticate via the mobile network to use this service
Internal:
description: Server error
headers:
Expand All @@ -310,7 +313,7 @@ components:
examples:
response:
value:
status: "500"
status: 500
monamok marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Collaborator

Choose a reason for hiding this comment

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

looks good

code: INTERNAL
message: Server error
Unavailable:
Expand Down Expand Up @@ -338,7 +341,7 @@ components:
examples:
response:
value:
status: "503"
status: 503
monamok marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Collaborator

Choose a reason for hiding this comment

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

looks good

code: UNAVAILABLE
message: Service unavailable
Timeout:
Expand Down Expand Up @@ -366,7 +369,7 @@ components:
examples:
response:
value:
status: "504"
status: 504
monamok marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Collaborator

Choose a reason for hiding this comment

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

looks good

code: TIMEOUT
message: Request timeout exceeded. Try later.
externalDocs:
Expand Down