Merge "Adjustment for OAuth2 and mTLS behavior change"

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
+      Assuming you have a 3rd-party |OAuth| 2 server, you have permission to
-      minimal access permission credentials.
+      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=<oran-o2-client-id>
+         OAUTH2_CLIENT_SECRET=<oran-o2-client-secret>
 
-          cat <<EOF > smo-serviceaccount.yaml
+      .. note::
-          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
 
-          kubectl apply -f smo-serviceaccount.yaml
+         The reference to the 3rd-party |OAuth| Server (`Keycloak <https://github.com/keycloak/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
+      When using |JWT| with shared key, the following attributes need to be
-      `ServiceAccount` in the annotation section as shown below:
+      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 <<EOF > smo-secret.yaml
+      For token introspection, for example:
-          apiVersion: v1
-          kind: Secret
-          metadata:
-            name: ${SMO_SECRET}
-            annotations:
-              kubernetes.io/service-account.name: ${SMO_SERVICEACCOUNT}
-          type: kubernetes.io/service-account-token
-          EOF
 
-          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=<oran-o2-client-id>
+          ~(keystone_admin)]$ OAUTH2_CLIENT_SECRET=<oran-o2-client-secret>
 
    #. Create certificates for the O2 service.
 
-      Obtain an intermediate or Root CA-signed certificate and key from a
+      Obtain an intermediate or Root |CA|-signed certificate and key from a
-      trusted intermediate or Root Certificate Authority (CA). Refer to the
+      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 <https://orandownloadsweb.azurewebsites.net/specifications>`__.
@@ -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]

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)`