diff --git a/CHANGELOG.md b/CHANGELOG.md index 6b0b804..9033cfc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,50 +1,86 @@ -# Changelog - -## v0.4.0-wip [Work in Progress] - -## Please note: - -- This is *work-in-progress* version, it should be considered as a draft -- There are bug fixes to be expected and incompatible changes in upcoming versions -- The release is suitable for implementors, but it is not recommended to use the API with customers in productive environments -- Version numbers before v0.4.0-wip were used during the development of this version but not released - -### Added - -- Merge pull request #58 from fernandopradocabrillo/update-documentation-and-remove-deprecated-files -- include documentation inside yaml file, remove deprecated files and fix image link -- Merge pull request #57 from fernandopradocabrillo/update-tef-codeowners -- update codeowners from Telefónica -- Merge pull request #56 from camaraproject/bigludo7-patch-1 -- Merge pull request #58 from fernandopradocabrillo/update-documentation-and-remove-deprecated-files -- include documentation inside yaml file, remove deprecated files and fix image link -- Merge pull request #57 from fernandopradocabrillo/update-tef-codeowners -- update codeowners from Telefónica -- Merge pull request #56 from camaraproject/bigludo7-patch-1 -- Update number_verification.yaml -- Merge pull request #53 from DT-DawidWroblewski/main -- update to yaml -- Merge branch 'main' of https://github.com/DT-DawidWroblewski/NumberVerification -- adding fixes to PR -- Merge pull request #52 from jlurien/chore/replace-polymorphism-requestBody -- Replace polymorphism in requestBody of POST /verify -- Update documentation/API_documentation/README.MD -- Merge pull request #50 from monamok/chore/update_documentation -- cleaning repo -- Relevant definition section added -- Merge pull request #43 from monamok/chore/phone_number_description_alignment -- error code copy/pase typo removed -- updating uml url -- phoneNumber descriptions aligned to the other APIs - -### Changed - -* N/A - -### Fixed - -* N/A - -### Removed - -* N/A \ No newline at end of file +# Changelog Number Verification API + + +## Table of contents + +- **[r1.1](#r11)** +- [v0.3.1](#v031) + + +**Please be aware that the project will have frequent updates to the main branch. There are no compatibility guarantees associated with code in any branch, including main, until it has been released. For example, changes may be reverted before a release is published. For the best results, use the latest published release.** + + + +# r1.1 - rc + +## Release Notes + +This release contains the definition and documentation of +* Number Verification API 1.0.0-rc.1 + + + +The API definition(s) are based on +* Commonalities v0.4.0 +* Identity and Consent Management v0.2.0 + + +## Number Verification v1.0.0-rc.1 + + +**number-verification 1.0.0-rc.1** is the first release-candidate version for the v1.0.0 of the number-verification API. +This version contains significant changes compared to v0.3.1, and it is not backward compatible. + +- API definition **with inline documentation**: + - OpenAPI [YAML spec file](https://github.com/camaraproject/NumberVerification/blob/r1.1/code/API_definitions/number_verification.yaml) + - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/blob/r1.1/code/API_definitions/number_verification.yaml&nocors) + - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/blob/r1.1/code/API_definitions/number_verification.yaml) + + +### Added + +* User Story in documentation/API_documentation directory by @bigludo7 [PR118](https://github.com/camaraproject/NumberVerification/pull/118) +* Test Definition in Test_Definitions directory [To be done] + +### Changed + +* Aligned with CAMARA design guidelines & Identity Consent management +* Make the '+' mandatory for the phone number by @fernandopradocabrillo [PR90](https://github.com/camaraproject/NumberVerification/pull/90) +* Cosmetic change following megalinter integration by @bigludo7 [PR103](https://github.com/camaraproject/NumberVerification/pull/103) +* Update Authorization and authentication part accordingly to ICM by @fernandopradocabrillo [PR88](https://github.com/camaraproject/NumberVerification/issues/88) +* Adding a pattern for PhoneNumber in /verify by @maxl2287 [PR68](https://github.com/camaraproject/NumberVerification/issues/76) +* Clarify use of 'user' and 'subscriber' wording by @AxelNennker [PR102](https://github.com/camaraproject/NumberVerification/pull/102) + +### Fixed + +* Replaced OAuth2 auth code flow by OIDC auth code flow by @AxelNennker [PR109](https://github.com/camaraproject/NumberVerification/pull/109) + +### Removed + +* n/a + +## New Contributors + +- @AxelNennker made their first contribution in clarifying use of 'user' and 'subscriber' wording by @AxelNennker [PR102](https://github.com/camaraproject/NumberVerification/pull/102) +- @rartych made their first contribution in GitHub workflows [#108](https://github.com/camaraproject/NumberVerification/pull/108) +- @fernandopradocabrillo made their first contribution by updating Authorization and authentication part accordingly to ICM [PR88](https://github.com/camaraproject/NumberVerification/issues/88) +- @maxl2287 made their first contribution by adding a pattern for PhoneNumber in /verify [PR68](https://github.com/camaraproject/NumberVerification/issues/76) +- @bigludo7 made their first contribution by making change following megalinter integration [PR103](https://github.com/camaraproject/NumberVerification/pull/103) + +**Full Changelog**: https://github.com/camaraproject/NumberVerification/compare/v0.3.1...r1.1 + +## v0.3.1 + +Initital release of Camara Number Verification API + +## What's Changed +* Telefonica Proposal by @monamok in https://github.com/camaraproject/NumberVerification/pull/3 +* Adding API documentation by @monamok in https://github.com/camaraproject/NumberVerification/pull/6 +* Initial content for Number Verify by @DT-DawidWroblewski in https://github.com/camaraproject/NumberVerification/pull/2 +* New specific 403 token error and guidelines alignment by @monamok in https://github.com/camaraproject/NumberVerification/pull/19 +* adding puml by @DT-DawidWroblewski in https://github.com/camaraproject/NumberVerification/pull/24 +* guidelines alignment errors and camel case by @monamok in https://github.com/camaraproject/NumberVerification/pull/30 +* Change 'sub' cardinality + add attribute description by @bigludo7 in https://github.com/camaraproject/NumberVerification/pull/32 +* Embed documentation in API Spec by @monamok in https://github.com/camaraproject/NumberVerification/pull/38 + +**Full Changelog**: https://github.com/camaraproject/NumberVerification/commits/v0.3.1 \ No newline at end of file diff --git a/README.MD b/README.MD new file mode 100644 index 0000000..153ef91 --- /dev/null +++ b/README.MD @@ -0,0 +1,53 @@ + + + + + + + +# NumberVerification + +Repository to describe, develop, document and test the NumberVerification API family + +## Scope + +* Service APIs for “NumberVerification” (see APIBacklog.md) +* It provides the customer with the ability to: + * verify the phone number associated with the SIM used in the device connected to the mobile data network. +* Describe, develop, document and test the APIs (with 1-2 Telcos) +* Started: October 2022 +* Location: virtually + +## Meetings + +* Current schedule, registration, & meeting links are available on the confluence page: [Meetings information](https://wiki.camaraproject.org/display/CAM/NumberVerification) + + + +## Status and released versions + +* Note: Please be aware that the project will have frequent updates to the main branch. There are no compatibility guarantees associated with code in any branch, including main, until a new release is created. For example, changes may be reverted before a release is created. **For best results, use the latest available release**. +* **The latest pre-release of CAMARA Number Verification API is 1.0.0-rc.1 This is the release candidate of the first stable version of the API**. It is suitable for implementors. +* The Release Tag is [r1.1](https://github.com/camaraproject/NumberVerification/releases/tag/r1.1). + - API definition **with inline documentation**: + - OpenAPI [YAML spec file](https://github.com/camaraproject/NumberVerification/blob/r1.1/code/API_definitions/number_verification.yaml) + - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/blob/r1.1/code/API_definitions/number_verification.yaml&nocors) + - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/blob/r1.1/code/API_definitions/number_verification.yaml) + + +* The previous version 0.3.1 is available within the [release-0.3.1 branch](https://github.com/camaraproject/NumberVerification/tree/release-0.3.1): + - API definition **with inline documentation**: + - OpenAPI [YAML spec file](https://github.com/camaraproject/NumberVerification/blob/release-0.3.1/code/API_definitions/CAMARA/number_verification.yaml) + - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/release-0.3.1/code/API_definitions/CAMARA/number_verification.yaml&nocors) + - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/release-0.3.1/code/API_definitions/CAMARA/number_verification.yaml) + + +## Contributorship and mailing list + +* To subscribe / unsubscribe to the mailing list of this Sub Project and thus be / resign as Contributor please visit . +* A message to all Contributors of this Sub Project can be sent using . + + +## Relevant Information + +Since April 4th 2024 WG meeting minutes are placed in [Number Verification Wiki Confluence site](https://wiki.camaraproject.org/display/CAM/Number+Verification) \ No newline at end of file diff --git a/code/API_definitions/number_verification.yaml b/code/API_definitions/number_verification.yaml index 61d25e6..ac8571f 100644 --- a/code/API_definitions/number_verification.yaml +++ b/code/API_definitions/number_verification.yaml @@ -1,336 +1,335 @@ -openapi: 3.0.3 -info: - title: Number Verification - description: | - Service Enabling Network Function API to verify that the provided **mobile phone number** is the one used in the device. It verifies that the user is using a device with the same *mobile phone number* as it is declared. - It also makes it possible for a Service provider to verify the number itself by returning the phone number associated to the authenticated user's access token. - - In this API **phone number** term refers to the mobile phone number. - - # Introduction - - Number Verification API performs real-time checks to verify the phone number of the mobile device being used to access a service provider (SP) service, where the mobile device is accessing the *service provider* over a mobile network (WiFi connections are out of this API scope) either by getting the comparison result or receiving the phone number of the device that it is used, so they can verify it themselves. - - It uses direct mobile network connections to verify possession of a phone number in the background without requiring user interaction. There are neither OTPs (One-time passwords) received by SMS nor authenticator app downloads, so it is much simpler. It can be used at sign up, login, or transaction time to validate that a user's SIM (Subscriber Identity Module) is both actively connected to the mobile network and not spoofed or cloned. - - - # Relevant Definitions and Concepts - - - **Network-Based Authentication**: Authentication mechanism based on the identification of the endpoint of a network connection. Network operators know to which subscriber a network resource is assigned at a given moment, for example the mobile phone number associated to a specific mobile network connection. - - # API Functionality - - This enables a Service Provider (SP) to verify the phone number of the mobile device being used to access their service where the mobile device is accessing the *service provider* over a mobile network (WiFi connections are out of this API scope). This can happen either by getting the comparison result or receiving the phone number of the device that is used, so they can verify it themselves. - - # 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 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**. - - 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. - - # Sequence Diagram - Number Verification API uses the **standard [OIDC Authorization Code Flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth)**. The following diagram will help to clarify the end-to-end process, including previous steps prior to this API call. - - ![UML Sequence Diagram](https://raw.githubusercontent.com/camaraproject/NumberVerification/main/documentation/API_documentation/assets/uml_v0.3.jpg) - - **Additional details:** - - - **(1):** Authentication must be automatic without any user interactions. Authentication methods such as SMS OTP or user/password are incompatible, as the goal is to validate the mobile phone number that is accessing the App. So it is required to be authentication via mobile network and without the user being involved. the use of parameter prompt=none, as described in **[OIDC Connect](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest)**, ensures no user interaction. - - - **(2):** The way in which the phone_number is retrieved depends on the implementation. For example, access token may be a self contained encrypted JWT, so API can decrypt and identify phone_number. Some other implementations might request the phone_number associated to the token from Authserver. - - # Authorization and authentication - - CAMARA guidelines defines a set of authorization flows which can grant API clients access to the API functionality, as outlined in the document [CAMARA-API-access-and-user-consent.md](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md). 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. - - 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. - - In the case of the Number Verification API scenario and according to the API definition, 3-legged access tokens must be used by API clients to invoke this API with dedicated scope. The API client must authenticate on behalf of a specific user to use this service. This must be done via mobile network authentication. - - # Further info and support - [GSMA Mobile Connect Verified MSISDN specification](https://www.gsma.com/identity/wp-content/uploads/2022/12/IDY.54-Mobile-Connect-Verified-MSISDN-Definition-and-Technical-Requirements-1.0.pdf) was used as source of input for this API. For more about Mobile Connect, please see [Mobile Connect website](https://mobileconnect.io/). - version: wip - termsOfService: http://example.com/terms/ - contact: - name: API Support - url: http://www.example.com/support - email: support@example.com - license: - name: Apache 2.0 - url: https://www.apache.org/licenses/LICENSE-2.0.html -servers: - - url: '{apiRoot}/number-verification/v0' - variables: - apiRoot: - default: http://localhost:9091 - description: API root -tags: - - name: Phone number verify - description: API operation to verify a phone number received as input. It can be received either in plain text or hashed format. - - 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/plain text phone number matches the phone number associated with the access token - description: | - Verifies if the specified phone number (either in plain text or hashed format) matches the one that the user is currently using. Only one of the plain or hashed formats must be provided. - - The number verification will be done for the user that has authenticated via mobile network - - 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: phoneNumberVerify - parameters: - - in: header - name: X-Correlator - required: false - description: Correlation id for the different services - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/NumberVerificationRequestBody' - required: true - responses: - '200': - description: OK - headers: - X-Correlator: - description: Correlation id for the different services - schema: - type: string - content: - application/json: - schema: - $ref: '#/components/schemas/NumberVerificationMatchResponse' - '400': - $ref: '#/components/responses/Generic400' - '401': - $ref: '#/components/responses/Generic401' - '403': - $ref: '#/components/responses/PhoneNumberVerificationPermissionDenied403' - '500': - $ref: '#/components/responses/Generic500' - '503': - $ref: '#/components/responses/Generic503' - '504': - $ref: '#/components/responses/Generic504' - security: - - openId: - - number-verification:verify - /device-phone-number: - get: - tags: - - Phone number share - summary: Returns the phone number associated with the access token - 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 - - It returns the authenticated user's `device phone number` associated to the access token - operationId: phoneNumberShare - parameters: - - in: header - name: X-Correlator - required: false - description: Correlation id for the different services - schema: - type: string - responses: - '200': - description: OK - headers: - X-Correlator: - description: Correlation id for the different services - schema: - type: string - content: - application/json: - schema: - $ref: '#/components/schemas/NumberVerificationShareResponse' - '400': - $ref: '#/components/responses/Generic400' - '401': - $ref: '#/components/responses/Generic401' - '403': - $ref: '#/components/responses/PhoneNumberVerificationPermissionDenied403' - '500': - $ref: '#/components/responses/Generic500' - '503': - $ref: '#/components/responses/Generic503' - '504': - $ref: '#/components/responses/Generic504' - security: - - openId: - - number-verification:device-phone-number:read -components: - securitySchemes: - openId: - type: openIdConnect - openIdConnectUrl: https://example.com/.well-known/openid-configuration - schemas: - NumberVerificationRequestBody: - type: object - description: Payload to verify the phone number. - minProperties: 1 - maxProperties: 1 - properties: - phoneNumber: - type: string - pattern: '^\+[1-9][0-9]{4,14}$' - example: '+123456789' - description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. - hashedPhoneNumber: - description: Hashed phone number. SHA-256 (in hexadecimal representation) of the mobile phone number in **E.164 format (starting with country code)**. Prefixed with '+'. - type: string - example: 32f67ab4e4312618b09cd23ed8ce41b13e095fe52b73b2e8da8ef49830e50dba - NumberVerificationMatchResponse: - type: object - description: Number verification result - required: - - devicePhoneNumberVerified - properties: - devicePhoneNumberVerified: - $ref: '#/components/schemas/DevicePhoneNumberVerified' - NumberVerificationShareResponse: - type: object - description: Number verification share result - required: - - devicePhoneNumber - properties: - devicePhoneNumber: - $ref: '#/components/schemas/DevicePhoneNumber' - DevicePhoneNumber: - type: string - pattern: '^\+[1-9][0-9]{4,14}$' - example: '+123456789' - description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. - DevicePhoneNumberVerified: - description: Number verification. True, if it matches - type: boolean - ErrorInfo: - type: object - required: - - status - - code - - message - properties: - status: - type: integer - description: HTTP response status code - code: - type: string - description: Code given to this error - message: - type: string - description: Detailed error description - responses: - Generic400: - description: Problem with the client request - headers: - X-Correlator: - description: Correlation id for the different services - schema: - type: string - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorInfo' - example: - status: 400 - code: INVALID_ARGUMENT - message: Client specified an invalid argument, request body or query param - Generic401: - description: Authentication problem with the client request - headers: - X-Correlator: - description: Correlation id for the different services - schema: - type: string - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorInfo' - example: - status: 401 - code: UNAUTHENTICATED - message: Request not authenticated due to missing, invalid, or expired credentials - PhoneNumberVerificationPermissionDenied403: - description: | - Client does not have sufficient permission. - In addition to regular scenario of `PERMISSION_DENIED`, other scenarios 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_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"}`) - headers: - X-Correlator: - description: Correlation id for the different services - schema: - type: string - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorInfo' - examples: - PermissionDenied: - value: - status: 403 - code: PERMISSION_DENIED - message: Client does not have sufficient permissions to perform this action - UserNotAuthenticatedByMobileNetwork: - value: - status: 403 - code: NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK - message: Client must authenticate via the mobile network to use this service - InvalidTokenContext: - value: - status: 403 - code: NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT - message: Phone number cannot be deducted from access token context - Generic500: - description: Server error - headers: - X-Correlator: - description: Correlation id for the different services - schema: - type: string - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorInfo' - example: - status: 500 - code: INTERNAL - message: Server error - Generic503: - description: Service unavailable. Typically the server is down. - headers: - X-Correlator: - description: Correlation id for the different services - schema: - type: string - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorInfo' - example: - status: 503 - code: UNAVAILABLE - message: Service unavailable - Generic504: - description: Request time exceeded. If it happens repeatedly, consider reducing the request complexity - headers: - X-Correlator: - description: Correlation id for the different services - schema: - type: string - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorInfo' - example: - status: 504 - code: TIMEOUT - message: Request timeout exceeded. Try later. -externalDocs: - description: Project documentation at CAMARA - url: https://github.com/camaraproject/NumberVerification +openapi: 3.0.3 +info: + title: Number Verification + description: | + Service Enabling Network Function API to verify that the provided **mobile phone number** is the one used in the device. It verifies that the user is using a device with the same *mobile phone number* as it is declared. + It also makes it possible for a Service provider to verify the number itself by returning the phone number associated to the authenticated user's access token. + + In this API **phone number** term refers to the mobile phone number. + + # Introduction + + Number Verification API performs real-time checks to verify the phone number of the mobile device being used to access a service provider (SP) service, where the mobile device is accessing the *service provider* over a mobile network (WiFi connections are out of this API scope) either by getting the comparison result or receiving the phone number of the device that it is used, so they can verify it themselves. + + It uses direct mobile network connections to verify possession of a phone number in the background without requiring user interaction. There are neither OTPs (One-time passwords) received by SMS nor authenticator app downloads, so it is much simpler. It can be used at sign up, login, or transaction time to validate that a user's SIM (Subscriber Identity Module) is both actively connected to the mobile network and not spoofed or cloned. + + + # Relevant Definitions and Concepts + + - **Network-Based Authentication**: Authentication mechanism based on the identification of the endpoint of a network connection. Network operators know to which subscriber a network resource is assigned at a given moment, for example the mobile phone number associated to a specific mobile network connection. + + # API Functionality + + This enables a Service Provider (SP) to verify the phone number of the mobile device being used to access their service where the mobile device is accessing the *service provider* over a mobile network (WiFi connections are out of this API scope). This can happen either by getting the comparison result or receiving the phone number of the device that is used, so they can verify it themselves. + + # 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 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**. + - 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. + + # Sequence Diagram + Number Verification API uses the **standard [OIDC Authorization Code Flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth)**. The following diagram will help to clarify the end-to-end process, including previous steps prior to this API call. + + ![UML Sequence Diagram](https://raw.githubusercontent.com/camaraproject/NumberVerification/main/documentation/API_documentation/assets/uml_v0.3.jpg) + + **Additional details:** + + - **(1):** Authentication must be automatic without any user interactions. Authentication methods such as SMS OTP or user/password are incompatible, as the goal is to validate the mobile phone number that is accessing the App. So it is required to be authentication via mobile network and without the user being involved. the use of parameter prompt=none, as described in **[OIDC Connect](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest)**, ensures no user interaction. + + - **(2):** The way in which the phone_number is retrieved depends on the implementation. For example, access token may be a self contained encrypted JWT, so API can decrypt and identify phone_number. Some other implementations might request the phone_number associated to the token from Authserver. + + # Authorization and authentication + + CAMARA guidelines defines a set of authorization flows which can grant API clients access to the API functionality, as outlined in the document [CAMARA-API-access-and-user-consent.md](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md). 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. + + 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. + + In the case of the Number Verification API scenario and according to the API definition, 3-legged access tokens must be used by API clients to invoke this API with dedicated scope. The API client must authenticate on behalf of a specific user to use this service. This must be done via mobile network authentication. + + # Further info and support + [GSMA Mobile Connect Verified MSISDN specification](https://www.gsma.com/identity/wp-content/uploads/2022/12/IDY.54-Mobile-Connect-Verified-MSISDN-Definition-and-Technical-Requirements-1.0.pdf) was used as source of input for this API. For more about Mobile Connect, please see [Mobile Connect website](https://mobileconnect.io/). + version: 1.0.0-rc.1 + x-camara-commonalities: 0.4.0 + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html +servers: + - url: '{apiRoot}/number-verification/v1rc1' + variables: + apiRoot: + default: http://localhost:9091 + description: API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath +tags: + - name: Phone number verify + description: API operation to verify a phone number received as input. It can be received either in plain text or hashed format. + - 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/plain text phone number matches the phone number associated with the access token + description: | + Verifies if the specified phone number (either in plain text or hashed format) matches the one that the user is currently using. Only one of the plain or hashed formats must be provided. + - The number verification will be done for the user that has authenticated via mobile network + - 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: phoneNumberVerify + parameters: + - in: header + name: X-Correlator + required: false + description: Correlation id for the different services + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/NumberVerificationRequestBody' + required: true + responses: + '200': + description: OK + headers: + X-Correlator: + description: Correlation id for the different services + schema: + type: string + content: + application/json: + schema: + $ref: '#/components/schemas/NumberVerificationMatchResponse' + '400': + $ref: '#/components/responses/Generic400' + '401': + $ref: '#/components/responses/Generic401' + '403': + $ref: '#/components/responses/PhoneNumberVerificationPermissionDenied403' + '500': + $ref: '#/components/responses/Generic500' + '503': + $ref: '#/components/responses/Generic503' + '504': + $ref: '#/components/responses/Generic504' + security: + - openId: + - number-verification:verify + /device-phone-number: + get: + tags: + - Phone number share + summary: Returns the phone number associated with the access token + 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 + - It returns the authenticated user's `device phone number` associated to the access token + operationId: phoneNumberShare + parameters: + - in: header + name: X-Correlator + required: false + description: Correlation id for the different services + schema: + type: string + responses: + '200': + description: OK + headers: + X-Correlator: + description: Correlation id for the different services + schema: + type: string + content: + application/json: + schema: + $ref: '#/components/schemas/NumberVerificationShareResponse' + '400': + $ref: '#/components/responses/Generic400' + '401': + $ref: '#/components/responses/Generic401' + '403': + $ref: '#/components/responses/PhoneNumberVerificationPermissionDenied403' + '500': + $ref: '#/components/responses/Generic500' + '503': + $ref: '#/components/responses/Generic503' + '504': + $ref: '#/components/responses/Generic504' + security: + - openId: + - number-verification:device-phone-number:read +components: + securitySchemes: + openId: + type: openIdConnect + openIdConnectUrl: https://example.com/.well-known/openid-configuration + headers: + x-correlator: + description: Correlation id for the different services + schema: + type: string + schemas: + NumberVerificationRequestBody: + type: object + description: Payload to verify the phone number. + minProperties: 1 + maxProperties: 1 + properties: + phoneNumber: + type: string + pattern: '^\+[1-9][0-9]{4,14}$' + example: '+123456789' + description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. + hashedPhoneNumber: + description: Hashed phone number. SHA-256 (in hexadecimal representation) of the mobile phone number in **E.164 format (starting with country code)**. Prefixed with '+'. + type: string + example: 32f67ab4e4312618b09cd23ed8ce41b13e095fe52b73b2e8da8ef49830e50dba + NumberVerificationMatchResponse: + type: object + description: Number verification result + required: + - devicePhoneNumberVerified + properties: + devicePhoneNumberVerified: + $ref: '#/components/schemas/DevicePhoneNumberVerified' + NumberVerificationShareResponse: + type: object + description: Number verification share result + required: + - devicePhoneNumber + properties: + devicePhoneNumber: + $ref: '#/components/schemas/DevicePhoneNumber' + DevicePhoneNumber: + type: string + pattern: '^\+[1-9][0-9]{4,14}$' + example: '+123456789' + description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. + DevicePhoneNumberVerified: + description: Number verification. True, if it matches + type: boolean + ErrorInfo: + type: object + required: + - status + - code + - message + properties: + status: + type: integer + description: HTTP response status code + code: + type: string + description: Code given to this error + message: + type: string + description: Detailed error description + responses: + Generic400: + description: Problem with the client request + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorInfo' + example: + status: 400 + code: INVALID_ARGUMENT + message: Client specified an invalid argument, request body or query param + Generic401: + description: Unauthorized + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + 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. + PhoneNumberVerificationPermissionDenied403: + description: | + Client does not have sufficient permission. + In addition to regular scenario of `PERMISSION_DENIED`, other scenarios 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_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"}`) + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorInfo' + 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_USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK: + value: + status: 403 + code: NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK + message: Client must authenticate via the mobile network to use this service + GENERIC_403_INVALID_TOKEN_CONTEXT: + value: + status: 403 + code: INVALID_TOKEN_CONTEXT + message: Phone number cannot be deducted from access token context + Generic500: + description: Server error + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorInfo' + example: + status: 500 + code: INTERNAL + message: Server error + Generic503: + description: Service unavailable. Typically the server is down. + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorInfo' + example: + status: 503 + code: UNAVAILABLE + message: Service unavailable + Generic504: + description: Request time exceeded. If it happens repeatedly, consider reducing the request complexity + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorInfo' + example: + status: 504 + code: TIMEOUT + message: Request timeout exceeded. Try later. +externalDocs: + description: Project documentation at CAMARA + url: https://github.com/camaraproject/NumberVerification diff --git a/documentation/API_documentation/NumberVerification-Readiness-Checklist.md b/documentation/API_documentation/NumberVerification-Readiness-Checklist.md new file mode 100644 index 0000000..db01a02 --- /dev/null +++ b/documentation/API_documentation/NumberVerification-Readiness-Checklist.md @@ -0,0 +1,25 @@ +# API Readiness Checklist + +Checklist for number_verification 1.0.0-rc.1 in release r1.1 + +| Nr | API release assets | alpha | release-candidate | public-release
initial | public-release
stable | Status | Comments | +|----|----------------------------------------------|:-----:|:-----------------:|:-------:|:------:|:----:|:----:| +| 1 | API definition | M | M | M | M | Y | [link](/code/API_definitions/number_verification.yaml) | +| 2 | Design guidelines from Commonalities applied | O | M | M | M | Y | | +| 3 | Guidelines from ICM applied | O | M | M | M | Y | | +| 4 | API versioning convention applied | M | M | M | M | Y | | +| 5 | API documentation | M | M | M | M | Y | Embed documentation into API spec - [link](/code/API_definitions/number_verification.yaml) | +| 6 | User stories | O | O | O | M | N | [link](documentation/API_documentation/) | +| 7 | Basic API test cases & documentation | O | M | M | M | N | link | +| 8 | Enhanced API test cases & documentation | O | O | O | M | N | link | +| 9 | Test result statement | O | O | O | M | N | link | +| 10 | API release numbering convention applied | M | M | M | M | Y | | +| 11 | Change log updated | M | M | M | M | N | [link](/CHANGELOG.md) | +| 12 | Previous public-release was certified | O | O | O | M | Y | | + + + + +Note: It is normal that the checklists of the (final) release-candidate and its subsequent public-release are the same, while additional release assets are required for a subsequent stable public-release. + +The documentation for the content of the checklist is here: [API Readiness Checklist documentation](https://wiki.camaraproject.org/x/AgAVAQ#APIReleaseProcess-APIreadinesschecklist) \ No newline at end of file