Authenticating users on private repositories of SCM servers

The following section describes how to configure user authentications for SCM servers.

Authenticating on Bitbucket servers

The following section describes the configuration needed to enables Che to use Bitbucket (BB) repositories with Git cloning operations.

BB authentication is based on using personal access tokens. Each BB user is able to request several personal access tokens with different attributes, such as names, permissions, or expiration times. Those tokens can also be used to sign BB REST API calls and perform Git repository operations.

  • Che users may use public or private repositories on the BB Source Code Management (SCM) system as a source of their projects.

Before configuring the OAuth 1 authentication that is required for reading from private repositories and writing to both private and public repositories, configure the BB server with Che first. To do so, see the Prerequisites section below.
Additional resources

For a remote Git repository that uses a self-signed certificate, add an additional server configuration. See Deploying Che with support for Git repositories with self-signed certificates.

Prerequisites
  • A BB endpoint has been registered with Che. Follow the Configuring Bitbucket servers procedure and register a BB server using the CHE_INTEGRATION_BITBUCKET_SERVER__ENDPOINTS YAML secret property.

Procedure
  1. Configure the OAuth 1 authentication by following the Configuring Bitbucket Server OAuth 1 procedure.

Authenticating on GitLab servers

Configuring authentication on the GitLab system is similar to Bitbucket.

GitLab authentication is based on using personal access tokens. Each GitLab user is able to request several personal access tokens with different names, permissions, expiration times, and so on. Those tokens can be used to sign GitLab REST API calls and perform Git repository operations.

See the GitLab documentation for more details about personal access tokens.

To allow GitLab authentication on Che side, personal tokens must be stored in the user’s namespace in the form of a secret. The secret must look as follows:

Example 1. GitLab personal access token secret
apiVersion: v1
kind: Secret
metadata:
  name: gitlab-personal-access-token-secret
  labels:
    app.kubernetes.io/part-of: che.eclipse.org
    app.kubernetes.io/component: scm-personal-access-token
  annotations:
    che.eclipse.org/expired-after: '-1'
    che.eclipse.org/che-userid: '355d1ce5-990e-401e-9a8c-094bca10b5b3'
    che.eclipse.org/scm-userid: '2'
    che.eclipse.org/scm-username: 'user-foo'
    che.eclipse.org/scm-url: 'https://gitlab.apps.cluster-example.com'
data:
  token: Yzh5cEt6cURxUWVCa3FKazhtaHg=

The main parts of the secret are:

Label

app.kubernetes.io/component

Indicates it is a SCM personal token secret.

Annotation

che.eclipse.org/che-userid

Eclipse Che id of the user token belongs to

Annotation

che.eclipse.org/scm-userid

GitLab user id to which token belongs

Annotation

che.eclipse.org/scm-username

GitlLab user name to which token belongs

Annotation

che.eclipse.org/scm-url

GitLab server URL to which this token belong

Annotation

che.eclipse.org/expired-after

Personal access token expiration time

Data entry

token

Base-64 encoded value of the personal access token

Encoding a string into the base64 format using the base64 tool on Linux machines leads to adding the newline character to the end of the source string and causing a value to be unusable as the authentication header value after decoding. Avoid this by using base64 -w0, which removes newly added lines, or strip newlines explicitly using`tr -d \\n`.
  1. To obtain a user ID from a secret, take a look into user profile page on GitLab web UI or make a call to a REST API URL:

    • For GitLab:

      https://<gitlab-hostname>/api/v4/users?username=<username>
    • For Che

      https://che-host:che-port/api/user
    • With the token credentials obtained from a secret, another secret is automatically created, allowing authorization to Git operations. This secret is mounted into a workspace container as a Git credentials file, and any additional configurations are not required to work with private Git repositories.

    • When a remote Git repository uses a self-signed certificate, add an additional server configuration. See: Deploying Che with support for Git repositories with self-signed certificates.

Authenticating on GitHub servers

Configuring authentication on the GitHub system is similar to GitLab.

GitHub authentication can be based on using personal access tokens. Each GitHub user is able to request several personal access tokens with different names, permissions, expiration times, and so on. Those tokens can be used to sign GitHub REST API calls and perform Git repository operations.

To allow GitHub authentication on Che side, personal tokens must be stored in the user’s namespace in the form of a secret. The secret must look as follows:

Example 2. GitHub personal access token secret
apiVersion: v1
kind: Secret
metadata:
  name: github-personal-access-token-secret
  labels:
    app.kubernetes.io/part-of: che.eclipse.org
    app.kubernetes.io/component: scm-personal-access-token
  annotations:
    che.eclipse.org/expired-after: '-1'
    che.eclipse.org/che-userid: '355d1ce5-990e-401e-9a8c-094bca10b5b3'
    che.eclipse.org/scm-userid: '1651062'
    che.eclipse.org/scm-username: 'user-foo'
    che.eclipse.org/scm-url: 'https://github.com'
data:
  token: Yzh5cEt6cURxUWVCa3FKazhtaHg=

The main parts of the secret are:

Label

app.kubernetes.io/component

Indicates it is an SCM personal token secret.

Annotation

che.eclipse.org/che-userid

Eclipse Che id of the user token belongs to

Annotation

che.eclipse.org/scm-userid

GitHub user id to which token belongs

Annotation

che.eclipse.org/scm-username

GitHub username to which token belongs

Annotation

che.eclipse.org/scm-url

GitHub server URL to which this token belongs. Typically, it is https://github.com

Annotation

che.eclipse.org/expired-after

Personal access token expiration time

Data entry

token

Base-64 encoded value of the personal access token

Encoding a string into the base64 format using the base64 tool on Linux machines leads to adding the newline character to the end of the source string and causing a value to be unusable as the authentication header value after decoding. Avoid this by using base64 -w0, which removes newly added lines, or strip newlines explicitly using`tr -d \\n`.
  1. To obtain a user ID from a secret, make a call to a REST API URL:

    https://api.github.com/user
    • For Che

      https://che-host:che-port/api/user
    • With the token credentials obtained from a secret, another secret is automatically created, allowing authorization to Git operations. This secret is mounted into a workspace container as a Git credentials file, and any additional configurations are not required to work with private Git repositories.

    • When a remote Git repository uses a self-signed certificate, add an additional server configuration. See: Deploying Che with support for Git repositories with self-signed certificates.