Configuring authorization

Che uses the permissions model for user 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
  1. Create an OAuth application in GitHub with the following URLs:

    • Enter the Che URL as Homepage URL. The default value is https://che-eclipse-che.<domain>/.

    • Enter the Authorization callback URL as follows:

      • If the DevWorkspace engine is not enabled, enter the Keycloak GitHub endpoint URL as Authorization callback URL. The default value is https://keycloak-eclipse-che.<domain>/auth/realms/che/broker/github/endpoint.

      • If the DevWorkspace engine is enabled, enter the Che OAuth callback URL as Authorization callback URL. The default value is https://che-eclipse-che.<domain>/api/oauth/callback.

  2. 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
  3. If Che was already installed wait until rollout of Keycloak component finishes.

Configuring a Bitbucket server that uses self-signed TLS certificates

The following chapter describes how to configure a Bitbucket (BB) server that uses self-signed TLS certificates so that the Che server and workspace components can establish a trusted connection with BB.

  • Creating ConfigMaps for additional TLS and gitSelfSign certificates. This enables:

    • Launching a factory using a devfile URL.

    • Importing and cloning a project.

  • Configure the OAuth 1 authentication on the BB server side. For more information, see Configuring Bitbucket Server OAuth 1

  • Creating a ConfigMap for importing additional certificates is necessary only if a BB server is setup with self-signed TLS certificates. These certificates are needed for the proper functionality of Che server and tools inside of a workspace, which use them for performing Git operations related to a specific repository.

Prerequisites
  • A value of the BB server certification authority (CA) exported in the Base64 ASCII format and stored in a ca.crt file.

  • An instance of Che.

Procedure
  1. Provision the CA of the BB server to the Che server to enable it to read the devfiles stored in the BB server. To do so, add the following ConfigMap to the eclipse-che namespace:

    $ kubectl create configmap bitbucket-ca-cert-for-factory --from-file=ca.crt -n eclipse-che
    $ kubectl label configmap bitbucket-ca-cert-for-factory app.kubernetes.io/part-of=che.eclipse.org app.kubernetes.io/component=ca-bundle -n eclipse-che
  2. Provision the CA of the BB server to the Che server to be able to use Git operations. To do so, add a new ConfigMap to the eclipse-che namespace:

    $ kubectl create configmap che-git-self-signed-cert --from-file=ca.crt --from-literal=githost=<bitbucket_server_url> -n eclipse-che
  3. Edit the CheCluster Custom Resource (CR) to configure the Che server.

    spec:
      server:
        # …
        gitSelfSignedCert: <boolean> (1)
    1 Use true for a BB server that use a self-signed cert. Default value: false.
Reference

Configuring the Bitbucket and Che integration to use OAuth1

The following section describes the configuration of the OAuth 1 authentication that is needed for performing read and write operations with Bitbucket (BB) repositories. To use BB repositories with allowed Git operations, such as clone and push, register a BB endpoint with Che first, and configure the OAuth 1 authentication.

This procedure requires:

  • generating RSA key pairs

  • generating a consumer key-secret pair

  • creating an application link on the BB side

  • configuring BB on the Che-server side

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

Prerequisites
  • The kubectl tool is available.

  • Bitbucket Server is available from Che server.

  • An instance of Che.

Procedure
  1. Generate an 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. 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.

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

    3. In the warning message stating No response was received from the URL click the Continue button.

    4. Complete 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.

    5. Complete 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.

  4. 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: <Che-namespace> (1)
      labels:
        app.kubernetes.io/component: oauth-scm-configuration
        app.kubernetes.io/part-of: che.eclipse.org
      annotations:
        che.eclipse.org/oauth-scm-server: bitbucket
        che.eclipse.org/scm-server-endpoint: '<scm-server-endpoint>' (2)
    type: Opaque
    data:
      private.key: '<user-private-key>' (3)
      consumer.key: '<bitbucket_server_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.
    Example
    #!/usr/bin/env bash
    
    NS=${1:-eclipse-che}
    CONSUMER_KEY=$(cat ./certs/bitbucket_server_consumer_key)
    PRIVATE_KEY=$(cat ./certs/privatepkcs8.pem | sed 's/-----BEGIN PRIVATE KEY-----//g' |  sed 's/-----END PRIVATE KEY-----//g' | tr -d '\n')
    BITBUCKET_HOST='<your-bitbucket-host-here>'
    unameOut="$(uname -s)"
    
    case "${unameOut}" in
        Linux*)     BASE64_FUNC='base64 -w 0';;
        Darwin*)    BASE64_FUNC='base64';;
        CYGWIN*)    BASE64_FUNC='base64 -w 0';;
        MINGW*)     BASE64_FUNC='base64 -w 0';;
        *)          BASE64_FUNC='base64 -w 0'
    esac
    
    cat <<EOF | oc apply -n $NS -f -
    kind: Secret
    apiVersion: v1
    metadata:
      name: bitbucket-oauth-config
      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: https://$BITBUCKET_HOST
    type: Opaque
    data:
      private.key: $(echo -n $PRIVATE_KEY | $BASE64_FUNC)
      consumer.key: $(echo -n $CONSUMER_KEY | $BASE64_FUNC)
    EOF

Configuring GitLab servers

To use a GitLab server as a project sources supplier, register the GitLab server URL with Che using the CHE_INTEGRATION_GITLAB_SERVER__ENDPOINTS property and specify the host name of the server to register.

Example
https://gitlab.apps.cluster-2ab2.2ab2.example.opentlc.com/

For additional examples of configuring GitLab servers see Understanding Che server advanced configuration using the Operator

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 OAuth 2 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/authorize format;

      Token URL

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

      Scopes

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

      Store Tokens

      needs to be enabled;

      Store Tokens Readable

      needs to be enabled

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

    2. Register the GitLab instance URL with the enabled OAuth 2 support in Che using the CHE_INTEGRATION_GITLAB_OAUTH__ENDPOINT property.

      • The GitLab instance URL must be present in the list of configured GitLab integration endpoints, set by the CHE_INTEGRATION_GITLAB_SERVER__ENDPOINTS property.

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.

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
  • In the administration console of the external installation of Keycloak, define a realm that contains the users 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 https://www.keycloak.org/docs/latest/server_admin/#openshift-3 or https://www.keycloak.org/docs/latest/server_admin/#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 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.