From 08dd2944ba8fac383e5c1c9a63bed47f92cd67eb Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Fri, 22 Aug 2025 11:00:42 +0200 Subject: [PATCH 1/4] Remove sequence flow diagram --- code/API_definitions/number-verification.yaml | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/code/API_definitions/number-verification.yaml b/code/API_definitions/number-verification.yaml index b894a66..a9f5adf 100644 --- a/code/API_definitions/number-verification.yaml +++ b/code/API_definitions/number-verification.yaml @@ -46,22 +46,18 @@ info: It compares the received phone number with the user's phone number associated to the access token in order to respond **true/false**. - The /device-phone-number endpoint returns the phone number associated by the network operator with the SIM in the end user's device. - # Sequence Diagram + # Implementation Details - The following sequence diagram shows an example of a direct integration into the developer's application and the API Provider's Authorization Server and API for the case that no temporary token is available. + Detailed sequence diagrams of end-to-end integration with CIBA and JWT-Bearer token flow are available in **[CAMARA-API-access-and-user-consent document](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md)**. - ![UML Sequence Diagram](https://raw.githubusercontent.com/camaraproject/NumberVerification/r2.4/documentation/API_documentation/assets/uml_v0.3.jpg) - - **Implementation Details:** - - - **(1):** Authentication must be automatic without any user interactions. + - **Note1:** 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. The API Consumer should use the request parameter prompt=none in the Authentication Request, as described in **[OIDC Connect](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest)**, ensuring no user interaction. The API Provider implies the request parameter prompt=none in the Authentication Request for this API. - - **(2):** The way in which the phone number is retrieved depends upon the implementation. + - **Note2:** The way in which the phone number is retrieved depends upon the implementation. For example, the access token may be a self-contained encrypted JWT, and so the API provider can decrypt and identify phone number directly from the access token. Other implementations might retrieve the phone number associated with the access token from their Authorization Server. From 2dae581cc85beac45211797cfd528e9ca2be00f4 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Fri, 22 Aug 2025 11:01:48 +0200 Subject: [PATCH 2/4] Update number-verification.yaml --- code/API_definitions/number-verification.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/number-verification.yaml b/code/API_definitions/number-verification.yaml index a9f5adf..fee45db 100644 --- a/code/API_definitions/number-verification.yaml +++ b/code/API_definitions/number-verification.yaml @@ -79,7 +79,7 @@ info: As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible error response if it is explicitly documented in the API. - version: 2.1.0-rc.1 + version: wip x-camara-commonalities: 0.6 license: name: Apache 2.0 @@ -88,7 +88,7 @@ externalDocs: description: Project documentation at CAMARA url: https://github.com/camaraproject/NumberVerification servers: - - url: '{apiRoot}/number-verification/v2rc1' + - url: '{apiRoot}/number-verification/vwip' variables: apiRoot: default: http://localhost:9091 From b0903ef719f9d25f505875aed9c36b09cc67a92c Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Mon, 25 Aug 2025 14:21:12 +0200 Subject: [PATCH 3/4] Update number-verification.yaml --- code/API_definitions/number-verification.yaml | 21 ++++++------------- 1 file changed, 6 insertions(+), 15 deletions(-) diff --git a/code/API_definitions/number-verification.yaml b/code/API_definitions/number-verification.yaml index fee45db..040307d 100644 --- a/code/API_definitions/number-verification.yaml +++ b/code/API_definitions/number-verification.yaml @@ -23,6 +23,9 @@ info: This API enables an API Consumer to verify or retrieve the phone number of the mobile device being used to access their service. # The Authentication Request + + **For NumberVerification the API provider guarantees that there is no user interaction.** Would user interaction be needed the authorization server returns an error. + 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. ## Authentication Request with a temporary token @@ -38,6 +41,9 @@ info: If the API Consumer does not have a TS.43 temporary token then the API Consumer must use OpenId Connect Authorization Code Flow as described in the current release of [CAMARA APIs Access and User Consent Management](https://github.com/camaraproject/IdentityAndConsentManagement). For this method of authentication to work, the device must be connected to the mobile network. + The API Consumer should use the request parameter prompt=none in the Authentication Request, as described in **[OIDC Connect](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest)**, ensuring no user interaction. + The API Provider implies the request parameter prompt=none in the Authentication Request for this API. + # Resources and Operations overview This API currently provides two endpoints which both require a **3-legged token** obtained by using one of the two methods indicated in _The Authentication Request_ section. This therefore **excludes** using, for example, SMS/OTP or user/password as an authentication method: @@ -46,21 +52,6 @@ info: It compares the received phone number with the user's phone number associated to the access token in order to respond **true/false**. - The /device-phone-number endpoint returns the phone number associated by the network operator with the SIM in the end user's device. - # Implementation Details - - Detailed sequence diagrams of end-to-end integration with CIBA and JWT-Bearer token flow are available in **[CAMARA-API-access-and-user-consent document](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md)**. - - - **Note1:** 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. - - The API Consumer should use the request parameter prompt=none in the Authentication Request, as described in **[OIDC Connect](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest)**, ensuring no user interaction. - - The API Provider implies the request parameter prompt=none in the Authentication Request for this API. - - - **Note2:** The way in which the phone number is retrieved depends upon the implementation. - For example, the access token may be a self-contained encrypted JWT, and so the API provider can decrypt and identify phone number directly from the access token. - Other implementations might retrieve the phone number associated with the access token from their Authorization Server. - # Authorization and authentication The "Camara Security and Interoperability Profile" provides details of how an API consumer requests an access token. Please refer to [Identity and Consent Management](https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the profile. From e66502b0ad36423494ad9bd1ad11beeb6c3a5906 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Mon, 25 Aug 2025 16:26:44 +0200 Subject: [PATCH 4/4] Update number-verification.yaml --- code/API_definitions/number-verification.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/number-verification.yaml b/code/API_definitions/number-verification.yaml index 040307d..94b40f8 100644 --- a/code/API_definitions/number-verification.yaml +++ b/code/API_definitions/number-verification.yaml @@ -23,7 +23,7 @@ info: This API enables an API Consumer to verify or retrieve the phone number of the mobile device being used to access their service. # The Authentication Request - + **For NumberVerification the API provider guarantees that there is no user interaction.** Would user interaction be needed the authorization server returns an error. 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.