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-config
        namespace: <...> (1)
        labels:
          app.kubernetes.io/part-of: che.eclipse.org
          app.kubernetes.io/component: oauth-scm-configuration
        annotations:
          che.eclipse.org/oauth-scm-server: github
      type: Opaque
      data:
        id: <...> (2)
        secret: <...> (3)
      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.

Configuring Bitbucket servers

To make it possible to use the Bitbucket server as a project sources supplier, Bitbucket server URL should be registered on Eclipse Che using the CHE_INTEGRATION_BITBUCKET_SERVER__ENDPOINTS property. Value of the property must contain the hostname of the server to register. Examples on how to change configuration options using Helm or the Operator can be found here:

Configuring Bitbucket Server OAuth 1

This procedure describes how to activate OAuth 1 for Bitbucket Server to:

It enables Che to obtain and renew Bitbucket Server Personal access tokens.

Prerequisites
  • The kubectl tool is available.

  • Bitbucket Server is available from Che server.

Procedure
  1. Generate a RSA key pair and a stripped down version of the public key:

    openssl genrsa -out <private.pem> 2048
    openssl rsa -in <private.pem> -pubout > <public.pub>
    openssl pkcs8 -topk8 -inform pem -outform pem -nocrypt -in <private.pem> -out <privatepkcs8.pem>
    cat <public.pub> | sed 's/-----BEGIN PUBLIC KEY-----//g' | sed 's/-----END PUBLIC KEY-----//g' | tr -d '\n' > <public-stripped.pub>
  2. Generate a consumer key and a shared secret.

    openssl rand -base64 24 > <bitbucket_server_consumer_key>
    openssl rand -base64 24 > <bitbucket_shared_secret>
  3. Create a Kubernetes Secret in Che namespace containing the consumer and private keys.

    $ kubectl apply -f - <<EOF
    kind: Secret
    apiVersion: v1
    metadata:
      name: bitbucket-oauth-config
      namespace: <...> (1)
      labels:
        app.kubernetes.io/part-of: che.eclipse.org
        app.kubernetes.io/component: oauth-scm-configuration
      annotations:
        che.eclipse.org/oauth-scm-server: bitbucket
        che.eclipse.org/scm-server-endpoint: <...> (2)
    type: Opaque
    data:
      private.key: <...> (3)
      consumer.key: <...> (4)
    EOF
    1 Che namespace. The default is eclipse-che
    2 Bitbucket Server URL
    3 base64 encoded content of the <privatepkcs8.pem> file without first and last lines.
    4 base64 encoded content of the <bitbucket_server_consumer_key> file.
  4. Configure an Application Link in Bitbucket to enable the communication from Che to Bitbucket Server.

    1. In Bitbucket Server, click the cog in the top navigation bar to navigate to Administration > Application Links.

  1. Enter the application URL: https://che-host:che-port and click the Create new link button.

  1. On the warning message stating "No response was received from the URL" click the Continue button.

  1. Fill-in the Link Applications form and click the Continue button.

    Application Name

    <Che>

    Application Type

    Generic Application.

    Service Provider Name

    <Che>

    Consumer Key

    Paste the content of the <bitbucket_server_consumer_key> file.

    Shared secret

    Paste the content of the <bitbucket_shared_secret> file.

    Request Token URL

    <Bitbucket Server URL>/plugins/servlet/oauth/request-token

    Access token URL

    <Bitbucket Server URL>/plugins/servlet/oauth/access-token

    Authorize URL

    <Bitbucket Server URL>/plugins/servlet/oauth/access-token

    Create incoming link

    Enabled.

  2. Fill-in the Link Applications form and click the Continue button.

    Consumer Key

    Paste the content of the <bitbucket_server_consumer_key> file.

    Consumer name

    <Che>

    Public Key

    Paste the content of the <public-stripped.pub> file.

Configuring GitLab servers

To make it possible to use the GitLab server as a project sources supplier, GitLab server URL should be registered on Eclipse Che using the CHE_INTEGRATION_GITLAB_SERVER__ENDPOINTS property. Value of the property must contain the hostname of the server to register. Examples on how to change configuration options using Helm or the Operator can be found here:

Configuring GitLab OAuth2

OAuth2 for GitLab allows accepting factories from private GitLab repositories.

Prerequisites
  • GitLab server is running and available from Che

Procedure
  • Create a Authorized OAuth2 application in GitLab using Che as the application Name and Keycloak GitLab endpoint URL as the value for Redirect URI. The callback URL default value is https://keycloak-eclipse-che.<DOMAIN>/auth/realms/che/broker/gitlab/endpoint, where <DOMAIN> is Kubernetes cluster domain. Store the Application ID and Secret values. All three types of GitLab OAuth2 applications are supported: User owned, Group owned and Instance-wide.

    1. Create a custom OIDC provider link on Keycloak pointing to GitLab server. Fill the following fields:

      Client ID

      a value from the Application ID field provided by GitLab server in previous step;

      Client Secret

      a value from Secret field provided by GitLab server in previous step;

      Authorization URL

      a URL which have a ++https://<GITLAB_DOMAIN>/oauth/oauth/authorize format;

      Token URL

      a URL which have a ++https://<GITLAB_DOMAIN>/oauth/oauth/token format;

      Scopes

      set of scopes which must contain (but not limited to) the following set: api write_repository openid

    • Substitute <GITLAB_DOMAIN> with the URL and port of the GitLab installation.

Additional resources

In case of having issues Che accessing GitLab related to TLS keys, consult with the following docs:

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>

Keycloak 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 (Keycloak or RH-SSO). When using an external Keycloak, configure the Keycloak manually. For instructions, see the appropriate Keycloak documentations for either OpenShift 3 or OpenShift 4.

  • The configured Keycloak 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 (Keycloak or RH-SSO) alias is different from 'openshift-v3' or 'openshift-v4'
    server:
      customCheProperties:
        CHE_INFRA_OPENSHIFT_OAUTHIDENTITYPROVIDER: <OpenShift Identity Provider (Keycloak or RH-SSO) 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.

Enabling self-registration

Self-registration allows users to register themselves in a Che instance by accessing the Che server URL.

For Che installed without OpenShift OAuth support, self-registration is disabled by default, therefore the option to register a new user is not available on the login page.

Prerequisites
  • You are logged in as an administrator.

Procedure

To enable self-registration of users:

  1. Navigate to the Realm Settings menu on the left and open the Login tab.

  2. Set User registration option to On.