From: ktimoney Date: Wed, 10 May 2023 14:02:51 +0000 (+0100) Subject: Document security architecture X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=commitdiff_plain;h=900ceda884f7cd92be20bfb1fb3a424073dc4316;p=nonrtric.git Document security architecture Issue-ID: NONRTRIC-869 Change-Id: I871b6cbaa8f971a9bc366bfbc10c202e7426d981 Signed-off-by: ktimoney --- diff --git a/docs/index.rst b/docs/index.rst index d3ad7f65..ca977702 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -16,3 +16,4 @@ Non-RT RIC ./requirements.rst ./installation-guide.rst ./release-notes.rst + ./service-exposure/se-overview.rst diff --git a/docs/overview.rst b/docs/overview.rst index 0aebe30e..4a2701c1 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -160,18 +160,14 @@ Implementation: - Repo: *portal/nonrtric-controlpanel*. -Non-RT-RIC (Kong) Service Exposure Prototyping -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Non-RT-RIC Service Exposure Security Architecture Prototyping +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Support Apps to use NONRTRIC, SMO and other App interfaces. A building block for coming releases as the R1 Interface concept matures . - Support dynamic registration and exposure of service interfaces to Non-RT-RIC applications (& NONRTRIC Control panel). -- Extends a static gateway function specifically for NONRTRIC Control panel (described above). -- Initial version based on `Kong API Gateway `_ function. -- Initial exposure candidates include A1 (NONRTRIC) services & O1 (OAM/SMO) services. - -NONRTRIC Kubernetes deployment - including Kong configurations can be found in the OSC `it/dep `_ Gerrit repo. +- The architecture and componets are defined in :doc:`Non-RT RIC Security Architecture Prototyping (Documentation site) `. DMaaP/Kafka Information Producer Adapters ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/service-exposure/se-app-invoker-flow.png b/docs/service-exposure/se-app-invoker-flow.png new file mode 100644 index 00000000..e0eb966b Binary files /dev/null and b/docs/service-exposure/se-app-invoker-flow.png differ diff --git a/docs/service-exposure/se-istio-authorization.png b/docs/service-exposure/se-istio-authorization.png new file mode 100644 index 00000000..94e1686b Binary files /dev/null and b/docs/service-exposure/se-istio-authorization.png differ diff --git a/docs/service-exposure/se-jwt-proxy.png b/docs/service-exposure/se-jwt-proxy.png new file mode 100644 index 00000000..d27b123e Binary files /dev/null and b/docs/service-exposure/se-jwt-proxy.png differ diff --git a/docs/service-exposure/se-overview.rst b/docs/service-exposure/se-overview.rst new file mode 100644 index 00000000..8b6d89bc --- /dev/null +++ b/docs/service-exposure/se-overview.rst @@ -0,0 +1,181 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (C) 2023 Nordix + +################################# +Security Architecture Prototyping +################################# + +************ +Introduction +************ +The O-RAN (Open Radio Access Network) security architecture is a framework for securing the communication between different +components of an open system. It is designed to ensure the confidentiality, integrity, and availability of data and services, +while also providing protection against potential security threats. +This involves securing the communication between different components, including encryption, authentication, and access control. +The O-RAN security architecture is designed to be flexible, scalable, and interoperable, enabling different vendors to integrate their solutions into the O-RAN ecosystem while maintaining security. + +Here are some key features provided by the platform: + +* MTLS provides secure encrypted communication and mutual authentication of peers. +* Users are authenticated using a client via the OpenID Connect (OIDC) protocol. +* OAuth 2.0 is a framework that controls authorization for access of services. + +Apps (rApps) need to use Service Management & Orchestration (SMO) services and provide services to other Apps. +Apps & SMO services may be multivendor. +The goal of the Security Architecture is to provide selective & controlled exposure of these services. + +* Ensure that services cannot be accessed without a valid token. +* Ensure that inter-services communication is done using mTLS. +* Ensure the automated setup and configuration of security prior to app deployment. + +This product is a part of :doc:`NONRTRIC <../index>`. + +********** +Components +********** + +====== +Istio +====== +App security relies on Istio service mesh to enforce mTLS between applications. +The applications running in the cluster are not required to implement mTLS, +instead this is done by attaching an Istio sidecar to the running containers. +mTLS communication is done between the sidecars. + + +.. image:: ./se-service-mesh-architecture.png + :width: 1000pt + +======== +Keycloak +======== +Keycloak is an open-source identity and access management tool. +It is used to issue access tokens to the apps. +The access token comes in the form of a JWT which includes claims or fields which are used to determine the access level to grant to a particular app. + + * Access tokens (JWT) are retrieved using Keycloak clients. + * Access token has limited lifetime (needs to be refreshed). + * Access token is sent in the HTTP header is each REST call. + +This is an example of a JWT payload: + +.. code-block:: javascript + + { + "exp": 1683628065, + "iat": 1683627765, + "jti": "b61ae49d-5a73-4e91-96f2-de3b400a5779", + "iss": "https://keycloak:8443/realms/demo", + "sub": "e7709f80-61bd-4440-a265-d51c4fed8ece", + "typ": "Bearer", + "azp": "demoprovider-cli", + "session_state": "89ac7390-2865-4e07-bd1a-aea43c43827a", + "scope": "email", + "sid": "89ac7390-2865-4e07-bd1a-aea43c43827a", + "clientHost": "127.0.0.6", + "clientId": "demoprovider-cli", + "email_verified": false, + "clientRole": [ + "provider-viewer" + ], + "clientAddress": "127.0.0.6" + } + +.. image:: ./se-istio-authorization.png + :width: 1000pt + +======== +Postgres +======== +Postgres is used as the back-end database for Keycloak, it will persistent the Keycloak objects that have been created. + +============ +Cert Manager +============ +Cert Manager is used to provide both server and client certificates for Keycloak. +It also provides certificates for the webhook server. + +============ +Chart Museum +============ +Chart museum is used to stores the Helm charts for the apps. + +============== +Helm Installer +============== +Helm installer is used to automate the installation of the Helm charts. +Each chart contains an app configuration section in the values.yaml file which is used by Istio manager and Keycloak manager. + +============== +Istio Manager +============== +Istio manager is used to automate the setup of Gateways, Virtual Services, Authorization Policies +and Request Authentication polices for the apps. +The exact configuration required is read from the values.yaml file in the Helm chart. + +================ +Keycloak Manager +================ +Keycloak manager is used to automate the setup of realms, clients, users, role mappings and authentication flows. +Keycloak provides REST API endpoints for creating and deleting these objects. +The exact configuration required is read from the values.yaml file in the Helm chart. + +==================== +JWT Proxy Controller +==================== +The Jwt Proxy Admission Controller determines whether to attach a jwt proxy sidecar to the app container based on the app label. +If permitted the exact configuration required is read from the values.yaml file in the Helm chart. + +.. image:: ./se-jwt-proxy.png + :width: 1000pt + + +************ +Request Flow +************ + +.. image:: ./se-request-flow.png + :width: 1000pt + +============ +Provider App +============ +When a provider app is installed using Helm manager, all the necessary security is automatically setup prior to deployment. + +Helm manager calls Istio manager and sets up the following Istio services: + * Gateway: a load balancer operating at the edge of the mesh receiving incoming or outgoing HTTP/TCP connections. + * VirtualService: routes request from the gateway to the app. + * RequestAuthentication: verifies the issuer and jwksUri of the JWT. + * AuthorizationPolicy: authorizes incoming requests based on claims in the JWT. + +Helm manager calls Keycloak manager and sets up the following Keycloak objects: + * Realm : represents a set of users, credentials, roles, groups and clients. Realms can be used to isolated different apps from each other. + * Client: used to authenticate a user and retrieve a JWT. + * Role Mapper: maps the user role(s) to the token. These role(s) are used during app authorization. + +Clients support 4 authenticator types: + #. Client Secret + #. x509 certificate + #. JWT signed with certificate + #. JWT signed with secret + +Depending on the app configuration it will either setup an x509 client, a jwt client or a secret client. + +.. note:: If the app is configured to use the x509 authenticator, a direct flow grant for x509 is also setup to check fields in x509 certificate against some pre-defined value(s). + +=========== +Invoker App +=========== +When an invoker app is installed using Helm manager, +the app label is used to determine whether to inject the deployment with a jwt proxy sidecar. +If the app label has been whitelisted the proxy is added to the container. +The jwt proxy sidecar will automatically retrieve the token required to access the app provider and include it in the request header. + +.. image:: ./se-app-invoker-flow.png + :width: 1000pt + +This is an example of a provider and invoker running in a cluster: + +.. image:: ./se-rapp-jwt.png + :width: 1000pt diff --git a/docs/service-exposure/se-rapp-jwt.png b/docs/service-exposure/se-rapp-jwt.png new file mode 100644 index 00000000..ead820f5 Binary files /dev/null and b/docs/service-exposure/se-rapp-jwt.png differ diff --git a/docs/service-exposure/se-request-flow.png b/docs/service-exposure/se-request-flow.png new file mode 100644 index 00000000..3d8331e8 Binary files /dev/null and b/docs/service-exposure/se-request-flow.png differ diff --git a/docs/service-exposure/se-service-mesh-architecture.png b/docs/service-exposure/se-service-mesh-architecture.png new file mode 100644 index 00000000..9c45722b Binary files /dev/null and b/docs/service-exposure/se-service-mesh-architecture.png differ