Update OpenAPI security guidelines.md

documentation/API-design-guidelines.md

@@ -43,7 +43,7 @@ This document captures guidelines for the API design in CAMARA project. These gu
     - [11.3 Request Parameters](#113-request-parameters)
     - [11.4 Response Structure](#114-response-structure)
     - [11.5 Data Definitions](#115-data-definitions)
-    - [11.6 OAuth Definition](#116-oauth-definition)
+    - [11.6 Security Definition](#116-security-definition)
   - [12. Subscription, Notification \& Event](#12-subscription-notification--event)
     - [12.1 Subscription](#121-subscription)
     - [12.2 Event notification](#122-event-notification)
@@ -862,28 +862,14 @@ The scopes allow defining the permission scopes that a system or a user has on a
 Scopes should be represented as:
 - API Name: address-management, numbering-information...
 - Protected Resource: orders, billings…
-- Grant-level: read, write…
+- Grant-level, action on resource: read, write…
 
 To correctly define the scopes, when creating them, the following recommendations should be taken:
 - **Appropriate granularity**. Scopes should be granular enough to match the types of resources and permissions you want to grant.
 - **Use a common nomenclature for all resources**.  Scopes must be descriptive names and that there is no conflict between the different resources.
 - **Use the kebab-case nomenclature** to define API names, resources, and scope permissions.
-- **Recommended Format**: `<API_name>-<Resource>-<Permission>`
 
-Next, we illustrate an example on how to define series of scopes for a OpenAPI file.
-
-The first step is to create the security definitions according to the nomenclature that we have defined.
-<p align="center">
-<img src="./images/guidelines-fig-11.png" width="400"/>
-</p>
-
-Then, each operation is assigned the necessary scope:
-<p align="center">
-<img src="./images/guidelines-fig-12.png" width="400"/>
-</p>
-<p align="center">
-<img src="./images/guidelines-fig-13.png" width="400"/>
-</p>
+See section [11.6 Security Definition](#116-security-definition) for detailed guidelines on how to define scopes and other security-related properties in a OpenAPI file.
 
 
 <font size="3"><span style="color: blue"> Data security </span></font>
@@ -933,7 +919,6 @@ The API must validate the signature of the JWT in the payload following next req
   - Making sure that the JWT payload has the same structure and values as the decrypted part of "`JWT_Signature`".
 
 
-
 ## 11. Definition in OpenAPI
 
 API documentation helps customers integrate with the API by explaining what it is and how to use it. All APIs must include documentation for the developer who will consume your API.
@@ -1116,17 +1101,73 @@ When IpAddr is used in a payload the property objectType MUST be present to indi
 }
 ```
 
-### 11.6 OAuth Definition
+### 11.6 Security definition
+
+Finally, this part describes the security is applied to the API. 
+
+#### 11.6.1 Scope naming
+
+* Define a scope per API operation with the structure:
+
+`api-name:[resource:]action`
+
+where
+
+* `api-name` is the API name specified as the base path, prior to the API version, in the `servers[*].url` property. For example, from `/location-verification/v0`, it would be `location-verification`.
+
+* `resource` is optional. For APIs with several `paths`, it may include the resource in the path. For example, from `/qod/v0/sessions/{sessionId}`, it would be `sessions`.
 
-Finally, this part describes the OAuth security applied to the API. This spec is for client testing purposes only, but
-there should be as similar as possible to the OAuth flows in your production environment. This definition has the
-following aspects:
+* `action`: There are two cases:
+  - For POST operations with a verb, it will be the verb. For example, from `POST /location-verification/v0/verify`, it would be `verify`.
+    - For endpoints designed as POST but with underlying logic retrieving information, a CRUD action `read` may be added, but if it is a path with single operation and it is not expected to have more operations on it, the CRUD action is not necessary.
+  - For CRUD operations on a resource in paths, it will be one of:
+    - `create`: For operations creating the resource, typically `POST`.
+    - `read`: For operations accessing to details of the resource, typically `GET`.
+    - `update`: For operations modifying the resource, typically `PUT` or `PATCH`.
+    - `delete`: For operations removing the resource, typically `DELETE`.
+    - `write` : For operations creating or modifying the resource, when differentiation between `create` and `update` is not needed.
+
+* Eventually we may need to add an additional level to the scope, such as `api-name:[resource:]action[:detail]`, to deal with cases when only a set of parameters/information has to be allowed to be returned. Guidelines should be enhanced when those cases happen.
+
+##### Examples
+
+| API | path | method | scope |
+| --- | --- | --- | --- |
+| location-verification | /verify | POST | `location-verification:verify` |
+| qod | /sessions | POST | `qod:sessions:create`, or<br>`qod:sessions:write` |
+| qod | /qos-profiles | GET | `qod:qos-profiles:read` |
+
+
+#### 11.6.2 Use of openIdConnect for `securitySchemes`
+
+Generally, OpenID Connect is the protocol to be used for securitization. Each API spec will define the following entry in `securitySchemes`, as shown in [CAMARA-AuthN-AuthZ-Concept.md](https://github.com/camaraproject/IdentityAndConsentManagement/tree/main/documentation/CAMARA-AuthN-AuthZ-Concept.md) document:
+
+```
+components:
+  securitySchemes:
+    openId:
+      type: openIdConnect
+      openIdConnectUrl: https://example.com/.well-known/openid-configuration
+```
+
+The value for `openIdConnectUrl` in the CAMARA spec is an example, that must be substituted by the specific discovery endpoint for OIDC protocol of the API provider, when the API is exposed in one of its environments.
+
+#### 11.6.3 Use of `security` property
+
+Generally, each operation will be protected by a scope and it will include a `security` property with a single element in the array:
+
+```
+paths:
+  {path}:
+    {method}:
+      ...
+      security:
+        - openId:
+            - {scope}
+```
 
-- Security Type: oauth2, oauth…
-- Security Flow (Depends of security type): implicit, password…
-- Security Flow description applied (String)
-- Endpoint token URL
-- URL to endpoint authorization ( If flow is based on "`authorizationCode`").	
+The key is arbitrary in OAS, but convention in CAMARA is to name it `openId`. This key must be same defined in the `components.securitySchemes` section.
+The {scope} is the specific scope defined to protect this operation. It must follow the syntax specified above.
 
 ## 12. Subscription, Notification & Event