diff --git a/code/API_definitions/number-verification.yaml b/code/API_definitions/number-verification.yaml index b894a66..94b40f8 100644 --- a/code/API_definitions/number-verification.yaml +++ b/code/API_definitions/number-verification.yaml @@ -24,6 +24,9 @@ info: # 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 If the API Consumer has a TS.43 temporary token created on the mobile device then this API works over all connections e.g. WiFi taking advantage of the SIM-Based authentication. @@ -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,25 +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. - # Sequence Diagram - - 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. - - ![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. - 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. - 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. @@ -83,7 +70,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 @@ -92,7 +79,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