Install Che on Kubernetes with Keycloak as external identity provider

To manage user authentication through a centralized identity provider, deploy Che on an Kubernetes cluster with Keycloak as the external OpenID Connect (OIDC) provider.

Prerequisites

You have an active kubectl session with administrative permissions to the Kubernetes cluster. See Overview of kubectl.
You have Keycloak configured as an external identity provider for Kubernetes. See Enabling direct authentication with an external OIDC identity provider.

Procedure

Define the environment variables:

# The Keycloak realm used for Kubernetes authentication:
OPENSHIFT_REALM=<realm>

# The Keycloak URL:
KEYCLOAK_URL=<keycloak_url>

Create a che client in the Keycloak Admin Console:
1. Within the realm used for Kubernetes authentication, select Clients on the left side of the navigation bar.
2. Select the Create client button.
3. On the General Settings page:
  
  Enter che in the Client ID field.
  
  Optional: Enter a Name and Description for the OAuth client.
  
  Click Next.
4. On the Capability config page:
  
  Toggle Client authentication to On.
  
  Click Next.
  
  Click Save.
5. 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 che client to the audiences list in the Kubernetes authentication configuration:
```
kubectl patch authentication.config/cluster \
  --type='json' \
  -p='[
    {
      "op": "add",
      "path": "/spec/oidcProviders/0/issuer/audiences/-",
      "value": "che"
    }
  ]'
```
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:
```
watch kubectl get co kube-apiserver
```
Create a namespace for Che:
```
kubectl create namespace eclipse-che
```

Create a secret for the OAuth client in the Che namespace:

kubectl apply -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
  name: oauth-secret
  namespace: eclipse-che
  labels:
    app.kubernetes.io/part-of: che.eclipse.org
stringData:
  oAuthSecret: <client_secret>
EOF

where:

<client_secret>: The client secret value from the che client in Keycloak.

Optional: Create the ConfigMap with a Keycloak certificate in the eclipse-che namespace. If Keycloak uses a certificate that is already trusted by Kubernetes, skip this step.

openssl s_client \
  -connect "$(echo "$KEYCLOAK_URL" | sed 's|https://||'):443" \
  -showcerts < /dev/null \
| sed -n '/-----BEGIN CERTIFICATE-----/,/-----END CERTIFICATE-----/p' \
> keycloak-ca.crt

kubectl create configmap keycloak-certs \
    --from-file=keycloak-ca.crt=keycloak-ca.crt \
    -n eclipse-che && \
kubectl label configmap keycloak-certs \
    app.kubernetes.io/part-of=che.eclipse.org \
    app.kubernetes.io/component=ca-bundle \
    -n eclipse-che

Prepare the CheCluster patch:

cat > che-patch.yaml << EOF
kind: CheCluster
apiVersion: org.eclipse.che/v2
spec:
  networking:
    auth:
      oAuthClientName: che
      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>'
        CHE_OIDC_GROUPS__PREFIX: '<GROUPS_PREFIX>'
        CHE_OIDC_USERNAME__CLAIM: '<USERNAME_CLAIM>'
        CHE_OIDC_USERNAME__PREFIX: '<USERNAME_PREFIX>'
EOF

where:

CHE_OIDC_GROUPS__CLAIM

The claim to use for extracting user groups.

CHE_OIDC_GROUPS__PREFIX

The prefix to add to group names. Empty string means no prefix.

CHE_OIDC_USERNAME__CLAIM

The claim to use for extracting the username.

CHE_OIDC_USERNAME__PREFIX

The prefix to add to usernames. Empty string means no prefix.

These values must match the corresponding claim and prefix settings configured in the authentication.config/cluster resource. To view the current cluster configuration, run:

kubectl get authentication.config/cluster -o yaml

Create the Che instance with chectl:

chectl server:deploy \
  --platform openshift \
  --che-operator-cr-patch-yaml che-patch.yaml

Update the che client to set the Che redirect URI and web origin.

Obtain the Eclipse Che URL:
```
echo "$(kubectl get checluster eclipse-che -n eclipse-che -o jsonpath='{.status.cheURL}')"
```
1. In the Valid redirect URIs field, enter the URL above with /oauth/callback appended.
2. In the Web origins field, enter the URL above.
3. Click Save.

Verification

Verify the Che instance status:
```
chectl server:status
```
Navigate to the Che cluster instance:
```
chectl dashboard:open
```
Log in to the Che instance.