docs/overview.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. SPDX-License-Identifier: CC-BY-4.0
   3 .. Copyright (C) 2023 Nordix
   4 .. Copyright (C) 2024 OpenInfra Foundation Europe. All rights reserved.
   5
   6 #############
   7 Overview
   8 #############
   9
  10 Service Management and Exposure has 2 components - Service Manager and  CAPIF Core . Service Manager is in the "servicemanager" directory. Capifcore is found in the "capifcore" directory.
  11
  12 This product is a part of :doc:`NONRTRIC <nonrtric:index>`.
  13
  14 ***************
  15 Service Manager
  16 ***************
  17
  18 Service Manager Overview
  19 ************************
  20
  21 Service Manager implements the R1 interface by providing a wrapper for R1 APIs that are produced and/or consumed by rApps. Service Manager also provides a wrapper for the Kong API Gateway.
  22
  23 If an rApp app needs access to a published service, it needs to go through Service Manager. It cannot access the published service directly.
  24
  25 .. image:: ./images/Service-Manager-Architecture.svg
  26    :width: 400pt
  27    :alt: High level architecture for Service Manager
  28
  29 Service Manager and the R1 API
  30 ******************************
  31
  32 CAPIF stands for Common API Framework and it was developed by 3GPP to enable a unified Northbound API framework across 3GPP network functions, and to ensure that there is a single and harmonized approach for API development. CAPIF (Common API Framework) is defined in 3GPP TS 29.222.  Among CAPIF's key features are the following.
  33
  34 * Register/deregister APIs
  35 * Publishing Service APIs
  36 * Onboarding/offboarding API invoker
  37 * Discovery APIs
  38 * CAPIF events subscription/notification
  39 * Entity authentication/authorization
  40 * Support for 3rd party domains i.e., allow 3rd party API providers to leverage the CAPIF framework
  41 * Support interconnection between two CAPIF providers
  42
  43 Service Manager wraps CAPIF to provide the following Northbound service APIs.
  44
  45 * Register/deregister APIs
  46 * Publishing Service APIs
  47 * Onboarding/offboarding API invoker
  48 * Discovery APIs
  49
  50 If you only need the above APIs, then Service Manager is a plugin-in replacement for CAPIF.
  51
  52
  53 CAPIF APIs wrapped by Service Manager
  54 *************************************
  55
  56 * **CAPIF_API_Provider_Management** API: This API enables the API Management Function to communicate with the CAPIF core function to register the API provider domain functions.
  57 * **CAPIF_Publish_Service_API** API:This API enables the API publishing function to communicate with the CAPIF core function to publish the service API information and manage the published service API information.
  58 * **CAPIF_API_Invoker_Management** API: This API enables the API invoker to communicate with the CAPIF core function to enroll as a registered user of CAPIF and manage the enrollment information.
  59 * **CAPIF_Discover_Service_API** API: This API enables the API invoker to communicate with the CAPIF core function to discover the published service API information.
  60
  61 +-----------------------------------+------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
  62 |     **Service Name**              | **Service Operations**       | **Operation Semantics**                      | **Consumer(s)**                                                                        |
  63 +-----------------------------------+------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
  64 | CAPIF_API_Provider_Management_API | Register_API_Provider        | POST /registrations                          | API Management Function                                                                |
  65 +                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
  66 |                                   | Update_API_Provider          | PUT /registrations/{registrationId}          | API Management Function                                                                |
  67 +                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
  68 |                                   | Deregister_API_Provider      | DELETE /registrations/{registrationId}       | API Management Function                                                                |
  69 +-----------------------------------+------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
  70 | CAPIF_Publish_Service_API         | Publish_Service_API          | POST /{apfId}/service-apis                   | API Publishing Function, CAPIF core function                                           |
  71 +                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
  72 |                                   | Unpublish_Service_API        | DELETE /{apfId/service-apis/{serviceApiId}   | API Publishing Function, CAPIF core function                                           |
  73 +                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
  74 |                                   | Update_Service_API           | PUT /{apfId/service-apis/{serviceApiId}      | API Publishing Function, CAPIF core function                                           |
  75 +                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
  76 |                                   | Get_Service_API              | GET /{apfId}/service-apis                    | API Publishing Function, CAPIF core function                                           |
  77 +-----------------------------------+------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
  78 | CAPIF_API_Invoker_Management_API  | Onboard_API_Invoker          | POST /onboardedInvokers                      | API Invoker                                                                            |
  79 +                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
  80 |                                   | Offboard_API_Invoker         | DELETE /onboardedInvokers/{onboardingId}     | API Invoker                                                                            |
  81 +                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
  82 |                                   | Notify_Onboarding_Completion | Subscribe/Notify                             | API Invoker                                                                            |
  83 +                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
  84 |                                   | Update_API_Invoker_Details   | PUT /onboardedInvokers/{onboardingId}        | API Invoker                                                                            |
  85 |                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
  86 |                                   | Notify_Update_Completion     | Subscribe/Notify                             | API Invoker                                                                            |
  87 +-----------------------------------+------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
  88 | CAPIF_Discover_Service_API        | Discover_Service_API         | GET /allServiceAPIs                          | API Invoker, CAPIF core function                                                       |
  89 +-----------------------------------+------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
  90
  91 Generation of OpenAPI Code
  92 **************************
  93
  94 * The R1 APIs are generated from the OpenAPI specifications provided by 3GPP.
  95 * The generate.sh script downloads the specifications from 3GPP, fixes them and then generates the northbound APIs.
  96 * The specifications are downloaded from https://www.3gpp.org/ftp/Specs/archive/29_series.
  97 * CAPIF needs the server implementation while Service Manager needs both server and client implementations. Service Manager needs the client to access CAPIF and the server to provide access to the rApps.
  98
  99 Service Manager Integration with Kong
 100 *************************************
 101
 102 * Service Manager is a Go implementation of a service that wraps both CAPIF and Kong.
 103 * When publishing a service through Service Manager, we create a Kong service and Kong route.
 104 * The JSON element that we return in the response body is updated to point to the Kong data plane. Therefore, the API interface that we return from Service Discovery has the Kong host and port, and not the original service's host and port.
 105 * The rApp can only access the Published function through Service Manager. It cannot access the Published function directly.
 106 * We use Kong as a reverse proxy. Instead of calling the Publishing service directly, our Invoker's API request is proxied through Kong. This gives us the advantages of using a proxied service, such as providing caching and load balancing.
 107 * When service invocations are routed through Kong, in an R1 SME scenario where services are selectively exposed to rApps, the Kong API gateway can be used to enforce R1 SME exposure and access.
 108 * Service exposure is achieved by restricting rApps to have access only to the Kong API gateway, and so only services exposed to the rApps through the API gateway can be accessed.
 109
 110 Service Manager Deployment
 111 **************************
 112
 113 * We have a stand-alone deployment and a deployment as part of NONRTRIC.
 114 * We use the NONRTRIC deployment from the Git repo at https://gerrit.o-ran-sc.org/r/admin/repos/it/dep.
 115 * The stand-alone deployment is in this repo at sme/servicemanager/deploy. Please see the Service Manager README.
 116 * The Service Manager configuration is stored in a config file, ``.env``.
 117 * For both the stand-alone and it/dep deployments, ``.env`` is volume-mounted into the Docker container from a Kubernetes config map at container run-time.
 118
 119 Postman
 120 *******
 121 A Postman collection has been included in this repo at sme/postman/ServiceManager.postman_collection.json.
 122
 123
 124 *************
 125 CAPIF
 126 *************
 127
 128 Introduction
 129 ************
 130
 131 CAPIF stands for Common API Framework and it was developed by 3GPP to enable a unified Northbound API framework across 3GPP network functions, and to ensure that there is a single and harmonized approach for API development.
 132
 133 Key features in CAPIF includes onboarding and offloading of application functions, service discovery and management, event subscription and notification as well as authorization and authentication.
 134
 135 It was delivered in Rel-15 (Refer to 3GPP TS 23.222 and 3GPP TS 29.222).
 136
 137 Functional entities
 138 ===================
 139
 140 The CAPIF consists of an API provider functions, the CAPIF core functions and API Invoker.
 141
 142 .. image:: ./images/architectureCAPIF.png
 143    :width: 500pt
 144    :alt: High level functional architecture for the CAPIF (3GPP TS 23.222).
 145
 146 CAPIF Core function
 147 ~~~~~~~~~~~~~~~~~~~
 148
 149 The CAPIF core functions support the API invokers to access the service APIs. It consists of the following capabilities:
 150
 151 * Authenticating the API invoker based on the identity and other information required for authentication of the API invoker;
 152 * Supporting mutual authentication with the API invoker;
 153 * Providing authorization for the API invoker prior to accessing the service API;
 154 * Publishing, storing and supporting the discovery of service APIs information;
 155 * Monitoring the service API invocations;
 156 * Onboarding a new API invoker and offboarding an API invoker;
 157 * Supports publishing, discovery of service APIs information with another CAPIF core function in CAPIF interconnection.
 158
 159 API Invoker
 160 ~~~~~~~~~~~
 161
 162 The API invoker is the entity which invokes the CAPIF or service APIs, typically provided by a 3rd party application provider.
 163
 164 The API invoker supports the following capabilities:
 165
 166 * Triggering API invoker onboarding/offboarding;
 167 * Supporting the authentication by providing the API invoker identity and other information required for authentication of the API invoker;
 168 * Supporting mutual authentication with CAPIF;
 169 * Obtaining the authorization prior to accessing the service API;
 170 * Discovering service APIs information; and
 171 * Invoking the service APIs.
 172
 173
 174 API Provider functions
 175 ~~~~~~~~~~~~~~~~~~~~~~
 176
 177 The API provider functions consists of:
 178
 179 * **API exposing function** is the provider of the service APIs and is also the service communication entry point of the service API to the API invokers. Provides access control, logging, charging, provides authentication and authorization support.
 180 * **API publishing function** is responsible for the capability to publish the service API information of the API provider to the CAPIF core functions in order to enable the discovery of APIs by the API invoker.
 181 * **API management function** is the entity which registers and maintains registration information of the API provider domain functions on the CAPIF core function.
 182
 183 CAPIF core function APIs
 184 ************************
 185
 186 * **CAPIF_Discover_Service_API** API: This API enables the API invoker to communicate with the CAPIF core function to discover the published service API information.
 187 * **CAPIF_Publish_Service_API** API: This API enables the API publishing function to communicate with the CAPIF core function to publish the service API information and manage the published service API information.
 188 * **CAPIF_Events** API: This API enables the API subscribing entity to communicate with the CAPIF core function to subscribe to and unsubscribe from CAPIF events and receive subsequent notification of CAPIF events. This API is used for the subscription to and notifications of those CAPIF events that are not bound to any of the other CAPIF core function APIs.
 189 * **CAPIF_API_Invoker_Management** API: This API enables the API invoker to communicate with the CAPIF core function to enroll as a registered user of CAPIF and manage the enrollment information.
 190 * **CAPIF_Security** API:This API enables the API invoker to communicate with the CAPIF core function to authenticate and obtain authorization to access service APIs.
 191 * **CAPIF_Monitoring** API: This API enables the API management function to communicate with the CAPIF core function to subscribe to and unsubscribe from CAPIF events related to monitoring and receive subsequent notification of CAPIF monitoring events.
 192 * **CAPIF_Logging_API_Invocation** API: This API enables the API exposing function to communicate with the CAPIF core function to log the information related to service API invocation.
 193 * **CAPIF_Auditing** API: This API enables the API management function to communicate with the CAPIF core function to retrieve the log information related to service API invocation.
 194 * **CAPIF_Access_Control_Policy** API: This API enables the API exposing function to obtain the policy to perform access control on the service API invocations.
 195 * **CAPIF_Routing_Info** API: This API enables the API exposing function to obtain the routing information to forward the API invocation to another API exposing function.
 196 * **CAPIF_API_Provider_Management** API: This API enables the API Management Function to communicate with the CAPIF core function to register the API provider domain functions as authorized users of the CAPIF functionalities.
 197
 198 The table below lists the CAPIF Core Function APIs.
 199
 200 +-----------------------------------+------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
 201 |     **Service Name**              | **Service Operations**       | **Operation Semantics**                      | **Consumer(s)**                                                                        |
 202 +-----------------------------------+------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
 203 | CAPIF_Discover_Service_API        | Discover_Service_API         | GET /allServiceAPIs                          | API Invoker, CAPIF core function                                                       |
 204 +-----------------------------------+------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
 205 | CAPIF_Publish_Service_API         | Publish_Service_API          | POST /{apfId}/service-apis                   | API Publishing Function, CAPIF core function                                           |
 206 +                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
 207 |                                   | Unpublish_Service_API        | DELETE /{apfId/service-apis/{serviceApiId}   | API Publishing Function, CAPIF core function                                           |
 208 +                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
 209 |                                   | Update_Service_API           | PUT /{apfId/service-apis/{serviceApiId}      | API Publishing Function, CAPIF core function                                           |
 210 +                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
 211 |                                   | Get_Service_API              | GET /{apfId}/service-apis                    | API Publishing Function, CAPIF core function                                           |
 212 +-----------------------------------+------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
 213 | CAPIF_Events_API                  | Subscribe_Event              | Subscribe/Notify                             | API Invoker, API Publishing Function, API Management Function, API Exposing Function   |
 214 +                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
 215 |                                   | Notify_Event                 | Subscribe/Notify                             | API Invoker, API Publishing Function, API Management Function, API Exposing Function   |
 216 +                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
 217 |                                   | Unsubscribe_Event            | Subscribe/Notify                             | API Invoker, API Publishing Function, API Management Function, API Exposing Function   |
 218 +-----------------------------------+------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
 219 | CAPIF_API_Invoker_Management_API  | Onboard_API_Invoker          | POST /onboardedInvokers                      | API Invoker                                                                            |
 220 +                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
 221 |                                   | Offboard_API_Invoker         | DELETE /onboardedInvokers/{onboardingId}     | API Invoker                                                                            |
 222 +                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
 223 |                                   | Notify_Onboarding_Completion | Subscribe/Notify                             | API Invoker                                                                            |
 224 +                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
 225 |                                   | Update_API_Invoker_Details   | PUT /onboardedInvokers/{onboardingId}        | API Invoker                                                                            |
 226 |                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
 227 |                                   | Notify_Update_Completion     | Subscribe/Notify                             | API Invoker                                                                            |
 228 +-----------------------------------+------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
 229 | CAPIF_Security_API                | Obtain_Security_Method       | PUT /trustedInvokers/{apiInvokerId}          | API Invoker                                                                            |
 230 +                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
 231 |                                   | Obtain_Authorization         | POST /securities/{securityId}/token          | API Invoker                                                                            |
 232 +                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
 233 |                                   | Obtain_API_Invoker_Info      | GET /trustedInvokers/{apiInvokerId}          | API exposing function                                                                  |
 234 +                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
 235 |                                   | Revoke_Authorization         | DELETE /trustedInvokers/{apiInvokerId}       | API exposing function                                                                  |
 236 +-----------------------------------+------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
 237 | CAPIF_API_Provider_Management_API | Register_API_Provider        | POST /registrations                          | API Management Function                                                                |
 238 +                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
 239 |                                   | Update_API_Provider          | PUT /registrations/{registrationId}          | API Management Function                                                                |
 240 +                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
 241 |                                   | Deregister_API_Provider      | DELETE /registrations/{registrationId}       | API Management Function                                                                |
 242 +-----------------------------------+------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
 243 | CAPIF_Monitoring_API              | Event operations             |                                              | API Management Function                                                                |
 244 +-----------------------------------+------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
 245 | CAPIF_Logging_API_Invocation_API  | Log_API_Invocation           | POST /{aefId}/logs                           | API exposing function                                                                  |
 246 +-----------------------------------+------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
 247 | CAPIF_Auditing_API                | Query_API_Invocation_Log     | GET /apiInvocationLogs                       | API management function                                                                |
 248 +-----------------------------------+------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
 249 | CAPIF_Access_Control_Policy_API   | Obtain_Access_Control_Policy | GET /accessControlPolicyList/{serviceApiId}  | API Exposing Function                                                                  |
 250 +-----------------------------------+------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
 251 | CAPIF_Routing_Info_API            | Obtain_Routing_Info          | GET /service-apis/{serviceApiId}             | API exposing function                                                                  |
 252 +-----------------------------------+------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
 253
 254 Security in CAPIF
 255 *****************
 256
 257 CAPIF establishes security requirements for all the interfaces defined in the specification. There are also security requirements that are applicable to all CAPIF entities, such as:
 258
 259 - CAPIF shall provide mechanisms to hide the topology of the PLMN trust domain from the API invokers accessing the service APIs from outside the PLMN trust domain.
 260 - CAPIF shall provide mechanisms to hide the topology of the 3rd party API provider trust domain from the API invokers accessing the service APIs from outside the 3rd party API provider trust domain.
 261 - CAPIF shall provide authorization mechanism for service APIs from the 3rd party API providers.
 262 - CAPIF shall support a common security mechanism for all API implementations to provide confidentiality and integrity protection.
 263
 264 The image below shows the functional security model for CAPIF architecture. CAPIF-1, CAPIF-2, CAPIF-3, CAPIF-4, CAPIF-5 and CAPIF-7 are interfaces that lie within the PLMN trust domain while the CAPIF-1e , CAPIF-2e, CAPIF-3e, CAPIF-4e, CAPIF-5e and CAPIF-7e interfaces are CAPIF core and AEF access points for API Invokers outside of the PLMN trust domain.
 265
 266 .. image:: ./images/securitymodel.png
 267    :width: 500pt
 268    :alt: CAPIF functional security model (3GPP TS 33.122).
 269
 270 Authentication and authorization are required for both API invokers that lie within the PLMN trust domain and API invokers that lie outside of the PLMN trust domain. For an API invoker that is outside of the PLMN trust domain, the CAPIF core function in coordination with the API exposing function utilizes the CAPIF-1e, CAPIF-2e and the CAPIF-3 interfaces to onboard, authenticate and authorize the API invoker prior to granting access to CAPIF services.
 271
 272 Security procedures for API invoker onboarding
 273 ==============================================
 274
 275 The API invoker and the CAPIF core function shall establish a secure session.
 276 With a secure session established, the API Invoker sends an Onboard API Invoker Request message to the CAPIF core function. The Onboard API Invoker Request message carries an onboard credential obtained during pre-provisioning of the onboard enrolment information.
 277
 278 .. image:: ./images/Onboardingnewinvoker.svg
 279    :alt: Procedure for API invoker onboarding
 280
 281 The CAPIF core function shall respond with an Onboard API invoker response message. The response shall include the CAPIF core function assigned API invoker ID, API invoker's certificate and the API invoker Onboard_Secret (generated by the CAPIF core function provided by keycloak).
 282
 283 Security method negotiation
 284 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 285
 286 The API invoker and the CAPIF core function shall negotiate a security method that shall be used by the API invoker and the API exposing function for CAPIF-2e interface authentication and protection.
 287
 288 As a pre-condition the API invoker must be onboarded with the CAPIF core function.
 289
 290 After successful mutual authentication on CAPIF-1e interface, the API invoker may send CAPIF-2/2e security capability information to the CAPIF core function in the Security Method Request message, indicating the list of security methods that it supports for each AEF.
 291
 292 The CAPIF core function shall select a security method to be used over CAPIF-2/2e reference point for each requested AEF, taking into account the information sent by the API invoker and send a Security Method Response message to the API invoker indicating the selected security method for each AEF.
 293
 294 API discovery
 295 ~~~~~~~~~~~~~
 296
 297 After successful authentication between API invoker and CAPIF core function, the CAPIF core function shall decide whether the API invoker is authorized to perform discovery based on API invoker ID and discovery policy.
 298
 299 Postman
 300 *******
 301
 302 A Postman collection has been included in this repo at sme/postman/CAPIF.postman_collection.json.