Merge pull request #64 from eric-murray/eric-murray-patch-2

Incorporate Commonalities WG recommendations on Simplification of Device object

code/API_definitions/CAMARA Mobile Device Identifier API.yaml

@@ -54,10 +54,32 @@ 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.
 
+    ## Handling of mobile subscription information:
+
+    ### Optional mobile subscription identifiers for 3-legged tokens:
+
+    - When using a 3-legged access token, the mobile subscription identifier associated with the access token must be considered as the mobile subscription identifier for the API request. This means that no mobile subscription identifiers are required in the request, and if included it must identify the same subscription. Hence **it is recommended NOT to include it in these scenarios** to simplify the API usage and avoid additional validations.
+
+    ### Validation mechanism:
+
+    - The API server will determine the mobile subscription identifier (e.g. phone number) from the access token itself if that information is associated with it (i.e. 3-legged token).
+    - If the API request itself additionally includes one or more mobile subscription identifiers when using a 3-legged access token, the API will validate that the identifier(s) provided matches the one associated with the access token.
+    - If there is a mismatch, the API will respond with a `403 INVALID_TOKEN_CONTEXT` error, indicating that the mobile subscription information in the request does not match the token.
+
+    ### Error handling for unidentifiable devices:
+
+    - If no mobile subscription information is included in the request and the mobile subscription information cannot be derived from the 3-legged access token, the server will return a `422 UNIDENTIFIABLE_DEVICE` error.
+
+    ### Restrictions for tokens without an associated authenticated identifier:
+
+    - For scenarios which do not have a mobile subscription identifier associated to the token during the authentication flow, e.g. 2-legged access tokens, mobile subscription identifiers MUST be provided in the API request. This ensures that the mobile subscription identifier is explicit and valid for each API call made with these tokens.
+
     # API functionality
 
     The API defines two service endpoints:
@@ -73,7 +95,7 @@ info:
 
     If the mobile subscription parameters contain a formatting error, a `400 INVALID_ARGUMENT` error is returned.
 
-    If the mobile subscription cannot be identified from the provided parameters, a `404 NOT_FOUND` error is returned.
+    If the mobile subscription cannot be identified from the provided parameters, a `404 DEVICE_NOT_FOUND` error is returned.
 
     If the end user has not consented to the API consumer getting access to the device identifier information, then a `403 PERMISSION_DENIED` error is returned.
 
@@ -139,6 +161,7 @@ paths:
 
       requestBody:
         description: Parameters to create a new session
+        required: false
         content:
           application/json:
             schema:
@@ -159,6 +182,8 @@ paths:
           $ref: '#/components/responses/405MethodNotAllowed'
         "406":
           $ref: '#/components/responses/406Unacceptable'
+        "422":
+          $ref: '#/components/responses/422UnprocessableContent'
         "429":
           $ref: '#/components/responses/429TooManyRequests'
         "500":
@@ -192,6 +217,7 @@ paths:
 
       requestBody:
         description: Parameters to create a new session
+        required: false
         content:
           application/json:
             schema:
@@ -212,6 +238,8 @@ paths:
           $ref: '#/components/responses/405MethodNotAllowed'
         "406":
           $ref: '#/components/responses/406Unacceptable'
+        "422":
+          $ref: '#/components/responses/422UnprocessableContent'
         "429":
           $ref: '#/components/responses/429TooManyRequests'
         "500":
@@ -316,6 +344,7 @@ components:
                 status: 400
                 code: OUT_OF_RANGE
                 message: "Invalid value: ipv4Address.publicPort"
+
     401Unauthorized:
       description: Unauthorized
       headers:
@@ -324,13 +353,20 @@ components:
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/ErrorResponse'
+            $ref: "#/components/schemas/ErrorResponse"
           examples:
-            InvalidCredentials:
+            GENERIC_401_UNAUTHENTICATED:
+              description: Request cannot be authenticated
               value:
                 status: 401
                 code: UNAUTHENTICATED
-                message: "Request not authenticated due to missing, invalid, or expired credentials"
+                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.
 
     403Forbidden:
       description: Forbidden
@@ -340,30 +376,43 @@ components:
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/ErrorResponse'
+            $ref: "#/components/schemas/ErrorResponse"
           examples:
-            InsufficientPermissions:
+            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: "API consumer does not have sufficient permissions to perform this action"
+                message: Client does not have sufficient permissions to perform this action.
+            GENERIC_403_INVALID_TOKEN_CONTEXT:
+              description: Reflect some inconsistency between information in some field of the API and the related OAuth2 Token
+              value:
+                status: 403
+                code: INVALID_TOKEN_CONTEXT
+                message: "{{field}} is not consistent with access token."
 
     404NotFound:
-      description: Subscriber Not Found
+      description: Not found
       headers:
         x-correlator:
           $ref: "#/components/headers/X-Correlator"
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/ErrorResponse'
+            $ref: "#/components/schemas/ErrorResponse"
           examples:
-            SubscriberNotFound:
-              description: The specified parameters are either inconsistent (if multiple parameters are specified) or not currently associated with any customers of this service
+            GENERIC_404_NOT_FOUND:
+              description: Resource is not found
               value:
                 status: 404
                 code: NOT_FOUND
-                message: "No device found for the specified parameters"
+                message: The specified resource is not found.
+            GENERIC_404_DEVICE_NOT_FOUND:
+              description: Device identifier not found
+              value:
+                status: 404
+                code: DEVICE_NOT_FOUND
+                message: Device identifier not found.
 
     405MethodNotAllowed:
       description: Method Not Allowed
@@ -399,6 +448,29 @@ components:
                 code: NOT_ACCEPTABLE
                 message: "The server cannot produce a response matching the content requested by the client through Accept-* headers"
 
+    422UnprocessableContent:
+      description: Unprocessable Content
+      headers:
+        x-correlator:
+          $ref: "#/components/headers/X-Correlator"
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorResponse"
+          examples:
+            GENERIC_422_DEVICE_IDENTIFIERS_MISMATCH:
+              description: Inconsistency between device identifiers not pointing to the same device
+              value:
+                status: 422
+                code: DEVICE_IDENTIFIERS_MISMATCH
+                message: Provided device identifiers are not consistent.
+            GENERIC_422_DEVICE_NOT_APPLICABLE:
+              description: Service is not available for the provided device
+              value:
+                status: 422
+                code: DEVICE_NOT_APPLICABLE
+                message: The service is not available for the provided device.
+
     429TooManyRequests:
       description: Too Many Requests
       headers:
@@ -523,7 +595,8 @@ components:
         * `ipv6Address`
         * `phoneNumber`
         * `networkAccessIdentifier`
-        NOTE: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device.
+        NOTE 1: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device.
+        NOTE 2: for the Commonalities release v0.4, we are enforcing that the networkAccessIdentifier is only part of the schema for future-proofing, and CAMARA does not currently allow its use. After the CAMARA meta-release work is concluded and the relevant issues are resolved, its use will need to be explicitly documented in the guidelines.
       type: object
       properties:
         phoneNumber:
@@ -581,10 +654,10 @@ components:
       example: "[email protected]"
 
     PhoneNumber:
-      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, optionally prefixed with '+'.
+      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 '+'.
       type: string
-      pattern: '^\+?[0-9]{5,15}$'
-      example: "123456789"
+      pattern: '^\+[1-9][0-9]{4,14}$'
+      example: "+123456789"
 
     Port:
       description: TCP or UDP port number