Install Che on OpenShift with Keycloak as external identity provider

To enable centralized user authentication through an external identity provider, install Che on Kubernetes with Keycloak as the OIDC provider.

This page is for platform administrators who install, configure, and manage Che on Kubernetes clusters. To learn more about common roles and example tasks referenced in Che documentation, see Common user roles and tasks.

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

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.
5. On the Login settings page:
  
  Enter Che redirect URL in the Valid redirect URIs field.
  
  Run the following command to obtain the Eclipse Che redirect URL:
  
  echo "$( oc whoami --show-console | sed 's|console-openshift-console|eclipse-che|g' )/oauth/callback"
  
  Click Save.
6. 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 OAuth authentication:

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

1	The client secret value from the `che` client credentials tab in Keycloak.

Prepare the CheCluster patch:

cat > che-patch.yaml <<EOF
kind: CheCluster
apiVersion: org.eclipse.che/v2
spec:
  networking:
    auth:
      oAuthClientName: che
      oAuthSecret: che-oidc-client-secret
      gateway:
        oAuthProxy:
          cookieExpireSeconds: 300
        deployment:
          containers:
            - name: oauth-proxy
              env:
                - name: OAUTH2_PROXY_BACKEND_LOGOUT_URL
                  value: "<issuer_url>/protocol/openid-connect/logout?id_token_hint={id_token}" (1)
EOF

1	The Keycloak OIDC issuer URL.

Create the Che instance with chectl:

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

Verification

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

Additional resources

Enabling direct authentication with an external OIDC identity provider