From e246b0fa9e32b68db3052a6a4c600b729cf41416 Mon Sep 17 00:00:00 2001 From: Anatolii Bazko Date: Wed, 4 Feb 2026 13:03:28 +0100 Subject: [PATCH 1/2] feat: Support OpenShift external IDP Signed-off-by: Anatolii Bazko --- antora.yml | 3 +- .../examples/snip_che-installing-che.adoc | 1 + modules/administration-guide/nav.adoc | 1 + .../pages/installing-che-in-the-cloud.adoc | 1 + ...he-on-openshift-with-keycloak-as-oidc.adoc | 236 ++++++++++++++++++ 5 files changed, 240 insertions(+), 2 deletions(-) create mode 100644 modules/administration-guide/pages/installing-che-on-openshift-with-keycloak-as-oidc.adoc diff --git a/antora.yml b/antora.yml index 6e8ba31e47..a027f2b97a 100644 --- a/antora.yml +++ b/antora.yml @@ -30,8 +30,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 diff --git a/modules/administration-guide/examples/snip_che-installing-che.adoc b/modules/administration-guide/examples/snip_che-installing-che.adoc index 8228f6048d..85aba42271 100644 --- a/modules/administration-guide/examples/snip_che-installing-che.adoc +++ b/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[] diff --git a/modules/administration-guide/nav.adoc b/modules/administration-guide/nav.adoc index 8ba444790d..588b18ca21 100644 --- a/modules/administration-guide/nav.adoc +++ b/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[] diff --git a/modules/administration-guide/pages/installing-che-in-the-cloud.adoc b/modules/administration-guide/pages/installing-che-in-the-cloud.adoc index 7f934307fd..ac922b6f8a 100644 --- a/modules/administration-guide/pages/installing-che-in-the-cloud.adoc +++ b/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[] diff --git a/modules/administration-guide/pages/installing-che-on-openshift-with-keycloak-as-oidc.adoc b/modules/administration-guide/pages/installing-che-on-openshift-with-keycloak-as-oidc.adoc new file mode 100644 index 0000000000..5ac8735159 --- /dev/null +++ b/modules/administration-guide/pages/installing-che-on-openshift-with-keycloak-as-oidc.adoc @@ -0,0 +1,236 @@ +:_content-type: PROCEDURE +:description: Installing {prod-short} on 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"] += Installing {prod-short} on OpenShift with {keycloak} as external identity provider + +You can Install {prod-short} on OpenShift when Keycloak is configured as an external identity provider for the cluster. + +.Prerequisites + +* An active `oc` 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/latest/html/authentication_and_authorization/external-auth[Enabling direct authentication with an external OIDC identity provider]. + +.Procedure + +. Define the namespace where {keycloak} is installed: ++ +[source,shell] +---- +KEYCLOAK_NAMESPACE= +---- + +. Define the {keycloak} realm used for OpenShift authentication: ++ +[source,shell] +---- +OPENSHIFT_REALM= +---- + +. Define the {keycloak} URL: ++ +[source,shell] +---- +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-hand navigation bar. +.. Select the *Create client* button. +.. On the *General Settings* page: ++ +... Enter `eclipse-che` in the *Client ID* field. +... Optionally 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. You will need this value in a later step. +-- + +. 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}: ++ +[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 - <__ <1> +EOF +---- +<1> The client secret value from the `eclipse-che` client in Keycloak. + + +. Create the `ConfigMap` with a {keycloak} certificate in the `{prod-namespace}` namespace. +If {keycloak} uses a certificate that is already trusted by OpenShift, this step may be omitted. ++ +[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: {prod-id}-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: '' <1> + CHE_OIDC_GROUPS__PREFIX: '' <2> + CHE_OIDC_USERNAME__CLAIM: '' <3> + CHE_OIDC_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 {keycloak} Admin Console +.. Within the realm used for OpenShift authentication, click on `{prod-id}` client +... In the *Valid redirect URIs* field, enter the redirect URIs for your {prod-short} installation. +Can be obtained with 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 - < +subjects: +- apiGroup: rbac.authorization.k8s.io + kind: 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 steps + +. 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. From 12e519b0d9d8ca12b406966b98e8405e1004d319 Mon Sep 17 00:00:00 2001 From: Anatolii Bazko Date: Mon, 9 Feb 2026 15:53:24 +0100 Subject: [PATCH 2/2] fixup Signed-off-by: Anatolii Bazko --- ...he-on-openshift-with-keycloak-as-oidc.adoc | 26 ++++++++++++------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/modules/administration-guide/pages/installing-che-on-openshift-with-keycloak-as-oidc.adoc b/modules/administration-guide/pages/installing-che-on-openshift-with-keycloak-as-oidc.adoc index 5ac8735159..cd705470a1 100644 --- a/modules/administration-guide/pages/installing-che-on-openshift-with-keycloak-as-oidc.adoc +++ b/modules/administration-guide/pages/installing-che-on-openshift-with-keycloak-as-oidc.adoc @@ -33,7 +33,7 @@ OPENSHIFT_REALM= . Define the {keycloak} URL: + -[source,shell] +[source,shell,subs="+quotes,+attributes"] ---- KEYCLOAK_URL=https://$({orch-cli} get route keycloak -n $KEYCLOAK_NAMESPACE --template='{{ .spec.host }}') ---- @@ -41,11 +41,11 @@ KEYCLOAK_URL=https://$({orch-cli} get route keycloak -n $KEYCLOAK_NAMESPACE --te . Create a `{prod-id}` client in the {keycloak} Admin Console: + -- -.. Within the realm used for OpenShift authentication, select *Clients* on the left-hand navigation bar. +.. 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 `eclipse-che` in the *Client ID* field. +... Enter `{prod-id}` in the *Client ID* field. ... Optionally enter a *Name* and *Description* for the OAuth client. ... Click *Next*. .. On the *Capability config* page: @@ -61,13 +61,21 @@ KEYCLOAK_URL=https://$({orch-cli} get route keycloak -n $KEYCLOAK_NAMESPACE --te + [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}"}]' +{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. +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: @@ -92,7 +100,7 @@ watch {orch-cli} get co kube-apiserver apiVersion: v1 kind: Secret metadata: - name: {prod-id}-oauth-secret + name: oauth-secret namespace: {prod-namespace} labels: app.kubernetes.io/part-of: che.eclipse.org @@ -100,7 +108,7 @@ stringData: oAuthSecret: ____ <1> EOF ---- -<1> The client secret value from the `eclipse-che` client in Keycloak. +<1> The client secret value from the `{prod-id} client in {keycloak}. . Create the `ConfigMap` with a {keycloak} certificate in the `{prod-namespace}` namespace. @@ -134,7 +142,7 @@ spec: networking: auth: oAuthClientName: {prod-id} - oAuthSecret: {prod-id}-oauth-secret + oAuthSecret: oauth-secret identityProviderURL: "$KEYCLOAK_URL/realms/$OPENSHIFT_REALM" gateway: oAuthProxy: