diff --git a/doc/source/admintasks/kubernetes/oran-o2-application-b50a0c899e66.rst b/doc/source/admintasks/kubernetes/oran-o2-application-b50a0c899e66.rst index e56a661e9..476f8cb0b 100644 --- a/doc/source/admintasks/kubernetes/oran-o2-application-b50a0c899e66.rst +++ b/doc/source/admintasks/kubernetes/oran-o2-application-b50a0c899e66.rst @@ -77,76 +77,46 @@ You can install |O-RAN| O2 application on |prod| from the command line. #. Prepare the override ``yaml`` file. - #. Create a service account for |SMO| application. + #. Create a client on the |OAuth| server. - Create a `ServiceAccount` which can be used to provide |SMO| application with - minimal access permission credentials. + Assuming you have a 3rd-party |OAuth| 2 server, you have permission to + create a client on your |OAuth| server, and the O2 application API required + to get a token from the |OAuth| server in each requst from |SMO|. + + When you create a client, you will get a client ID and client secret. .. code-block:: bash - export SMO_SERVICEACCOUNT=smo1 + OAUTH2_TOKEN_ENDPOINT=http://<3rd-party OAuth Server Address>:8080/realms/master/protocol/openid-connect/token + OAUTH2_CLIENT_ID= + OAUTH2_CLIENT_SECRET= - cat < smo-serviceaccount.yaml - apiVersion: rbac.authorization.k8s.io/v1 - kind: Role - metadata: - namespace: default - name: pod-reader - rules: - - apiGroups: [""] # "" indicates the core API group - resources: ["pods"] - verbs: ["get", "watch", "list"] - --- - apiVersion: v1 - kind: ServiceAccount - metadata: - name: ${SMO_SERVICEACCOUNT} - namespace: default - --- - apiVersion: rbac.authorization.k8s.io/v1 - kind: RoleBinding - metadata: - name: read-pods - namespace: default - roleRef: - apiGroup: rbac.authorization.k8s.io - kind: Role - name: pod-reader - subjects: - - kind: ServiceAccount - name: ${SMO_SERVICEACCOUNT} - namespace: default - EOF + .. note:: - kubectl apply -f smo-serviceaccount.yaml + The reference to the 3rd-party |OAuth| Server (`Keycloak `__) - #. Create a secret for service account and obtain an access token. + #. Prepare the |OAuth| 2 variables to authenticate the updates. - Create a secret with the type `service-account-token` and pass the - `ServiceAccount` in the annotation section as shown below: + When using |JWT| with shared key, the following attributes need to be + configured. For example: .. code-block:: bash - export SMO_SECRET=smo1-secret + ~(keystone_admin)]$ OAUTH2_ALGORITHM=RS256 + ~(keystone_admin)]$ OAUTH2_PUB_KEY=<3rd-party OAuth Server Public Key> - cat < smo-secret.yaml - apiVersion: v1 - kind: Secret - metadata: - name: ${SMO_SECRET} - annotations: - kubernetes.io/service-account.name: ${SMO_SERVICEACCOUNT} - type: kubernetes.io/service-account-token - EOF + For token introspection, for example: - kubectl apply -f smo-secret.yaml + .. code-block:: bash - export SMO_TOKEN_DATA=$(kubectl get secrets $SMO_SECRET -o jsonpath='{.data.token}' | base64 -d -w 0) + ~(keystone_admin)]$ OAUTH2_INTROSPECTION_ENDPOINT=http://<3rd-party OAuth Server Address>:8080/realms/master/protocol/openid-connect/token/introspect + ~(keystone_admin)]$ OAUTH2_CLIENT_ID= + ~(keystone_admin)]$ OAUTH2_CLIENT_SECRET= #. Create certificates for the O2 service. - Obtain an intermediate or Root CA-signed certificate and key from a - trusted intermediate or Root Certificate Authority (CA). Refer to the + Obtain an intermediate or Root |CA|-signed certificate and key from a + trusted intermediate or Root Certificate Authority (|CA|). Refer to the documentation for the external Root |CA| that you are using on how to create a public certificate and private key pairs signed by an intermediate or Root |CA| for HTTPS. @@ -170,13 +140,33 @@ You can install |O-RAN| O2 application on |prod| from the command line. scenario above) must be shared with the |SMO| application for the O2 server certificate verification. + Prepare client certificate for |mTLS| (Mutual TLS). + + When you request the O2 application from |SMO|, it needs the certificate + for |mTLS|. + We assume you have the CA certificate and CA key of the |SMO| client. It + can be used to generate the client certificate and key. + + * |SMO| |CA| certificate - ``smo-ca-cert.pem`` + * |SMO| |CA| key - ``smo-ca-key.pem`` + * Client certificate - ``client-cert.pem`` + * Client key - ``client-key.pem`` + + The reference command to generate the client certificate is below. For example: + + .. code-block:: bash + + openssl genrsa -out client-key.pem 2048 + openssl req -new -key client-key.pem -out client.csr + openssl x509 -req -in client.csr -CA smo-ca.pem -CAkey smo-ca-key.pem -CAcreateserial -out client-cert.pem -days 365 + #. Prepare the O2 service application configuration file. As per the Cloudification and Orchestration use case defined in O-RAN Working Group 6, the following information should be generated by |SMO|: * O-Cloud Gload ID - ``OCLOUD_GLOBAL_ID`` - * SMO Register URL - ``SMO_REGISTER_URL`` + * |SMO| Register URL - ``SMO_REGISTER_URL`` See `O-RAN Cloudification and Orchestration Use Cases and Requirements for O-RAN Virtualized RAN `__. @@ -190,7 +180,6 @@ You can install |O-RAN| O2 application on |prod| from the command line. ocloud_global_id = ${OCLOUD_GLOBAL_ID} smo_register_url = ${SMO_REGISTER_URL} - smo_token_data = ${SMO_TOKEN_DATA} [OCLOUD] OS_AUTH_URL = ${OS_AUTH_URL} @@ -198,6 +187,17 @@ You can install |O-RAN| O2 application on |prod| from the command line. OS_PASSWORD = ${OS_PASSWORD} API_HOST_EXTERNAL_FLOATING = ${API_HOST_EXTERNAL_FLOATING} + [OAUTH2] + oauth2_verify_type = jwt + oauth2_public_key = ${OAUTH2_PUB_KEY} + oauth2_algorithm = ${OAUTH2_ALGORITHM} + + # required if oauth2_verify_type = introspection + #oauth2_verify_type = introspection + #oauth2_introspection_endpoint = ${OAUTH2_INTROSPECTION_ENDPOINT} + #oauth2_client_id = ${OAUTH2_CLIENT_ID} + #oauth2_client_secret = ${OAUTH2_CLIENT_SECRET} + [API] [WATCHER] diff --git a/doc/source/shared/abbrevs.txt b/doc/source/shared/abbrevs.txt index 93134fc19..589a038c9 100755 --- a/doc/source/shared/abbrevs.txt +++ b/doc/source/shared/abbrevs.txt @@ -72,6 +72,7 @@ .. |FPGA| replace:: :abbr:`FPGA (Field Programmable Gate Array)` .. |FQDN| replace:: :abbr:`FQDN (Fully Qualified Domain Name)` .. |FQDNs| replace:: :abbr:`FQDNs (Fully Qualified Domain Names)` +.. |JWT| replace:: :abbr:`JWT (JSON Web Token)` .. |GC| replace:: :abbr:`GC (Garbage Collection)` .. |GM| replace:: :abbr:`GM (Grand Master)` .. |GNP| replace:: :abbr:`GNP (Global Network Policy)` @@ -110,6 +111,7 @@ .. |MNFA| replace:: :abbr:`MNFA (Multi-Node Failure Avoidance)` .. |MOTD| replace:: :abbr:`MOTD (Message of the Day)` .. |MSR| replace:: :abbr:`MSR (Model-specific Registers)` +.. |mTLS| replace:: :abbr:`mTLS (Mutual Transport Layer Security)` .. |MTU| replace:: :abbr:`MTU (Maximum Transmission Unit)` .. |NA| replace:: :abbr:`NA (Not Applicable)` .. |NAT| replace:: :abbr:`NAT (Network Address Translation)` @@ -123,6 +125,7 @@ .. |NUMA| replace:: :abbr:`NUMA (Non-Uniform Memory Access)` .. |NVMe| replace:: :abbr:`NVMe (Non-Volatile Memory express)` .. |OAM| replace:: :abbr:`OAM (Operations, administration and management)` +.. |OAuth| replace:: :abbr:`OAuth (Open standard for authorization)` .. |OEM| replace:: :abbr:`OEM (Original Equipment Manufacturer)` .. |OC| replace:: :abbr:`OC (Ordinary Clock)` .. |OCI| replace:: :abbr:`OCI (Open Container Initiative)`