feat: Support OpenShift external IDP

antora.yml

@@ -31,8 +31,7 @@ asciidoc:
     devworkspace-id: devworkspace
     docker-cli: docker
     hosted-che-docs: xref:hosted-che:hosted-che.adoc[]
-    identity-provider-legacy-id: keycloak
-    identity-provider-legacy: Keycloak
+    keycloak: Keycloak
     image-puller-cr-name: KubernetesImagePuller
     image-puller-deployment-id: kubernetes-image-puller-operator
     image-puller-deployment-name: kubernetes-image-puller

modules/administration-guide/examples/snip_che-installing-che.adoc

@@ -12,6 +12,7 @@ You can deploy only one instance of {prod-short} per cluster.
 
 * xref:installing-che-on-openshift-using-cli.adoc[]
 * xref:installing-che-on-openshift-using-the-web-console.adoc[]
+* xref:installing-che-on-openshift-with-keycloak-as-oidc.adoc[]
 * xref:installing-che-in-a-restricted-environment.adoc[]
 * xref:installing-che-on-microsoft-azure.adoc[]
 * xref:installing-che-on-amazon-elastic-kubernetes-service.adoc[]

modules/administration-guide/nav.adoc

@@ -21,6 +21,7 @@
 ** xref:installing-che-in-the-cloud.adoc[]
 *** xref:installing-che-on-openshift-using-cli.adoc[]
 *** xref:installing-che-on-openshift-using-the-web-console.adoc[]
+*** xref:installing-che-on-openshift-with-keycloak-as-oidc.adoc[]
 *** xref:installing-che-in-a-restricted-environment.adoc[]
 *** xref:installing-che-on-microsoft-azure.adoc[]
 *** xref:installing-che-on-amazon-elastic-kubernetes-service.adoc[]

modules/administration-guide/pages/installing-che-in-the-cloud.adoc

@@ -20,6 +20,7 @@ Follow the instructions below to start the {prod-short} Server in the cloud by u
 
 * xref:installing-che-on-openshift-using-cli.adoc[]
 * xref:installing-che-on-openshift-using-the-web-console.adoc[]
+* xref:installing-che-on-openshift-with-keycloak-as-oidc.adoc[]
 * xref:installing-che-in-a-restricted-environment.adoc[]
 * xref:installing-che-on-microsoft-azure.adoc[]
 * xref:installing-che-on-amazon-elastic-kubernetes-service.adoc[]

modules/administration-guide/pages/installing-che-on-openshift-with-keycloak-as-oidc.adoc

@@ -0,0 +1,235 @@
+:_content-type: PROCEDURE
+:description: Installing {prod-short} on Red Hat OpenShift with {keycloak} as external identity provider
+:keywords: overview, installing, openshift, keycloak, oidc
+:navtitle: Installing {prod-short} on OpenShift with {keycloak} as external identity provider
+
+
+[id="installing-che-on-openshift-with-keycloak-as-oidc"]
+= Install {prod-short} on OpenShift with {keycloak} as external identity provider
+
+Install {prod-short} on an OpenShift cluster that uses {keycloak} as an external OIDC identity provider for centralized user authentication.
+
+.Prerequisites
+
+* An active `{orch-cli}` session with administrative permissions to the OpenShift cluster. See link:https://docs.openshift.com/container-platform/{ocp4-ver}/cli_reference/openshift_cli/getting-started-cli.html[Getting started with the OpenShift CLI].
+
+* {keycloak} is configured as an external identity provider for OpenShift. See link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.20/html/authentication_and_authorization/external-auth[Enabling direct authentication with an external OIDC identity provider].
+
+.Procedure
+
+. Define the environment variables:
++
+[source,shell,subs="+quotes,+attributes"]
+----
+# The {keycloak} namespace:
+KEYCLOAK_NAMESPACE=__<KEYCLOAK_NAMESPACE>__
+
+# The {keycloak} realm used for OpenShift authentication:
+OPENSHIFT_REALM=<REALM>
+
+# The {keycloak} URL
+KEYCLOAK_URL=https://$({orch-cli} get route keycloak -n $KEYCLOAK_NAMESPACE --template='{{ .spec.host }}')
+----
+
+. Create a `{prod-id}` client in the {keycloak} Admin Console:
++
+--
+.. Within the realm used for OpenShift authentication, select *Clients* on the left side of the navigation bar.
+.. Select the *Create client* button.
+.. On the *General Settings* page:
++
+... Enter `{prod-id}` in the *Client ID* field.
+... Optional: Enter a *Name* and *Description* for the OAuth client.
+... Click *Next*.
+.. On the *Capability config* page:
++
+... Toggle *Client authentication* to *On*.
+... Click *Next*.
+... Click *Save*.
+
+.. Navigate to the *Credentials* tab of the newly created client and copy the *Client secret* value for use when applying the OAuth client secret.
+--
+
+. Add the `{prod-id}` client to the audiences list in the OpenShift authentication configuration:
++
+[source,shell,subs="+quotes,+attributes"]
+----
+{orch-cli} patch authentication.config/cluster \
+  --type='json' \
+  -p='[
+    {
+      "op": "add",
+      "path": "/spec/oidcProviders/0/issuer/audiences/-",
+      "value": "{prod-id}"
+    }
+  ]'
+----
++
+[NOTE]
+====
+If you have multiple OIDC providers configured, adjust the array index in the path
+(currently 0) to match your {keycloak} provider's position in the configuration.
+====
+
+. Wait for the `kube-apiserver` cluster operator to roll out the configuration changes:
++
+[source,shell,subs="+quotes,+attributes"]
+----
+watch {orch-cli} get co kube-apiserver
+----
+
+. Create a {orch-namespace} for {prod-short}:
++
+[source,bash,subs="+quotes,+attributes"]
+----
+{orch-cli} create {orch-namespace} {prod-namespace}
+----
+
+. Create a secret for the OAuth client in the {prod-short} namespace:
++
+[source,yaml,subs="+quotes,+attributes"]
+----
+{orch-cli} apply -f - <<EOF
+apiVersion: v1
+kind: Secret
+metadata:
+  name: oauth-secret
+  namespace: {prod-namespace}
+  labels:
+    app.kubernetes.io/part-of: che.eclipse.org
+stringData:
+  oAuthSecret: __<CLIENT_SECRET>__ <1>
+EOF
+----
+<1> The client secret value from the `{prod-id}` client in {keycloak}.
+
+
+. Optional: Create the `ConfigMap` with a {keycloak} certificate in the `{prod-namespace}` namespace. If {keycloak} uses a certificate that is already trusted by OpenShift, skip this step.
++
+[source,shell,subs="+attributes"]
+----
+openssl s_client \
+  -connect "$(echo "$KEYCLOAK_URL" | sed 's|https://||'):443" \
+  -showcerts < /dev/null \
+| sed -n '/-----BEGIN CERTIFICATE-----/,/-----END CERTIFICATE-----/p' \
+> keycloak-ca.crt
+
+{orch-cli} create configmap keycloak-certs \
+    --from-file=keycloak-ca.crt=keycloak-ca.crt \
+    -n {prod-namespace} && \
+{orch-cli} label configmap keycloak-certs \
+    app.kubernetes.io/part-of=che.eclipse.org \
+    app.kubernetes.io/component=ca-bundle \
+    -n {prod-namespace}
+----
+
+. Prepare the `CheCluster` patch:
++
+[source,shell,subs="+attributes"]
+----
+cat > che-patch.yaml << EOF
+kind: CheCluster
+apiVersion: org.eclipse.che/v2
+spec:
+  networking:
+    auth:
+      oAuthClientName: {prod-id}
+      oAuthSecret: oauth-secret
+      identityProviderURL: "$KEYCLOAK_URL/realms/$OPENSHIFT_REALM"
+      gateway:
+        oAuthProxy:
+          cookieExpireSeconds: 300
+        deployment:
+          containers:
+            - name: oauth-proxy
+              env:
+                - name: OAUTH2_PROXY_CODE_CHALLENGE_METHOD
+                  value: S256
+                - name: OAUTH2_PROXY_BACKEND_LOGOUT_URL
+                  value: "$KEYCLOAK_URL/realms/$OPENSHIFT_REALM/protocol/openid-connect/logout?id_token_hint=\{id_token}"
+  components:
+    cheServer:
+      extraProperties:
+        CHE_OIDC_GROUPS__CLAIM: '<GROUPS_CLAIM>' <1>
+        CHE_OIDC_GROUPS__PREFIX: '<GROUPS_PREFIX>' <2>
+        CHE_OIDC_USERNAME__CLAIM: '<USERNAME_CLAIM>' <3>
+        CHE_OIDC_USERNAME__PREFIX: '<USERNAME_PREFIX>' <4>
+EOF
+----
+<1> The claim to use for extracting user groups.
+<2> The prefix to add to group names. Empty string means no prefix.
+<3> The claim to use for extracting the username.
+<4> The prefix to add to usernames from the external authentication system.
++
+[NOTE]
+====
+These values must match the corresponding claim and prefix settings configured in the `authentication.config/cluster` resource. To view the current cluster configuration, run:
+
+[source,shell,subs="+attributes"]
+----
+{orch-cli} get authentication.config/cluster -o yaml
+----
+====
++
+. Create the {prod-short} instance with `{prod-cli}`:
++
+[source,shell,subs="+attributes"]
+----
+{prod-cli} server:deploy \
+  --platform openshift \
+  --che-operator-cr-patch-yaml che-patch.yaml
+----
+
+. Update a `{prod-id}` client to set {prod-short} callback URL:
++
+--
+.. Open the {keycloak} Admin Console.
+.. Within the realm used for OpenShift authentication, click the `{prod-id}` client.
+... In the *Valid redirect URIs* field, enter the redirect URI for your {prod-short} installation. To obtain the redirect URI, run the following command:
++
+[source,shell,subs="+quotes,+attributes"]
+----
+echo "$({orch-cli} get checluster {prod-checluster} -n {prod-namespace} -o jsonpath='{.status.cheURL}')/oauth/callback"
+----
+... Click *Save*.
+--
+
+. Create a `ClusterRoleBinding` to grant users access to {prod-short}:
++
+[source,shell,subs="+quotes,+attributes"]
+----
+{orch-cli} apply -f - <<EOF
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: openshift-developers
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: self-provisioner <1>
+subjects:
+- apiGroup: rbac.authorization.k8s.io
+  kind: Group
+  name: __<GROUP_NAME>__ <2>
+EOF
+----
+<1> Users must have at least the `self-provisioner` role to access {prod-short}.
+<2> The name of the user group from {keycloak} that should be granted access to {prod-short}.
+
+.Verification
+
+. Verify the {prod-short} instance status:
++
+[source,shell,subs="+attributes"]
+----
+{prod-cli} server:status
+----
+
+. Navigate to the {prod-short} cluster instance:
++
+[source,shell,subs="+attributes"]
+----
+{prod-cli} dashboard:open
+----
+
+. Log in to the {prod-short} instance.