Configuring authorization

Authorization and user management

Eclipse Che uses Keycloak to create, import, manage, delete, and authenticate users. Keycloak uses built-in authentication mechanisms and user storage. It can use third-party identity management systems to create and authenticate users. Eclipse Che requires a Keycloak token when you request access to Che resources.

Local users and imported federation users must have an email address in their profile.

The default Keycloak credentials are admin:admin. You can use the admin:admin credentials when logging into Eclipse Che for the first time. It has system privileges.

Identifying the Keycloak URL
Che running on Kubernetes

Go to $CHE_HOST:5050/auth.

Che is running on OpenShift

Go to the OpenShift web console and to the Keycloak project.

Configuring Che to work with Keycloak

The deployment script configures Keycloak. It creates a che-public client with the following fields:

  • Valid Redirect URIs: Use this URL to access Che.

  • Web Origins

The following are common errors when configuring Che to work with Keycloak:

Invalid redirectURI error

Occurs when you access Che at myhost, which is an alias, and your original CHE_HOST is 1.1.1.1. If this error occurs, go to the Keycloak administration console and ensure that the valid redirect URIs are configured.

CORS error

Occurs when you have an invalid web origin.

Configuring Keycloak tokens

A user token expires after 30 minutes by default.

You can change the following Keycloak token settings:

keycloak realm

Setting up user federation

Keycloak federates external user databases and supports LDAP and Active Directory. You can test the connection and authenticate users before choosing a storage provider.

See the User storage federation page in Keycloak documentation to learn how to add a provider.

See the LDAP and Active Directory page in Keycloak documentation to specify multiple LDAP servers.

Enabling authentication with social accounts and brokering

Keycloak provides built-in support for GitHub, OpenShift, and most common social networks such as Facebook and Twitter. See Keycloak documentation to learn how to enable Login with GitHub.

Configuring GitHub OAuth

OAuth for GitHub allows for automatic SSH key upload to GitHub.

Prerequisites
  • The kubectl tool is available.

Procedure
  • Create a OAuth application in GitHub using Che URL as the value for the application Homepage URL and Keycloak GitHub endpoint URL as the value for Authorization callback URL. The default values are https://che-eclipse-che.<DOMAIN>/ and https://keycloak-eclipse-che.<DOMAIN>/auth/realms/che/broker/github/endpoint respectively, where <DOMAIN> is Kubernetes cluster domain.

  • For Che deployed in multi-user mode:

    1. Create a new secret in the namespace where Che is deployed.

      $ kubectl apply -f - <<EOF
      kind: Secret
      apiVersion: v1
      metadata:
        name: github-oauth-credentials
        namespace: <...> (1)
        labels:
          app.kubernetes.io/part-of: che.eclipse.org
          app.kubernetes.io/component: keycloak-secret
        annotations:
          che.eclipse.org/github-oauth-credentials: 'true'
          che.eclipse.org/mount-as: env
          che.eclipse.org/id_env-name: GITHUB_CLIENT_ID
          che.eclipse.org/secret_env-name: GITHUB_SECRET
      data:
        id: <...> (2)
        secret: <...> (3)
      type: Opaque
      EOF
      1 Che namespace. The default is eclipse-che
      2 base64 encoded GitHub OAuth Client ID
      3 base64 encoded GitHub OAuth Client Secret
    2. If Che was already installed wait until rollout of Keycloak component finishes.

  • For Che deployed in single-user mode:

    1. On Kubernetes or OpenShift, update the deployment configuration (see Configuring the Che installation and installation-guide:advanced-configuration-options-for-the-che-server-component.adoc#authentication-parameters).

      CHE_OAUTH_GITHUB_CLIENTID=<your-github-client-ID>
      CHE_OAUTH_GITHUB_CLIENTSECRET=<your-github-secret>
    2. In the Authorization callback URL field of the GitHub OAuth application, enter <prod-url/api/oauth/callback.

      • Substitute <prod-url> with the URL and port of the Che installation.

      • Substitute <your-github-client-ID> and <your-github-secret> with your GitHub client ID and secret.

      • This configuration only applies to single-user deployments of Che.

Using protocol-based providers

Keycloak supports SAML v2.0 and OpenID Connect v1.0 protocols.

Managing users using Keycloak

You can add, delete, and edit users in the user interface. See Keycloak User Management for more information.

Configuring Che to use an external Keycloak installation

By default, Che installation includes the deployment of a dedicated Keycloak instance. However, using an external Keycloak is also possible. This option is useful when a user has an existing Keycloak instance with already-defined users, for example, a company-wide Keycloak server used by several applications.

A dedicated Keycloak instance is only deployed with Che installed in multiuser mode.
Table 1. Placeholders used in examples

<provider-realm-name>

Identity provider realm name intended for use by Che

<oidc-client-name>

Name of the oidc client defined in <provider-realm-name>

<auth-base-url>

Base URL of the external Keycloak server

Prerequisites
  • This procedure is only applicable to Che installations done using the Che Operator. When using the chectl management tool and Helm to install Che, no supported method is available to use an external Keycloak instance.

  • In the administration console of the external installation of Keycloak, define a realm containing the users intended to connect to Che:

    external keycloak realm
  • In this realm, define an OIDC client that Che will use to authenticate the users. This is an example of such a client with the correct settings:

    external keycloak public client
    • Client Protocol must be openid-connect.

    • Access Type must be public. Che only supports the public access type.

    • Valid Redirect URIs must contain at least two URIs related to the Che server, one using the http protocol and the other https. These URIs must contain the base URL of the Che server, followed by /* wildcards.

    • Web Origins must contain at least two URIs related to the Che server, one using the http protocol and the other https. These URIs must contain the base URL of the Che server, without any path after the host.

      The number of URIs depends on the number of installed product tools.

  • With Che installed on OpenShift that uses the default OpenShift OAuth support, user authentication relies on the integration of Keycloak with OpenShift OAuth. This allows users to log in to Che with their OpenShift login and have their workspaces created under personal OpenShift projects.

    This requires setting up an OpenShift identity provider ins Keycloak. When using an external Keycloak, set up the identity provider manually. For instructions, see the appropriate Keycloak documentations for either OpenShift 3 or OpenShift 4.

  • The configured identity provider has the options Store Tokens and Stored Tokens Readable enabled.

Procedure
  1. Set the following properties in the CheCluster Custom Resource (CR):

    spec:
      auth:
        externalIdentityProvider: true
        identityProviderURL: <auth-base-url>
        identityProviderRealm: <provider-realm-name>
        identityProviderClientId: <oidc-client-name>
  2. When installing Che on OpenShift with OpenShift OAuth support enabled, set the following properties in the CheCluster Custom Resource (CR):

    spec:
      auth:
        openShiftoAuth: true
    # Note: only if the OpenShift identity provider alias is different from 'openshift-v3' or 'openshift-v4'
    server:
      customCheProperties:
        CHE_INFRA_OPENSHIFT_OAUTH__IDENTITY__PROVIDER: <OpenShift identity provider alias>

Configuring Che to work without Keycloak

By default, Che is deployed in multiuser mode where Keycloak and PostgreSQL are enabled by default. However, it is possible to deploy it in the single-user mode too, by changing the CHE_MULTIUSER value to false. In that case, neither Keycloak nor PostgreSQL is installed.

Prerequisites
Procedure
  1. Prepare the cr-patch.yaml file with the following content:

    spec:
      server:
          customCheProperties:
            CHE_MULTIUSER: false
  2. Install Che in the single-user mode:

    $ chectl server:deploy --platform <platform> --installer operator  --che-operator-cr-patch-yaml cr-patch.yaml

    Depending on the strategy used, replace the <platform> option in the above example with crc, minishift, or openshift. Kubernetes-native platforms such as minikube, microk8s, k8s, and docker-desktop are also available.

Verification
  1. Wait for the console log output to display the Command server:deploy has completed successfully. message:

    ✔ Retrieving Eclipse Che server URL...<ECLIPSE_CHE_URL>
       ✔ Eclipse Che status check
    Command server:deploy has completed successfully.
  2. Use the following command for correct boolean verification:

    $ {prod-cli} get checluster -o=jsonpath='{.items[0].spec.server.customCheProperties.CHE_MULTIUSER}'

    If the output of the command is false, Che has been successfully configured in single-user mode.

Configuring SMTP and email notifications

Eclipse Che does not provide any pre-configured MTP servers.

To enable SMTP servers in Keycloak:

  1. Go to che realm settings > Email.

  2. Specify the host, port, username, and password.

Eclipse Che uses the default theme for email templates for registration, email confirmation, password recovery, and failed login.