OSDOCS#12643: Docs for BYO OIDC auth provider

_topic_maps/_topic_map.yml

@@ -1324,6 +1324,8 @@ Topics:
     File: configuring-google-identity-provider
   - Name: Configuring an OpenID Connect identity provider
     File: configuring-oidc-identity-provider
+- Name: Enabling direct authentication with an OIDC identity provider
+  File: external-auth
 - Name: Using RBAC to define and apply permissions
   File: using-rbac
 - Name: Removing the kubeadmin user

authentication/external-auth.adoc

@@ -0,0 +1,27 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="external-auth"]
+= Enabling direct authentication with an external OIDC identity provider
+include::_attributes/common-attributes.adoc[]
+:context: external-auth
+
+toc::[]
+
+While the built-in OpenShift OAuth server supports integration with a variety of identity providers, including external OpenID Connect (OIDC) identity providers, it is limited to the capabilities of the OAuth server itself. You can configure {product-title} to use an external OIDC identity provider directly to issue tokens for authentication, which replaces the built-in OpenShift OAuth server.
+
+:FeatureName: Direct authentication with an OIDC identity provider
+include::snippets/technology-preview.adoc[]
+
+// About direct authentication with an external OIDC identity provider
+include::modules/external-auth-about.adoc[leveloffset=+1]
+
+// Direct authentication identity providers
+include::modules/external-auth-providers.adoc[leveloffset=+2]
+
+// Configuring an external OIDC identity provider for direct authentication
+include::modules/external-auth-configuring.adoc[leveloffset=+1]
+
+// OIDC provider configuration parameters
+include::modules/external-auth-fields.adoc[leveloffset=+2]
+
+// Disabling direct authentication
+include::modules/external-auth-disabling.adoc[leveloffset=+1]

modules/external-auth-about.adoc

@@ -0,0 +1,29 @@
+// Module included in the following assemblies:
+//
+// * authentication/external-auth.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="external-auth-about_{context}"]
+= About direct authentication with an external OIDC identity provider
+
+You can enable direct integration with an external OpenID Connect (OIDC) identity provider to issue tokens for authentication. This bypasses the built-in OAuth server and uses the external identity provider directly.
+
+By integrating directly with an external OIDC provider, you can leverage the advanced capabilities of your preferred OIDC provider instead of being limited by the capabilities of the built-in OAuth server. Your organization can manage users and groups from a single interface, while also streamlining authentication across multiple clusters and in hybrid environments. You can also integrate with existing tools and solutions.
+
+// TODO: Add back in if we test machine-to-machine workflows in the future
+// You can also facilitate machine-to-machine workflows and integrate with existing tools and solutions.
+
+[IMPORTANT]
+====
+Currently, you may configure only one OIDC provider for direct authentication.
+====
+
+After switching to direct authentication, existing authentication configuration is not guaranteed to be preserved. Prior to enabling direct authentication, back up any existing user, group, oauthclient, or identity provider configuration in case you need to revert back to using the built-in OAuth server for authentication.
+
+Before replacing the built-in OAuth server with an external provider, ensure that you have access to a long-lived method of logging in with cluster administrator permissions, such as one of the following:
+
+* a certificate-based user `kubeconfig` file, such as the one generated by the installation program
+* a long-lived service account token `kubeconfig` file
+* a certificate-based service account `kubeconfig` file
+
+If there are any issues with the external identity provider, you need one of these methods to gain access to the {product-title} cluster in an emergency situation.

modules/external-auth-configuring.adoc

@@ -0,0 +1,178 @@
+// Module included in the following assemblies:
+//
+// * authentication/external-auth.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="external-auth-configuring_{context}"]
+= Configuring an external OIDC identity provider for direct authentication
+
+You can configure {product-title} to directly use an external OIDC identity provider to issue tokens for authentication.
+
+:FeatureName: Direct authentication with an OIDC identity provider
+include::snippets/technology-preview.adoc[]
+
+.Prerequisites
+
+* You have enabled the `TechPreviewNoUpgrade` feature set.
+* You have configured your external authentication provider.
++
+This procedure uses Keycloak as the identity provider and assumes that you have the following clients configured:
+
+** A confidential client for the web console called `console-test` with the valid redirect URIs set to [x-]`https://<openshift_console_route>/auth/callback`
+
+** A public client for the {oc-first} called `oc-cli-test` with the valid redirect URIs set to [x-]`http://localhost:8080`
+
+* You have access to the `kubeconfig` file generated by the installation program for the cluster.
+* You have backed up any existing authentication configuration, in case you need to revert back to using the built-in OAuth server for authentication.
+
+.Procedure
+
+. Ensure that you are using the `kubeconfig` file generated by the installation program, or another long-lived method of logging in as a cluster administrator.
+
+. Create a secret that allows you to authenticate with the web console by running the following command:
++
+[source,terminal]
+----
+$ oc create secret generic console-secret \
+    --from-literal=clientSecret=<secret_value> \// <1>
+    -n openshift-config
+----
+<1> Replace `<secret_value>` with the value of the secret for the `console-test` client in your identity provider.
+
+. Optional: Create a config map that contains the provider's certificate authority bundle by running the following command:
++
+[source,terminal]
+----
+$ oc create configmap keycloak-oidc-ca --from-file=ca-bundle.crt=my-directory/ca-bundle.crt \// <1>
+    -n openshift-config
+----
+<1> Specify the path to your provider's `ca-bundle.crt` file.
+
+. Edit the authentication configuration by running the following command:
++
+[source,terminal]
+----
+$ oc edit authentication.config/cluster
+----
+
+. Update the authentication configuration by setting the `type` field to `OIDC`, configuring the `oidcProviders` field for your provider, and setting the `webhookTokenAuthenticator` field to `null`:
++
+[source,yaml]
+----
+apiVersion: config.openshift.io/v1
+kind: Authentication
+metadata:
+# ...
+spec:
+  oidcProviders: <1>
+  - claimMappings:
+      groups:
+        claim: groups <2>
+        prefix: 'oidc-groups-test:'
+      username:
+        claim: email <3>
+        prefixPolicy: Prefix
+        prefix:
+          prefixString: 'oidc-user-test:'
+    issuer:
+      audiences: <4>
+      - console-test
+      - oc-cli-test
+      issuerCertificateAuthority:
+        name: keycloak-oidc-ca <5>
+      issuerURL: https://keycloak-keycloak.apps.example.com/realms/master <6>
+    name: 'keycloak-oidc-server' <7>
+    oidcClients:
+    - clientID: oc-cli-test <8>
+      componentName: cli
+      componentNamespace: openshift-console
+    - clientID: console-test <9>
+      clientSecret:
+        name: console-secret <10>
+      componentName: console
+      componentNamespace: openshift-console
+  type: OIDC <11>
+  webhookTokenAuthenticator: null <12>
+----
+<1> The OIDC provider configuration. Currently, only one OIDC provider configuration is allowed.
+<2> The name of the claim to construct group names for the cluster identity.
+<3> The name of the claim to construct usernames for the cluster identity.
+<4> The list of audiences that this authentication provider issues tokens for.
+<5> The name of the config map that contains the `ca-bundle.crt` key. If unset, system trust is used instead.
+<6> The URL for the token issuer.
+<7> The name for external OIDC provider.
+<8> The client ID that your provider uses for the {oc-first}.
+<9> The client ID that your provider uses for the {product-title} web console.
+<10> The name of the secret that stores the secret value for the console client.
+<11> Must be set to `OIDC` to indicate to use an external OIDC identity provider.
+<12> Must be set to `null` when `type` is set to `OIDC`.
++
+For more details on all available parameters, see "OIDC provider configuration parameters".
+
+. Exit and save the changes to apply the new configuration.
+
+. Wait for the cluster to roll out new revisions to all nodes.
+
+.. Check the Kubernetes API server Operator status by running the following command:
++
+[source,terminal]
+----
+$ oc get co kube-apiserver
+----
++
+.Example output
+[source,terminal]
+----
+NAME             VERSION   AVAILABLE   PROGRESSING   DEGRADED   SINCE   MESSAGE
+kube-apiserver   4.19.0    True        True          False      85m     NodeInstallerProgressing: 2 node are at revision 8; 1 node is at revision 10
+----
++
+The message in the preceding example shows that one node has progressed to the new revision and two nodes have not yet updated. It can take 20 minutes or more to roll out the new revision to all nodes, depending on the size of your cluster.
+
+.. To troubleshoot any issues, you can also check the Cluster Authentication Operator and `kube-apiserver` pod logs for errors.
+
+.Verification
+
+. Verify that you can log in to the {oc-first} by authenticating with your identity provider:
+
+.. Log in by running the following command:
++
+[source,terminal]
+----
+$ oc login --exec-plugin=oc-oidc \// <1>
+    --issuer-url=https://keycloak-keycloak.apps.example.com/realms/master \// <2>
+    --client-id=oc-cli-test \// <3>
+    --extra-scopes=email --callback-port=8080 \
+    --oidc-certificate-authority my-directory/ca-bundle.crt <4>
+----
+<1> Specify `oc-oidc` as the exec plugin type. Only a value of `oc-oidc` is allowed.
+<2> Specify the issuer URL for your identity provider.
+<3> Specify client ID for the {oc-first}.
+<4> Specify the path to the `ca-bundle.crt` file on your local machine.
++
+.Example output
+[source,terminal]
+----
+Please visit the following URL in your browser: http://localhost:8080
+----
+
+.. Open http://localhost:8080 in a browser.
+
+.. Authenticate with credentials from your identity provider.
++
+After successfully authenticating, you should see a message similar to the following output in your terminal:
++
+[source,terminal]
+----
+Logged into "https://api.my-cluster.example.com:6443" as "oidc-user-test:[email protected]" from an external oidc issuer.
+----
+
+. Verify that you can log in to the {product-title} web console by authenticating with your identity provider:
+
+.. Open the web console URL for your cluster in a browser.
++
+You are redirected to your identity provider to log in.
+
+.. Authenticate with credentials from your identity provider.
++
+Verify that you logged in successfully and are redirected to the {product-title} web console.

modules/external-auth-disabling.adoc

@@ -0,0 +1,56 @@
+// Module included in the following assemblies:
+//
+// * authentication/external-auth.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="external-auth-disabling_{context}"]
+= Disabling direct authentication
+
+If necessary, you can disable direct authentication for your cluster and revert back to authenticating with the built-in OpenShift OAuth server.
+
+.Prerequisites
+
+* You have access to the `kubeconfig` file generated by the installation program for the cluster.
+
+.Procedure
+
+. Ensure that you are using the `kubeconfig` file generated by the installation program, or another long-lived method of logging in as a cluster administrator.
+
+. Update the authentication configuration to use the built-in OpenShift OAuth server by running the following command:
++
+[source,terminal]
+----
+$ oc patch authentication.config/cluster --type=merge -p='
+spec:
+  type: "" <1>
+  oidcProviders: null <2>
+'
+----
+<1> Sets `type` to `""` to use the built-in OpenShift OAuth server. A value of `IntegratedOAuth` is also equivalent.
+<2> Removes the `oidcProviders` configuration.
+
+. Wait for the cluster to roll out new revisions to all nodes.
+
+.. Check the Kubernetes API server Operator status by running the following command:
++
+[source,terminal]
+----
+$ oc get co kube-apiserver
+----
++
+.Example output
+[source,terminal]
+----
+NAME             VERSION   AVAILABLE   PROGRESSING   DEGRADED   SINCE   MESSAGE
+kube-apiserver   4.19.0    True        True          False      85m     NodeInstallerProgressing: 2 node are at revision 12; 1 node is at revision 14
+----
++
+The message in the preceding example shows that one node has progressed to the new revision and two nodes have not yet updated. It can take 20 minutes or more to roll out the new revision to all nodes, depending on the size of your cluster.
+
+.. To troubleshoot any issues, you can also check the Cluster Authentication Operator and `kube-apiserver` pod logs for errors.
+
+. If necessary, restore any existing authentication configuration.
+
+.Verification
+
+* Verify that you can successfully log in to the {product-title} web console and {oc-first}.