diff --git a/code/API_definitions/qos-profiles.yaml b/code/API_definitions/qos-profiles.yaml index e8a2c52346..032b5b518f 100644 --- a/code/API_definitions/qos-profiles.yaml +++ b/code/API_definitions/qos-profiles.yaml @@ -16,6 +16,12 @@ 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) @@ -23,20 +29,22 @@ info: 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: @@ -44,9 +52,14 @@ paths: - 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: diff --git a/code/API_definitions/quality-on-demand.yaml b/code/API_definitions/quality-on-demand.yaml index 1397bcbcdc..42d4285669 100644 --- a/code/API_definitions/quality-on-demand.yaml +++ b/code/API_definitions/quality-on-demand.yaml @@ -55,6 +55,12 @@ info: ![QoD Management API](https://github.com/raw/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) @@ -62,20 +68,22 @@ info: 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: