Merge pull request #295 from eric-murray/main

Add required security scheme and scopes

code/API_definitions/qos-profiles.yaml

@@ -16,37 +16,50 @@ info:
 
     How QoS profiles are mapped to connectivity characteristics are subject to agreements between the communication service provider and the API invoker. Within the CAMARA project, you can find a sample for such a mapping of QoS profiles. [CAMARA QoS Profiles Mapping Table (REFERENCE DRAFT)](https://github.com/camaraproject/QualityOnDemand/blob/main/documentation/API_documentation/QoSProfile_Mapping_Table.md)
 
+    # 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.
+
     # Further info and support
 
     (FAQs will be added in a later version of the documentation)
   license:
     name: Apache 2.0
     url: https://www.apache.org/licenses/LICENSE-2.0.html
   version: wip
+
 externalDocs:
   description: Product documentation at Camara
   url: https://github.com/camaraproject/
-security:
-  - oAuth2ClientCredentials: []
+
 servers:
   - url: "{apiRoot}/qos-profiles/vwip"
     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: QoS Profiles
     description: Manage QoS Profiles
+
 paths:
   /qos-profiles:
     get:
       tags:
         - QoS Profiles
       summary: "Get All QoS Profiles"
       description: |
-        Returns all QoS Profiles that match the given criteria.
-        If no criteria is given, all QoS Profiles are returned.
+        Returns all QoS Profiles that match the given criteria, or all profiles if no criteria is specified.
+
+        The access token may be either a 2-legged or 3-legged access token. If the access token is 3-legged, all returned QoS Profiles must be available to all end users associated with the access token.
+
       operationId: getQosProfiles
+      security:
+        - openId:
+            - qos-profiles:qos-profiles:read
       parameters:
         - name: name
           in: query
@@ -92,6 +105,12 @@ paths:
       operationId: getQosProfile
       description: |
         Returns a QoS Profile that matches the given name.
+
+        The access token may be either a 2-legged or 3-legged access token. If the access token is 3-legged, a QoS Profile is only returned if available to all end users associated with the access token.
+
+      security:
+        - openId:
+            - qos-profiles:qos-profiles:read
       parameters:
         - name: name
           in: path
@@ -125,14 +144,9 @@ paths:
 
 components:
   securitySchemes:
-    oAuth2ClientCredentials:
-      description: |
-        The QoS Profiles API makes use of the OAUTH 2.0 client credentials grant which is applicable for server to server use cases involving trusted partners or clients without any protected user data involved. In this method the API invoker client is registered as a confidential client with an authorization grant type of client_credentials
-      type: oauth2
-      flows:
-        clientCredentials:
-          tokenUrl: https://api.example.com/oauth/token
-          scopes: {}
+    openId:
+      type: openIdConnect
+      openIdConnectUrl: https://example.com/.well-known/openid-configuration
 
   parameters:
     x-correlator:

code/API_definitions/quality-on-demand.yaml

@@ -55,27 +55,35 @@ info:
 
     ![QoD Management API](https://raw.githubusercontent.com/camaraproject/QualityOnDemand/main/documentation/API_documentation/resources/QoD_details.PNG)
 
+    # 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.
+
     # Further info and support
 
     (FAQs will be added in a later version of the documentation)
   license:
     name: Apache 2.0
     url: https://www.apache.org/licenses/LICENSE-2.0.html
   version: wip
+
 externalDocs:
   description: Product documentation at Camara
   url: https://github.com/camaraproject/
-security:
-  - oAuth2ClientCredentials: []
+
 servers:
   - url: "{apiRoot}/quality-on-demand/vwip"
     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: QoS Sessions
     description: Manage QoS sessions
+
 paths:
   /sessions:
     post:
@@ -94,12 +102,16 @@ paths:
 
         A `QOS_STATUS_CHANGED` event notification with `qosStatus` as `UNAVAILABLE` will also be send if the network terminates the session before the requested duration expired
 
-        NOTE: in case of a `QOS_STATUS_CHANGED` event with `qosStatus` as `UNAVAILABLE` and `statusInfo` as `NETWORK_TERMINATED` the resources of the QoS session are not directly released, but will get deleted automatically at earliest 360 seconds after the event.
-        This behavior allows clients which are not receiving notification events but are polling to get the session information with
-        the `qosStatus` `UNAVAILABLE` and `statusInfo` `NETWORK_TERMINATED`. Before a client can attempt to create a new QoD session
-        for the same device and flow period they must release the session resources with an explicit `delete` operation if not yet automatically deleted.
+        **NOTES:**
+        - In case of a `QOS_STATUS_CHANGED` event with `qosStatus` as `UNAVAILABLE` and `statusInfo` as `NETWORK_TERMINATED` the resources of the QoS session are not directly released, but will get deleted automatically at earliest 360 seconds after the event.
+
+          This behavior allows clients which are not receiving notification events but are polling to get the session information with the `qosStatus` `UNAVAILABLE` and `statusInfo` `NETWORK_TERMINATED`. Before a client can attempt to create a new QoD session for the same device and flow period they must release the session resources with an explicit `delete` operation if not yet automatically deleted.
+        - The access token may be either 2-legged or 3-legged. If a 3-legged access token is used, the end user identified by the `device` parameter must also be associated with the access token.
 
       operationId: createSession
+      security:
+        - openId:
+            - quality-on-demand:sessions:create
       parameters:
         - $ref: "#/components/parameters/x-correlator"
       requestBody:
@@ -254,18 +266,22 @@ paths:
           $ref: "#/components/responses/Generic501"
         "503":
           $ref: "#/components/responses/Generic503"
-      security:
-        - oAuth2ClientCredentials: []
-        - threeLegged:
-            - "qod-sessions-write"
 
   /sessions/{sessionId}:
     get:
       tags:
         - QoS Sessions
       summary: Get QoS session information
-      description: Querying for QoS session resource information details
+      description: |
+        Querying for QoS session resource information details
+
+        **NOTES:**
+        - The access token may be either 2-legged or 3-legged. If a 3-legged access token is used, the end user associated with the session must also be associated with the access token.
+
       operationId: getSession
+      security:
+        - openId:
+            - quality-on-demand:sessions:read
       parameters:
         - name: sessionId
           in: path
@@ -301,10 +317,6 @@ paths:
           $ref: "#/components/responses/Generic500"
         "503":
           $ref: "#/components/responses/Generic503"
-      security:
-        - oAuth2ClientCredentials: []
-        - threeLegged:
-            - "qod-sessions-read"
 
     delete:
       tags:
@@ -317,7 +329,14 @@ paths:
         - `qosStatus` as `UNAVAILABLE` and
         - `statusInfo` as `DELETE_REQUESTED`
         There will be no notification event if the `qosStatus` was already `UNAVAILABLE`.
+
+        **NOTES:**
+        - The access token may be either 2-legged or 3-legged. If a 3-legged access token is used, the end user associated with the session must also be associated with the access token.
+
       operationId: deleteSession
+      security:
+        - openId:
+            - quality-on-demand:sessions:delete
       parameters:
         - name: sessionId
           in: path
@@ -344,10 +363,6 @@ paths:
           $ref: "#/components/responses/Generic500"
         "503":
           $ref: "#/components/responses/Generic503"
-      security:
-        - oAuth2ClientCredentials: []
-        - threeLegged:
-            - "qod-sessions-delete"
 
   /sessions/{sessionId}/extend:
     post:
@@ -361,7 +376,14 @@ paths:
         - Previous duration: 30,000 seconds
         - Requested additional duration: 30,000 seconds
         - New overall session duration: 50,000 seconds (the maximum allowed)
+
+        **NOTES:**
+        - The access token may be either 2-legged or 3-legged. If a 3-legged access token is used, the end user associated with the session must also be associated with the access token.
+
       operationId: extendQosSessionDuration
+      security:
+        - openId:
+            - quality-on-demand:sessions:update
       parameters:
         - name: sessionId
           in: path
@@ -419,38 +441,17 @@ paths:
           $ref: "#/components/responses/Generic500"
         "503":
           $ref: "#/components/responses/Generic503"
-      security:
-        - oAuth2ClientCredentials: []
-        - threeLegged:
-            - "qod-sessions-write"
 
 components:
   securitySchemes:
-    oAuth2ClientCredentials:
-      description: |
-        The QoD API makes use of the OAUTH 2.0 client credentials grant which is applicable for server to server use cases involving trusted partners or clients without any protected user data involved. In this method the API invoker client is registered as a confidential client with an authorization grant type of client_credentials
-      type: oauth2
-      flows:
-        clientCredentials:
-          tokenUrl: https://api.example.com/oauth/token
-          scopes: {}
+    openId:
+      type: openIdConnect
+      openIdConnectUrl: https://example.com/.well-known/openid-configuration
     notificationsBearerAuth:
       description: Bearer authentication for notifications
       type: http
       scheme: bearer
       bearerFormat: "{$request.body#/webhook/notificationAuthToken}"
-    threeLegged:
-      type: oauth2
-      description: This API uses OAuth 2 with the authorization code grant flow.
-      flows:
-        authorizationCode:
-          authorizationUrl: https://api.example.com/oauth2/authorize
-          tokenUrl: https://api.example.com/oauth/token
-          scopes:
-            qod-sessions-read: Retrieval of QoS sessions
-            qod-sessions-write: Creation and update of QoS sessions
-            qod-sessions-delete: Deletion of QoS sessions
-            qod-profiles-read: Retrieval of QoS profiles
 
   parameters:
     x-correlator: