Merge pull request #132 from camaraproject/main

Rebase with main

code/API_definitions/number_verification.yaml

@@ -40,7 +40,9 @@ info:
 
     # 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.
+    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.
 
     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.
 
@@ -164,6 +166,11 @@ components:
     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
@@ -224,10 +231,8 @@ components:
     Generic400:
       description: Problem with the client request
       headers:
-        X-Correlator:
-          description: Correlation id for the different services
-          schema:
-            type: string
+        x-correlator:
+          $ref: "#/components/headers/x-correlator"
       content:
         application/json:
           schema:
@@ -237,58 +242,62 @@ components:
             code: INVALID_ARGUMENT
             message: Client specified an invalid argument, request body or query param
     Generic401:
-      description: Authentication problem with the client request
+      description: Unauthorized
       headers:
-        X-Correlator:
-          description: Correlation id for the different services
-          schema:
-            type: string
+        x-correlator:
+          $ref: "#/components/headers/x-correlator"
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/ErrorInfo'
-          example:
-            status: 401
-            code: UNAUTHENTICATED
-            message: Request not authenticated due to missing, invalid, or expired credentials
+          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:
-          description: Correlation id for the different services
-          schema:
-            type: string
+        x-correlator:
+          $ref: "#/components/headers/x-correlator"
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/ErrorInfo'
           examples:
-            PermissionDenied:
+            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
-            UserNotAuthenticatedByMobileNetwork:
+                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
-            InvalidTokenContext:
+            GENERIC_403_INVALID_TOKEN_CONTEXT:
               value:
                 status: 403
-                code: NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT
+                code: 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
+        x-correlator:
+          $ref: "#/components/headers/x-correlator"
       content:
         application/json:
           schema:
@@ -300,10 +309,8 @@ components:
     Generic503:
       description: Service unavailable. Typically the server is down.
       headers:
-        X-Correlator:
-          description: Correlation id for the different services
-          schema:
-            type: string
+        x-correlator:
+          $ref: "#/components/headers/x-correlator"
       content:
         application/json:
           schema:
@@ -315,10 +322,8 @@ components:
     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
+        x-correlator:
+          $ref: "#/components/headers/x-correlator"
       content:
         application/json:
           schema:

documentation/API_documentation/NumberVerification_verify_User_Story.md

@@ -0,0 +1,10 @@
+# Number Verification Verify API User Story
+
+| **Item** | **Details** |
+| ---- | ------- |
+| ***Summary*** | As an enterprise application developer, I want to verify the phone number associated with the phone from which the call was made, so I can get a proof of possession of the phone number. |
+| ***Roles, Actors and Scope*** | **Roles:** Customer:User, Customer:BusinessManager, Customer:Administrator<br>, end-user, Communication Service Provider (CSP), Channel Partner **Actors:** Application service providers, hyperscalers, aggregator, application developers, end users, Communication Service Provider (CSP). <br> **Scope:**  <br> - Verifies if the specified phone number (plain text or hashed format) matches the one that the user is currently using. |
+| ***Pre-conditions*** |The preconditions are listed below:<br><ol><li>The Customer:BusinessManager and Customer:Administrator have been onboarded to the CSP's API platform via (or not) a Channel Partner.</li><li>The Customer:BusinessManager has successfully subscribed to the Number Verification product from the product catalog.</li><li>The Customer:Administrator has onboarded the Customer:User to the CSP API platform via (or not) a Channel Partner.</li><li>The Customer:User performs an authorization request to CSP.</li><li> The CSP checks access & user approval then provide access token to the Customer:User </li><li> The Customer:User get the access token, via (or not) the Channel Partner, based on network authentication to ensure secure access of the API.|
+| ***Activities/Steps*** | **Starts when:** The customer application makes a POST verify via the number verification API providing in the request the phone number provided by the user on the application. This request could be done via (or not) the Channel Partner. This input could be hashed or plain.<br>**Ends when:** The Number Verification Server responds to confirm whether the provided phone number matches the device from which the request was initiated or not. |
+| ***Post-conditions*** | The customer application could continue offering its service to the user with the confirmation of the user phone number.  |
+| ***Exceptions*** | Several exceptions might occur during the Number Verification API operations<br>- Unauthorized: Not valid credentials (e.g. use of already expired access token).<br>- Invalid input: Not valid input data to invoke operation (e.g. phone number without the '+' prefix).<br>- Not able to provide: Client authentication was not performed via mobile network. Not working on mobile hotspot (tethering) neither Wifi nor VPN mobile connections |

documentation/API_documentation/NumberVerificationdevice_phone_number_User_Story.md

@@ -0,0 +1,10 @@
+# Number Verification Device Phone Number API User Story
+
+| **Item** | **Details** |
+| ---- | ------- |
+| ***Summary*** | As an enterprise application developer, I want to retrieve the phone number associated with the device from which the call was made, so that I can ensure that I obtain the correct phone number and avoid fraud e.g. identity theft. |
+| ***Roles, Actors and Scope*** | **Roles:** Customer:User, Customer:BusinessManager, Customer:Administrator, end-user, Communication Service Provider (CSP), Channel Partner. <br> **Actors:** Application service providers, hyperscalers, aggregator, application developers, end users, Communication Service Provider (CSP). <br> **Scope:**  <br>-Returns the phone number associated with the access token so API clients can get the phone number and verify it themselves. This user story is valid in direct interaction between Application service providers and CSP as with the presence of the channel partner betwen them. |
+| ***Pre-conditions*** |The preconditions are listed below:<br><ol><li>The Customer:BusinessManager and Customer:Administrator have been onboarded to the CSP's API platform via (or not) a Channel Partner.</li><li>The Customer:BusinessManager has successfully subscribed to the Number Verification product from the product catalog.</li><li>The Customer:Administrator has onboarded the Customer:User to the platform via (or not) a Channel Partner.</li><li>The Customer:user performs an authorization request to CSP</li><li> The CSP checked access & user approval then provide access token to the Customer:user </li><li> The Customer:User gets the access token,via (or not) a Channel Partner, based on network authentication to ensure secure access of the API.|
+| ***Activities/Steps*** | **Starts when:** The customer application makes a POST device phone number via the number verification API. This request could be done via (or not) the Channel Partner.<br>**Ends when:** The Number verification server answers providing the phone number corresponding to the one of the device from which the request was triggered. The customer application can check if this number corresponds to the one keyed by the end-user.|
+| ***Post-conditions*** | The customer application could continue offering its service to the end-user with the confirmation of the end-user phone number.  |
+| ***Exceptions*** | Several exceptions might occur during the Number Verification API operations<br>- Unauthorized: Not valid credentials (e.g. use of already expired access token).<br>- Invalid input: Not valid input data to invoke operation (e.g. phone number without the '+' prefix).<br>- Not able to provide: Client authentication was not performed via mobile network. Not working on mobile hotspot (tethering) neither Wifi nor VPN mobile connections|