From: ychacon Date: Tue, 30 May 2023 09:31:57 +0000 (+0200) Subject: Adding documentation for invoker X-Git-Tag: 1.1.0~3 X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=commitdiff_plain;h=0c2f0bcf1141d3aa806a66be061772298a347254;p=nonrtric%2Fplt%2Fsme.git Adding documentation for invoker Issue-ID: NONRTRIC-861 Signed-off-by: ychacon Change-Id: I850787dc4032a14ac1a313bb402c31a9210d7d03 --- diff --git a/invoker/README.md b/invoker/README.md new file mode 100644 index 0000000..e8d3e68 --- /dev/null +++ b/invoker/README.md @@ -0,0 +1,119 @@ + + +# O-RAN-SC Non-RealTime RIC CAPIF Invoker Stub + +This is a Go implementation of a stub for the CAPIF Invoker function, 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. + +This stub offers an user interface that helps to test the functionalities implemented in the O-RAN-SC CAPIF implementation and the supported features are the following: + +- Onboard API Invoker +- Discover published service APIs and retrieve a collection of APIs according to certain filter criteria. +- Obtain Security method +- Obtain Authorization + +### Onboard API Invoker + +This service operation is used by an API invoker to on-board itself as a recognized user of CAPIF + + + +To onboard itself 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. + +``` +{ + "apiInvokerInformation": "rApp as API invoker", + "apiList": [ + {} + ], + "NotificationDestination": "http://invoker-app:8086/callback", + "onboardingInformation": { + "apiInvokerPublicKey": "{PUBLIC_KEY_INVOKER}", + "apiInvokerCertificate": "apiInvokerCertificate" + }, + "requestTestNotification": true +} +``` + +After receiving the request, the CAPIF core should check if the invoker can be onboard. In case it can be onboard, the CAPIF core will create the API invoker Profile consisting of an API invoker Identifier, Authentication Information, Authorization Information and CAPIF Identity Information. In this implementation, Keycloak is used to manage identity information. + +### Discover published service APIs and retrieve a collection of APIs according to certain filter criteria. + +This service operation is used by an API invoker to discover service API available at the CAPIF core function. + + + +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. + + +### Obtain Security method + +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. + + + +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. + +Example of SecurityService: + +``` +{ + "notificationDestination": "http://invoker-app:8086/callback", + "supportedFeatures": "fffffff", + "securityInfo": [ + { + "aefId": "AEF_id_rApp_as_AEF", + "apiId": "api_id_example", + "prefSecurityMethods": [ + "PSK" + ], + "selSecurityMethod": "PSK" + } + ], + "requestTestNotification": true +} +``` + + +### Obtain Authorization + +This service operation is used by an API invoker to obtain authorization to access service APIs. + + + +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). + +## Build application + +To build the application, run the following command: + + go build + +The application can also be built as a Docker image, by using the following command: + + docker build . -t capifprov + +## Run + +To run the provider from the command line, run the following commands from this folder. + + ./capifprov [-port ] [-capifCoreUrl ] [-loglevel ] diff --git a/invoker/docs/Discover Service API.svg b/invoker/docs/Discover Service API.svg new file mode 100644 index 0000000..71e35c6 --- /dev/null +++ b/invoker/docs/Discover Service API.svg @@ -0,0 +1,31 @@ +CAPIF InternalInvokerClientInvokerClientcapifcorecapifcorediscoverservicediscoverserviceinvokerserviceinvokerservicepublishservicepublishservicealt[Discover Services]Discover serviceswith apiInvokerIdand filter parametersGet services availablefor the invokerGet services availablefor the invokerGet available servicesAvailable servicesServices availablefor the invokerServices available for theinvoker matching thefilter parametersServices availablematching thefilter parameters \ No newline at end of file diff --git a/invoker/docs/Obtain Access Token.svg b/invoker/docs/Obtain Access Token.svg new file mode 100644 index 0000000..09eabbb --- /dev/null +++ b/invoker/docs/Obtain Access Token.svg @@ -0,0 +1,40 @@ +CAPIF InternalInvokerClientInvokerClientcapifcorecapifcoresecurityservicesecurityserviceinvokerserviceinvokerservicepublishservicepublishserviceprovidermanagerprovidermanagerkeycloakkeycloakalt[Security Service]Request tokenfor service withAccessTokenReqIs invoker registered?OkIs secret valid?Okalt[Check scope]Is function providingservice registered?OkIs service published?Okget tokenJWT tokenAccessTokenRspwith token \ No newline at end of file diff --git a/invoker/docs/Obtain Security Method.svg b/invoker/docs/Obtain Security Method.svg new file mode 100644 index 0000000..368bdb0 --- /dev/null +++ b/invoker/docs/Obtain Security Method.svg @@ -0,0 +1,33 @@ +CAPIF InternalInvokerClientInvokerClientcapifcorecapifcoresecurityservicesecurityserviceinvokerserviceinvokerservicepublishservicepublishservicealt[Security Service]Request security methodfor service withSecurityService RequestIs invoker registered?OkIs service published?OkDetermine the security method foreach service API interfaceCompatible security methodSecurityService Responsewith compatible security method \ No newline at end of file diff --git a/invoker/docs/Onboarding new invoker.svg b/invoker/docs/Onboarding new invoker.svg new file mode 100644 index 0000000..f7e5b13 --- /dev/null +++ b/invoker/docs/Onboarding new invoker.svg @@ -0,0 +1,41 @@ +CAPIF CoreInvokerClientInvokerClientcapifcorecapifcoreinvokerserviceinvokerservicepublishservicepublishserviceeventserviceeventservicekeycloakkeycloakalt[Onboard Invoker]Register invoker withAPIInvokerEnrolmentDetailsCreates a new API Invoker profileCreate apiInvokerIdRegister client and getonboardingSecretonboardingSecretGet available servicesAvailable servicesServices availablefor the invokerInvoker with invokerIdand available servicesalt[Subscribe to publishing events]Subscribe to eventswith EventSubscriptionCreate subscriptionIdsubscriptionId \ No newline at end of file diff --git a/invoker/docs/discoveryapi.plantuml b/invoker/docs/discoveryapi.plantuml new file mode 100644 index 0000000..8a177f8 --- /dev/null +++ b/invoker/docs/discoveryapi.plantuml @@ -0,0 +1,21 @@ +@startuml Discover Service API +actor InvokerClient +box "CAPIF Internal" +participant capifcore +participant discoverservice +participant invokerservice +participant publishservice +end box + +alt#Yellow #Yellow Discover Services + InvokerClient->capifcore: Discover services\n with apiInvokerId\n and filter parameters + capifcore->discoverservice: Get services available\n for the invoker + discoverservice->invokerservice: Get services available\n for the invoker + invokerservice->publishservice: Get available services + publishservice->invokerservice: Available services + invokerservice->discoverservice: Services available \nfor the invoker + discoverservice->capifcore: Services available for the\n invoker matching the\n filter parameters + capifcore->InvokerClient: Services available\n matching the\n filter parameters +end + +@enduml \ No newline at end of file diff --git a/invoker/docs/onboardinvoker.plantuml b/invoker/docs/onboardinvoker.plantuml new file mode 100644 index 0000000..c9f8d2a --- /dev/null +++ b/invoker/docs/onboardinvoker.plantuml @@ -0,0 +1,31 @@ +@startuml Onboarding new invoker +actor InvokerClient + +box "CAPIF Core" +participant capifcore +participant invokerservice +participant publishservice +participant eventservice +end box + +participant keycloak + + +alt#PaleGreen #PaleGreen Onboard Invoker + InvokerClient->capifcore: Register invoker with\n APIInvokerEnrolmentDetails + capifcore->invokerservice: Creates a new API Invoker profile + invokerservice->invokerservice: Create apiInvokerId + invokerservice->keycloak: Register client and get\n onboardingSecret + keycloak->invokerservice: onboardingSecret + invokerservice->publishservice: Get available services + publishservice->invokerservice: Available services + invokerservice->capifcore: Services available\n for the invoker + capifcore->InvokerClient: Invoker with invokerId\n and available services + alt#Salmon #Salmon Subscribe to publishing events + InvokerClient->eventservice: Subscribe to events\n with EventSubscription + eventservice->eventservice: Create subscriptionId + eventservice->InvokerClient: subscriptionId + end +end + +@enduml \ No newline at end of file diff --git a/invoker/docs/securitymethod.plantuml b/invoker/docs/securitymethod.plantuml new file mode 100644 index 0000000..5b6dfb5 --- /dev/null +++ b/invoker/docs/securitymethod.plantuml @@ -0,0 +1,23 @@ +@startuml Obtain Security Method +actor InvokerClient + +box "CAPIF Internal" +participant capifcore +participant securityservice +participant invokerservice +participant publishservice + +end box + +alt#Pink #Pink Security Service + InvokerClient->securityservice: Request security method\n for service with\n SecurityService Request + securityservice->invokerservice: Is invoker registered? + invokerservice->securityservice: Ok + securityservice->publishservice: Is service published? + publishservice->securityservice: Ok + securityservice->publishservice: Determine the security method for\n each service API interface + publishservice->securityservice: Compatible security method + securityservice->InvokerClient: SecurityService Response\n with compatible security method +end + +@enduml \ No newline at end of file diff --git a/invoker/docs/securityobtaintoken.plantuml b/invoker/docs/securityobtaintoken.plantuml new file mode 100644 index 0000000..0e25370 --- /dev/null +++ b/invoker/docs/securityobtaintoken.plantuml @@ -0,0 +1,30 @@ +@startuml Obtain Access Token +actor InvokerClient + +box "CAPIF Internal" +participant capifcore +participant securityservice +participant invokerservice +participant publishservice +participant providermanager +end box +participant keycloak + +alt#LightBlue #LightBlue Security Service + InvokerClient->securityservice: Request token\n for service with\n AccessTokenReq + securityservice->invokerservice: Is invoker registered? + invokerservice->securityservice: Ok + securityservice->keycloak: Is secret valid? + keycloak->securityservice: Ok + alt#Salmon #Salmon Check scope + securityservice->providermanager: Is function providing\n service registered? + providermanager->securityservice: Ok + securityservice->publishservice: Is service published? + publishservice->securityservice: Ok + end + securityservice->keycloak: get token + keycloak->securityservice: JWT token + securityservice->InvokerClient: AccessTokenRsp\n with token + end + +@enduml \ No newline at end of file