invoker/README.md

   1 <!--
   2 -
   3 ========================LICENSE_START=================================
   4 O-RAN-SC
   5 %%
   6 Copyright (C) 2023: Nordix Foundation
   7 %%
   8 Licensed under the Apache License, Version 2.0 (the "License");
   9 you may not use this file except in compliance with the License.
  10 You may obtain a copy of the License at
  11
  12         http://www.apache.org/licenses/LICENSE-2.0
  13
  14 Unless required by applicable law or agreed to in writing, software
  15 distributed under the License is distributed on an "AS IS" BASIS,
  16 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17 See the License for the specific language governing permissions and
  18 limitations under the License.
  19 ========================LICENSE_END===================================
  20
  21 -->
  22
  23 # O-RAN-SC Non-RealTime RIC CAPIF Invoker Stub
  24
  25 This is a Go implementation of a stub for the CAPIF Invoker function, which is based on the 3GPP "29.222 Common API Framework for 3GPP Northbound APIs (CAPIF)" interfaces, see https://portal.3gpp.org/desktopmodules/Specifications/SpecificationDetails.aspx?specificationId=3450.
  26
  27 This stub offers a user interface that helps to test the functionalities implemented in the O-RAN-SC CAPIF implementation and the supported features are as follows:
  28
  29 - Onboard API Invoker
  30 - Discover published service APIs and retrieve a collection of APIs according to certain filter criteria.
  31 - Obtain Security method
  32 - Obtain Authorization
  33
  34 ### Onboard API Invoker
  35
  36 This service operation is used by an API invoker to on-board itself as a recognized user of CAPIF
  37
  38 <img src="docs/Onboarding new invoker.svg">
  39
  40 To onboard, the Invoker should send a request to the CAPIF core, including an API invoker Enrolment Details, API List and a Notification Destination URI for on-boarding notification.
  41
  42 ```
  43 {
  44     "apiInvokerInformation": "rApp as API invoker",
  45          "apiList": [
  46                 {}
  47         ],
  48     "NotificationDestination": "http://invoker-app:8086/callback",
  49     "onboardingInformation": {
  50                 "apiInvokerPublicKey": "{PUBLIC_KEY_INVOKER}",
  51                 "apiInvokerCertificate": "apiInvokerCertificate"
  52   },
  53   "requestTestNotification": true
  54 }
  55 ```
  56
  57 After receiving the request, the CAPIF core should check if the invoker can be onboarded. If the invoker is eligible for onboarding, the CAPIF core will create the API invoker Profile, which includes an API invoker Identifier, Authentication Information, Authorization Information, and CAPIF Identity Information. Keycloak is utilized in this implementation to manage identity information.
  58
  59 ### Discover published service APIs and retrieve a collection of APIs according to certain filter criteria.
  60
  61 This service operation is used by an API invoker to discover service API available at the CAPIF core function.
  62
  63 <img src="docs/Discover Service API.svg">
  64
  65 If the invoker is authorized to discover the service APIs, the CAPIF core function search the API registry for APIs matching the query criteria and return the filtered search results in the response message.
  66
  67
  68 ### Obtain Security method
  69
  70 This service operation is used by an API invoker to negotiate and obtain information about service API security method for itself with CAPIF core function.
  71
  72 <img src="docs/Obtain Security Method.svg">
  73
  74 The invoker sends a request to the CAPIF core including Security Method Request and a Notification Destination URI for security related notifications. The Security Method Request contains the unique interface details of the service APIs and may contain a preferred security method for each unique service API interface.
  75
  76 Example of SecurityService:
  77
  78 ```
  79 {
  80   "notificationDestination": "http://invoker-app:8086/callback",
  81   "supportedFeatures": "fffffff",
  82   "securityInfo": [
  83     {
  84       "aefId": "AEF_id_rApp_as_AEF",
  85       "apiId": "api_id_example",
  86       "prefSecurityMethods": [
  87         "PSK"
  88       ],
  89       "selSecurityMethod": "PSK"
  90     }
  91   ],
  92   "requestTestNotification": true
  93 }
  94 ```
  95
  96
  97 ### Obtain Authorization
  98
  99 This service operation is used by an API invoker to obtain authorization to access service APIs.
 100
 101 <img src="docs/Obtain Access Token.svg">
 102
 103 On success, "200 OK" will be returned. The payload body of the response contains the requested access token, the token type and the expiration time for the token. The access token is a JSON Web Token (JWT).
 104
 105 ## Build application
 106
 107 To build the application, run the following command:
 108
 109     go build
 110
 111 The application can also be built as a Docker image, by using the following command:
 112
 113     docker build . -t capifprov
 114
 115 ## Run
 116
 117 To run the provider from the command line, run the following commands from this folder.
 118
 119     ./capifprov [-port <port (default 9090)>] [-capifCoreUrl <URL to Capif core (default http://localhost:8090)>] [-loglevel <log level (default Info)>]