docs/service-exposure/se-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
   5 #################################
   6 Security Architecture Prototyping
   7 #################################
   8
   9 ************
  10 Introduction
  11 ************
  12 The O-RAN (Open Radio Access Network) security architecture is a framework for securing the communication between different
  13 components of an open system. It is designed to ensure the confidentiality, integrity, and availability of data and services,
  14 while also providing protection against potential security threats.
  15 This involves securing the communication between different components, including encryption, authentication, and access control.
  16 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.
  17
  18 Here are some key features provided by the platform:
  19
  20 * MTLS provides secure encrypted communication and mutual authentication of peers.
  21 * Users are authenticated using a client via the OpenID Connect (OIDC) protocol.
  22 * OAuth 2.0 is a framework that controls authorization for access of services.
  23
  24 Apps (rApps) need to use Service Management & Orchestration (SMO) services and provide services to other Apps.
  25 Apps & SMO services may be multivendor.
  26 The goal of the Security Architecture is to provide selective & controlled exposure of these services.
  27
  28 * Ensure that services cannot be accessed without a valid token.
  29 * Ensure that inter-services communication is done using mTLS.
  30 * Ensure the automated setup and configuration of security prior to app deployment.
  31
  32 This product is a part of :doc:`NONRTRIC <../index>`.
  33
  34 **********
  35 Components
  36 **********
  37
  38 ======
  39 Istio
  40 ======
  41 App security relies on Istio service mesh to enforce mTLS between applications.
  42 The applications running in the cluster are not required to implement mTLS,
  43 instead this is done by attaching an Istio sidecar to the running containers.
  44 mTLS communication is done between the sidecars.
  45
  46
  47 .. image:: ./se-service-mesh-architecture.png
  48    :width: 1000pt
  49
  50 ========
  51 Keycloak
  52 ========
  53 Keycloak is an open-source identity and access management tool.
  54 It is used to issue access tokens to the apps.
  55 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.
  56
  57  * Access tokens (JWT) are retrieved using Keycloak clients.
  58  * Access token has limited lifetime (needs to be refreshed).
  59  * Access token is sent in the HTTP header is each REST call.
  60
  61 This is an example of a JWT payload:
  62
  63 .. code-block:: javascript
  64
  65    {
  66       "exp": 1683628065,
  67       "iat": 1683627765,
  68       "jti": "b61ae49d-5a73-4e91-96f2-de3b400a5779",
  69       "iss": "https://keycloak:8443/realms/demo",
  70       "sub": "e7709f80-61bd-4440-a265-d51c4fed8ece",
  71       "typ": "Bearer",
  72       "azp": "demoprovider-cli",
  73       "session_state": "89ac7390-2865-4e07-bd1a-aea43c43827a",
  74       "scope": "email",
  75       "sid": "89ac7390-2865-4e07-bd1a-aea43c43827a",
  76       "clientHost": "127.0.0.6",
  77       "clientId": "demoprovider-cli",
  78       "email_verified": false,
  79       "clientRole": [
  80          "provider-viewer"
  81       ],
  82       "clientAddress": "127.0.0.6"
  83    }
  84
  85 .. image:: ./se-istio-authorization.png
  86    :width: 1000pt
  87
  88 ========
  89 Postgres
  90 ========
  91 Postgres is used as the back-end database for Keycloak, it will persistent the Keycloak objects that have been created.
  92
  93 ============
  94 Cert Manager
  95 ============
  96 Cert Manager is used to provide both server and client certificates for Keycloak.
  97 It also provides certificates for the webhook server.
  98
  99 ============
 100 Chart Museum
 101 ============
 102 Chart museum is used to  stores the Helm charts for the apps.
 103
 104 ==============
 105 Helm Installer
 106 ==============
 107 Helm installer is used to automate the installation of the Helm charts.
 108 Each chart contains an app configuration section in the values.yaml file which is used by Istio manager and Keycloak manager.
 109
 110 ==============
 111 Istio Manager
 112 ==============
 113 Istio manager is used to automate the setup of Gateways, Virtual Services, Authorization Policies
 114 and Request Authentication polices for the apps.
 115 The exact configuration required is read from the values.yaml file in the Helm chart.
 116
 117 ================
 118 Keycloak Manager
 119 ================
 120 Keycloak manager is used to automate the setup of realms, clients, users, role mappings and authentication flows.
 121 Keycloak provides REST API endpoints for creating and deleting these objects.
 122 The exact configuration required is read from the values.yaml file in the Helm chart.
 123
 124 ====================
 125 JWT Proxy Controller
 126 ====================
 127 The Jwt Proxy Admission Controller determines whether to attach a jwt proxy sidecar to the app container based on the app label.
 128 If permitted the exact configuration required is read from the values.yaml file in the Helm chart.
 129
 130 .. image:: ./se-jwt-proxy.png
 131    :width: 1000pt
 132
 133
 134 ************
 135 Request Flow
 136 ************
 137
 138 .. image:: ./se-request-flow.png
 139    :width: 1000pt
 140
 141 ============
 142 Provider App
 143 ============
 144 When a provider app is installed using Helm manager, all the necessary security is automatically setup prior to deployment.
 145
 146 Helm manager calls Istio manager and sets up the following Istio services:
 147  * Gateway: a load balancer operating at the edge of the mesh receiving incoming or outgoing HTTP/TCP connections.
 148  * VirtualService: routes request from the gateway to the app.
 149  * RequestAuthentication: verifies the issuer and jwksUri of the JWT.
 150  * AuthorizationPolicy: authorizes incoming requests based on claims in the JWT.
 151
 152 Helm manager calls Keycloak manager and sets up the following Keycloak objects:
 153  * Realm : represents a set of users, credentials, roles, groups and clients. Realms can be used to isolated different apps from each other.
 154  * Client: used to authenticate a user and retrieve a JWT.
 155  * Role Mapper: maps the user role(s) to the token. These role(s) are used during app authorization.
 156
 157 Clients support 4 authenticator types:
 158  #. Client Secret
 159  #. x509 certificate
 160  #. JWT signed with certificate
 161  #. JWT signed with secret
 162
 163 Depending on the app configuration it will either setup an x509 client, a jwt client or a secret client.
 164
 165 .. 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).
 166
 167 ===========
 168 Invoker App
 169 ===========
 170 When an invoker app is installed using Helm manager,
 171 the app label is used to determine whether to inject the deployment with a jwt proxy sidecar.
 172 If the app label has been whitelisted the proxy is added to the container.
 173 The jwt proxy sidecar will automatically retrieve the token required to access the app provider and include it in the request header.
 174
 175 .. image:: ./se-app-invoker-flow.png
 176    :width: 1000pt
 177
 178 This is an example of a provider and invoker running in a cluster:
 179
 180 .. image:: ./se-rapp-jwt.png
 181    :width: 1000pt
 182
 183
 184 .. note:: Security for service registry and management using the 3GPP Common API framework is available here:
 185      :doc:`Service Management & Exposure (SME) documentation site <sme:index>`.