A1 PMS support for fine grained access control -A1 London

Documentation updates.

Issue-ID: CCSDK-3889
Signed-off-by: PatrikBuhr <patrik.buhr@est.tech>
Change-Id: Iaa73d0128a4c466ed2b3d1803af66368d3c37fa6

2 files changed, 67 insertions, 3 deletions

diff --git a/docs/offeredapis/swagger/pms-api.json b/docs/offeredapis/swagger/pms-api.json
index 9efa7b75..33fa5e18 100644
--- a/docs/offeredapis/swagger/pms-api.json
+++ b/docs/offeredapis/swagger/pms-api.json
@@ -936,7 +936,7 @@
                 "description": "OK",
                 "content": {"application/json": {"schema": {"$ref": "#/components/schemas/void"}}}
             }},
-            "tags": ["Callbacks"]
+            "tags": ["Service callbacks"]
         }},
         "/a1-policy/v2/services/{service_id}": {"delete": {
             "summary": "Unregister a service",
@@ -999,9 +999,9 @@
             "name": "Copyright (C) 2020-2023 Nordix Foundation. Licensed under the Apache License.",
             "url": "http://www.apache.org/licenses/LICENSE-2.0"
         },
-        "description": "<h2>General<\/h2><p>The O-RAN Non-RT RIC Policy Management Service provides a REST API for management of A1 policies. <br/>The main tasks of the service are:<\/p><ul><li>A1 Policy creation, modification and deletion.<\/li><li>Monitoring and maintaining consistency of the SMO view of A1 policies and the Near-RT RICs<\/li><li>Maintaining a view of supported Near-RT RIC policy types<\/li><li>Supervision of using services (R-APPs). When a service is unavailable, its policies are removed.<\/li><\/ul><h2>APIs provided by the service<\/h2><h3>A1 Policy Management<\/h3><p>This is an API for management of A1 Policies.<\/p><ul><li>A1 Policy retrieval, creation, modification and deletion.<\/li><li>Retrieval of supported A1 Policy types for a Near-RT RIC<\/li><li>Retrieval of status for existing A1 policies<\/li><\/ul><h3>Management of configuration<\/h3><p>API for updating and retrieval of the component configuration. Note that there other ways to maintain the configuration.<\/p><h3>Callbacks<\/h3><p>These are endpoints that are invoked by this service. The callbacks are registered in this service at service registration.<\/p><h3>NearRT-RIC Repository<\/h3><p>This is an API that provides support for looking up a NearRT-RIC. Each A1 policy is targeted for one Near-RT RIC.<\/p><h3>Health Check<\/h3><p>API used for supervision of the PMS component.<\/p><h3>Service Registry and Supervision<\/h3><p>API used for registering services that uses PMS. Each A1 policy is optionally owned by a service. PMS can supervise each registered service by a heart-beat supervision and will automatically remove policies for unavailable services. Note that a service does not need to be registered in order to create A1 Policies. This is a feature that is optional to use.<\/p><h3>Spring Boot Actuator<\/h3><p>Provides generic functions  used to monitor and manage the Spring web application.<\/p>",
+        "description": "<h2>General<\/h2><p>The O-RAN Non-RT RIC Policy Management Service provides a REST API for management of A1 policies. <br/>The main tasks of the service are:<\/p><ul><li>A1 Policy creation, modification and deletion.<\/li><li>Monitoring and maintaining consistency of the SMO view of A1 policies and the Near-RT RICs<\/li><li>Maintaining a view of supported Near-RT RIC policy types<\/li><li>Supervision of using services (R-APPs). When a service is unavailable, its policies are removed.<\/li><\/ul><h2>APIs provided or defined by the service<\/h2><h3>A1 Policy Management<\/h3><p>This is an API for management of A1 Policies.<\/p><ul><li>A1 Policy retrieval, creation, modification and deletion.<\/li><li>Retrieval of supported A1 Policy types for a Near-RT RIC<\/li><li>Retrieval of status for existing A1 policies<\/li><\/ul><h3>Management of configuration<\/h3><p>API for updating and retrieval of the component configuration. Note that there other ways to maintain the configuration.<\/p><h3>Service callbacks<\/h3><p>These are endpoints that are invoked by this service. The callbacks are registered in this service at service registration.<\/p><h3>NearRT-RIC Repository<\/h3><p>This is an API that provides support for looking up a NearRT-RIC. Each A1 policy is targeted for one Near-RT RIC.<\/p><h3>Health Check<\/h3><p>API used for supervision of the PMS component.<\/p><h3>Service Registry and Supervision<\/h3><p>API used for registering services that uses PMS. Each A1 policy is optionally owned by a service. PMS can supervise each registered service by a heart-beat supervision and will automatically remove policies for unavailable services. Note that a service does not need to be registered in order to create A1 Policies. This is a feature that is optional to use.<\/p><h3>Authorization API<\/h3><p>API used for access control of A1 Policy access. If configured, an external authorization provider is requested to grant access to the A1 Policy type.<\/p><h3>Spring Boot Actuator<\/h3><p>Provides generic functions  used to monitor and manage the Spring web application.<\/p>",
         "title": "A1 Policy Management Service",
-        "version": "1.1.0"
+        "version": "1.2.0"
     },
     "tags": [
         {
diff --git a/docs/offeredapis/swagger/pms-api.yaml b/docs/offeredapis/swagger/pms-api.yaml
index 0cd28d07..a905c40e 100644
--- a/docs/offeredapis/swagger/pms-api.yaml
+++ b/docs/offeredapis/swagger/pms-api.yaml
@@ -31,6 +31,10 @@ info:
 servers:
 - url: /
 tags:
+- description: "API used for authorization of information A1 policy access (this is\
+    \ provided by an authorization producer such as OPA).\nNote that this API is called\
+    \ by PMS, it is not provided.\n"
+  name: Authorization API
 - description: Monitor and interact
   externalDocs:
     description: Spring Boot Actuator Web API Documentation
@@ -93,6 +97,26 @@ paths:
       summary: Query for A1 policy instances
       tags:
       - A1 Policy Management
+  /example-authz-check:
+    post:
+      description: The authorization function decides if access is granted.
+      operationId: performAccessControl
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/policy_authorization'
+        required: true
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/authorization_result'
+          description: OK
+      summary: Request for access authorization.
+      tags:
+      - Authorization API
   /actuator/threaddump:
     get:
       operationId: threaddump
@@ -957,6 +981,17 @@ components:
           description: status text
           type: string
       type: object
+    authorization_result:
+      description: Result of authorization
+      example:
+        result: true
+      properties:
+        result:
+          description: "If true, the access is granted"
+          type: boolean
+      required:
+      - result
+      type: object
     ric_info_v2:
       description: Information for a Near-RT RIC
       example:
@@ -1113,6 +1148,35 @@ components:
             http://json-schema.org/draft-07/schema
           type: object
       type: object
+    input:
+      description: input
+      properties:
+        access_type:
+          description: Access type
+          enum:
+          - READ
+          - WRITE
+          - DELETE
+          type: string
+        auth_token:
+          description: Authorization token
+          type: string
+        policy_type_id:
+          description: Policy type identifier
+          type: string
+      required:
+      - access_type
+      - auth_token
+      - policy_type_id
+      type: object
+    policy_authorization:
+      description: Authorization request for A1 policy requests
+      properties:
+        input:
+          $ref: '#/components/schemas/input'
+      required:
+      - input
+      type: object
     policytype_id_list_v2:
       description: Information about policy types
       example: