From bcfff644b2e606ec9131c4049d5045f1d1f0c414 Mon Sep 17 00:00:00 2001 From: Mohd Farhan Date: Sat, 28 Mar 2026 17:41:46 +0400 Subject: [PATCH] fix: add missing security schemes to session-insights API Add OpenID Connect security schemes and per-operation scopes as required by CAMARA Commonalities r3.2. Include the mandatory ICM authorization template in info.description. Resolves #69 --- code/API_definitions/session-insights.yaml | 30 ++++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/session-insights.yaml b/code/API_definitions/session-insights.yaml index 25a1f2b..6f682a5 100644 --- a/code/API_definitions/session-insights.yaml +++ b/code/API_definitions/session-insights.yaml @@ -38,7 +38,13 @@ info: # Authorization and Authentication - ## Identifying the [ device | phone number ](*) from the access token + The "Camara Security and Interoperability Profile" provides details of how an API consumer requests an access token. Please refer to Identity and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the profile. + + The specific authorization flows to be used will be agreed upon during the onboarding process, happening between the API consumer and the API provider, taking into account the declared purpose for accessing the API, whilst also being subject to the prevailing legal framework dictated by local legislation. + + In cases where personal 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 three-legged access tokens is mandatory. This ensures that the API remains in compliance with privacy regulations, upholding the principles of transparency and user-centric privacy-by-design. + + ## Identifying the device from the access token This API requires the API consumer to identify a device as the subject of the API as follows: - When the API is invoked using a two-legged access token, the subject will be identified from the optional `device` object, which therefore MUST be provided. @@ -50,7 +56,7 @@ info: - If the subject cannot be identified from the access token and the optional `device` object is not included in the request, then the server will return an error with the `422 MISSING_IDENTIFIER` error code. - - If the subject can be identified from the access token and the optional `device` is also included in the request, then the server will return an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will be the case even if the same [ device | phone number ](*) is identified by these two methods, as the server is unable to make this comparison. + - If the subject can be identified from the access token and the optional `device` is also included in the request, then the server will return an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will be the case even if the same device is identified by these two methods, as the server is unable to make this comparison. # Additional CAMARA error responses @@ -98,6 +104,9 @@ paths: The operator allocates a sink (HTTP webhook or MQTT topic) for the application to send metrics and receive notifications. operationId: createSession + security: + - openId: + - session-insights:sessions:create parameters: - $ref: "#/components/parameters/x-correlator" requestBody: @@ -140,6 +149,9 @@ paths: Retrieve the details of a specific session by its operator-assigned session ID. operationId: getSession + security: + - openId: + - session-insights:sessions:read parameters: - name: sessionId in: path @@ -175,6 +187,9 @@ paths: Delete a session by its operator-assigned session ID. This will stop all notifications and metrics streaming for the session. operationId: deleteSession + security: + - openId: + - session-insights:sessions:delete parameters: - name: sessionId in: path @@ -212,6 +227,9 @@ paths: - The request must include a `device` object if using a two-legged token. If using a three-legged token, do not provide a `device` as the device is derived from the token. operationId: retrieveSessionsByDevice + security: + - openId: + - session-insights:sessions:retrieve-by-device parameters: - $ref: "#/components/parameters/x-correlator" requestBody: @@ -255,6 +273,9 @@ paths: evaluate session quality and trigger notifications if thresholds are breached. operationId: sendSessionMetrics + security: + - openId: + - session-insights:sessions:send-metrics parameters: - name: sessionId in: path @@ -303,6 +324,11 @@ components: schema: $ref: "#/components/schemas/XCorrelator" + securitySchemes: + openId: + type: openIdConnect + openIdConnectUrl: https://example.com/.well-known/openid-configuration + schemas: XCorrelator: type: string