From 605af38233c90d8fb99eacfc54b392ab1cc51a25 Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Mon, 20 May 2024 15:29:13 +0100 Subject: [PATCH 1/8] Update qos-profiles.yaml --- code/API_definitions/qos-profiles.yaml | 29 +++++++++++++++++--------- 1 file changed, 19 insertions(+), 10 deletions(-) diff --git a/code/API_definitions/qos-profiles.yaml b/code/API_definitions/qos-profiles.yaml index 091b9d3b73..98901db7ef 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) @@ -26,20 +32,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: @@ -50,6 +58,9 @@ paths: Returns all QoS Profiles that match the given criteria. If no criteria is given, all QoS Profiles are returned. operationId: getQosProfiles + security: + - openId: + - qos-profiles:qos-profiles:read parameters: - name: name in: query @@ -95,6 +106,9 @@ paths: operationId: getQosProfile description: | Returns a QoS Profile that matches the given name. + security: + - openId: + - qos-profiles:qos-profiles:read parameters: - name: name in: path @@ -128,14 +142,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: From 04128b2881cbdefd1ad00e199cc60f079e04fd6b Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Mon, 20 May 2024 15:38:35 +0100 Subject: [PATCH 2/8] Update quality-on-demand.yaml --- code/API_definitions/quality-on-demand.yaml | 65 +++++++++------------ 1 file changed, 26 insertions(+), 39 deletions(-) diff --git a/code/API_definitions/quality-on-demand.yaml b/code/API_definitions/quality-on-demand.yaml index 5363730a65..10279720a2 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) @@ -65,20 +71,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: @@ -104,6 +112,9 @@ paths: for the same device and flow period they must release the session resources with an explicit `delete` operation if not yet automatically deleted. operationId: createSession + security: + - openId: + - quality-on-demand:sessions:create parameters: - $ref: "#/components/parameters/x-correlator" requestBody: @@ -258,10 +269,6 @@ paths: $ref: "#/components/responses/Generic501" "503": $ref: "#/components/responses/Generic503" - security: - - oAuth2ClientCredentials: [] - - threeLegged: - - "qod-sessions-write" /sessions/{sessionId}: get: @@ -270,6 +277,9 @@ paths: summary: Get QoS session information description: Querying for QoS session resource information details operationId: getSession + security: + - openId: + - quality-on-demand:sessions:read parameters: - name: sessionId in: path @@ -305,10 +315,6 @@ paths: $ref: "#/components/responses/Generic500" "503": $ref: "#/components/responses/Generic503" - security: - - oAuth2ClientCredentials: [] - - threeLegged: - - "qod-sessions-read" delete: tags: @@ -322,6 +328,9 @@ paths: - `statusInfo` as `DELETE_REQUESTED` There will be no notification event if the `qosStatus` was already `UNAVAILABLE`. operationId: deleteSession + security: + - openId: + - quality-on-demand:sessions:delete parameters: - name: sessionId in: path @@ -348,10 +357,6 @@ paths: $ref: "#/components/responses/Generic500" "503": $ref: "#/components/responses/Generic503" - security: - - oAuth2ClientCredentials: [] - - threeLegged: - - "qod-sessions-delete" /sessions/{sessionId}/extend: post: @@ -368,6 +373,9 @@ paths: - New remaining duration: 86,400 seconds (the maximum allowed) - New overall session duration: 96,400 seconds operationId: extendQosSessionDuration + security: + - openId: + - quality-on-demand:sessions:update parameters: - name: sessionId in: path @@ -425,39 +433,18 @@ 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: name: x-correlator From 62e49d487bb1163582939e0f7d57c3cd3864ea6b Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Mon, 20 May 2024 16:01:07 +0100 Subject: [PATCH 3/8] Update qos-profiles.yaml --- code/API_definitions/qos-profiles.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/qos-profiles.yaml b/code/API_definitions/qos-profiles.yaml index 98901db7ef..3c115a4ae0 100644 --- a/code/API_definitions/qos-profiles.yaml +++ b/code/API_definitions/qos-profiles.yaml @@ -60,7 +60,7 @@ paths: operationId: getQosProfiles security: - openId: - - qos-profiles:qos-profiles:read + - qos-profiles:qos-profiles:read parameters: - name: name in: query @@ -108,7 +108,7 @@ paths: Returns a QoS Profile that matches the given name. security: - openId: - - qos-profiles:qos-profiles:read + - qos-profiles:qos-profiles:read parameters: - name: name in: path From 4cc402c7201df1e3b49957378ba2c0ad15ac5e5a Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Mon, 20 May 2024 16:02:59 +0100 Subject: [PATCH 4/8] Update quality-on-demand.yaml --- code/API_definitions/quality-on-demand.yaml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/code/API_definitions/quality-on-demand.yaml b/code/API_definitions/quality-on-demand.yaml index 10279720a2..fdb96cdf95 100644 --- a/code/API_definitions/quality-on-demand.yaml +++ b/code/API_definitions/quality-on-demand.yaml @@ -60,7 +60,7 @@ info: 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) @@ -114,7 +114,7 @@ paths: operationId: createSession security: - openId: - - quality-on-demand:sessions:create + - quality-on-demand:sessions:create parameters: - $ref: "#/components/parameters/x-correlator" requestBody: @@ -279,7 +279,7 @@ paths: operationId: getSession security: - openId: - - quality-on-demand:sessions:read + - quality-on-demand:sessions:read parameters: - name: sessionId in: path @@ -330,7 +330,7 @@ paths: operationId: deleteSession security: - openId: - - quality-on-demand:sessions:delete + - quality-on-demand:sessions:delete parameters: - name: sessionId in: path @@ -375,7 +375,7 @@ paths: operationId: extendQosSessionDuration security: - openId: - - quality-on-demand:sessions:update + - quality-on-demand:sessions:update parameters: - name: sessionId in: path @@ -444,7 +444,7 @@ components: type: http scheme: bearer bearerFormat: "{$request.body#/webhook/notificationAuthToken}" - + parameters: x-correlator: name: x-correlator From 7cce24bbb17acd27e8f9a7dd5be3e9fdae30d91e Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Mon, 24 Jun 2024 15:50:46 +0100 Subject: [PATCH 5/8] Add notes on 2- and 3-legged token use --- code/API_definitions/quality-on-demand.yaml | 24 ++++++++++++++++----- 1 file changed, 19 insertions(+), 5 deletions(-) diff --git a/code/API_definitions/quality-on-demand.yaml b/code/API_definitions/quality-on-demand.yaml index bb4a2c4c74..d288aad98f 100644 --- a/code/API_definitions/quality-on-demand.yaml +++ b/code/API_definitions/quality-on-demand.yaml @@ -105,10 +105,11 @@ 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: @@ -274,7 +275,12 @@ paths: 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: @@ -326,6 +332,10 @@ 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: @@ -369,6 +379,10 @@ 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: From 821972e425516437de6e877965e80023a0d12b5f Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Mon, 24 Jun 2024 15:51:48 +0100 Subject: [PATCH 6/8] Add notes on 2- and 3-legged token use --- code/API_definitions/qos-profiles.yaml | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/qos-profiles.yaml b/code/API_definitions/qos-profiles.yaml index 51b3832bd2..9407de50fc 100644 --- a/code/API_definitions/qos-profiles.yaml +++ b/code/API_definitions/qos-profiles.yaml @@ -55,8 +55,10 @@ 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: @@ -106,6 +108,9 @@ 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 From 63dcebd84ea1b6f8802c61583c808ad6b8d3149a Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Mon, 24 Jun 2024 15:55:41 +0100 Subject: [PATCH 7/8] Fix trailing space --- code/API_definitions/quality-on-demand.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/quality-on-demand.yaml b/code/API_definitions/quality-on-demand.yaml index d288aad98f..e46882ff5e 100644 --- a/code/API_definitions/quality-on-demand.yaml +++ b/code/API_definitions/quality-on-demand.yaml @@ -109,7 +109,7 @@ paths: - 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. + - 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: From bf556952f3aaa934db2c4f53bd42911551e6f606 Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Mon, 24 Jun 2024 15:56:21 +0100 Subject: [PATCH 8/8] Fix trailing spaces --- code/API_definitions/qos-profiles.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/qos-profiles.yaml b/code/API_definitions/qos-profiles.yaml index 9407de50fc..9104f01f6e 100644 --- a/code/API_definitions/qos-profiles.yaml +++ b/code/API_definitions/qos-profiles.yaml @@ -56,7 +56,7 @@ paths: summary: "Get All QoS Profiles" description: | 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