Sign in to GitLab from the GitLab Workflow extension

Users can sign in to GitLab with OAuth directly from the GitLab Workflow extension that runs in a workspace, without pasting a personal access token. This page describes how the browser-based OAuth flow works and how to enable it for the workspaces of a Che instance.

How GitLab OAuth sign-in works in a workspace

IDE extensions sign in to GitLab with an OAuth authorization-code flow. In desktop Visual Studio Code, GitLab returns the authorization code to the editor through the vscode:// URI scheme. In Che, the editor runs in a browser: the vscode:// scheme cannot receive the redirect, and every workspace has a different URL that cannot be registered in advance as the redirect URI of an OAuth application.

Che provides a stable redirect endpoint for this case: https://<che_fqdn>/api/oauth/ide-redirect. You register this endpoint as the Redirect URI of a GitLab application and configure the GitLab Workflow extension in workspaces to use that application. During sign-in, the extension puts the callback URL of the workspace, together with an anti-CSRF token, into the OAuth state parameter. When GitLab redirects to the endpoint with the authorization code, Che forwards the code to the workspace that started the sign-in, and the extension exchanges the code for a token.

The callback URL travels inside the state parameter and is chosen by whoever builds the authorization URL, so it is not trusted. Che forwards the authorization code only when both of the following are true:

  • the request comes from a user who is signed in to Che

  • the callback URL is located under the main URL of one of the workspaces of that user

Because of these checks, a user cannot collect the authorization code of another user by handing them an authorization URL that points to their own workspace.

This OAuth flow is independent of the OAuth configuration for Git operations in workspaces, which Connect GitLab with OAuth describes. Both can be configured for the same GitLab instance.

Prerequisites
  • Workspaces use an editor based on Visual Studio Code, such as Che Code.

  • The GitLab Workflow extension installed in workspaces supports the GITLAB_WORKFLOW_OAUTH_* environment variables described in this page.

To enable GitLab OAuth sign-in from the IDE:

  1. Register a GitLab application for the IDE redirect.

  2. Mount the GitLab Workflow OAuth configuration into workspaces.

Registering a GitLab application for the IDE redirect

Register a GitLab application that the GitLab Workflow extension uses to sign in to GitLab from workspaces.

Prerequisites
Procedure
  1. Click your avatar and go to Edit profile  Applications.

  2. Enter a name for the application, for example Che IDE.

  3. Enter https://<che_fqdn>/api/oauth/ide-redirect as the Redirect URI.

  4. Leave the Confidential checkbox unselected. The GitLab Workflow extension is a public client that runs on the user side and cannot keep a client secret.

  5. Under Scopes, check the api checkbox.

  6. Click Save application.

  7. Copy and save the Application ID of the new application for use when mounting the GitLab Workflow OAuth configuration.

This application is separate from the GitLab authorized application that Connect GitLab with OAuth uses for Git operations. Do not reuse that application here: it is confidential, while the GitLab Workflow extension requires a non-confidential application. Both applications can be registered for the same GitLab instance.

Mounting the GitLab Workflow OAuth configuration into workspaces

Create a ConfigMap that provides the OAuth parameters of the registered GitLab application to the GitLab Workflow extension in every workspace.

The GitLab Workflow extension reads the following environment variables:

Table 1. Environment variables of the GitLab Workflow extension
Environment variable Description

GITLAB_WORKFLOW_INSTANCE_URL

The URL of the GitLab instance that the application is registered on, for example https://gitlab.com. The other two variables apply only to this instance.

GITLAB_WORKFLOW_OAUTH_CLIENT_ID

The Application ID of the registered GitLab application.

GITLAB_WORKFLOW_OAUTH_REDIRECT_URI

The redirect URI of the application: https://<che_fqdn>/api/oauth/ide-redirect. The value must exactly match the Redirect URI registered in the GitLab application. Setting this variable enables the browser-based OAuth flow.

The configuration applies to a single GitLab instance: the one named by GITLAB_WORKFLOW_INSTANCE_URL. For other instances, the extension uses its own configured OAuth clients, and the browser-based flow is not available for them.

Prerequisites
  • Registering a GitLab application for the IDE redirect is completed, and the Application ID of the application is at hand.

  • An active kubectl session with administrative permissions to the destination Kubernetes cluster. See Overview of kubectl.

Procedure
  1. Prepare the ConfigMap:

    kind: ConfigMap
    apiVersion: v1
    metadata:
      name: gitlab-workflow
      namespace: eclipse-che (1)
      labels:
        app.kubernetes.io/part-of: che.eclipse.org
        app.kubernetes.io/component: workspaces-config (2)
        controller.devfile.io/mount-to-devworkspace: 'true' (3)
        controller.devfile.io/watch-configmap: 'true'
      annotations:
        controller.devfile.io/mount-as: env (4)
    data:
      GITLAB_WORKFLOW_INSTANCE_URL: <gitlab_instance_url> (5)
      GITLAB_WORKFLOW_OAUTH_CLIENT_ID: <gitlab_application_id> (6)
      GITLAB_WORKFLOW_OAUTH_REDIRECT_URI: https://<che_fqdn>/api/oauth/ide-redirect
    1 The Che namespace. The default is eclipse-che.
    2 Synchronizes the ConfigMap to the namespace of every user. See Configuring a user namespace.
    3 Mounts the ConfigMap into workspaces. The controller.devfile.io/watch-configmap label lets the DevWorkspace Operator discover the ConfigMap.
    4 Exposes each key of the ConfigMap as an environment variable in every container of a workspace.
    5 The URL of the GitLab instance, for example https://gitlab.com.
    6 The Application ID of the registered GitLab application.
  2. Apply the ConfigMap:

    $ kubectl apply -f - <<EOF
    <ConfigMap_prepared_in_the_previous_step>
    EOF
  3. Verify in the output that the ConfigMap is created.

Applying a ConfigMap labeled with controller.devfile.io/mount-to-devworkspace: 'true' restarts all running workspaces. To mount the ConfigMap only when a workspace starts, add the controller.devfile.io/mount-on-start: 'true' annotation to the ConfigMap. Running workspaces then pick up the ConfigMap after their next restart.

Verification
  • Start a new workspace, open a terminal in it, and run:

    $ env | grep GITLAB_WORKFLOW
    GITLAB_WORKFLOW_INSTANCE_URL=https://gitlab.com
    GITLAB_WORKFLOW_OAUTH_CLIENT_ID=__<gitlab_application_id>__
    GITLAB_WORKFLOW_OAUTH_REDIRECT_URI=__<redirect_uri_of_the_application>__

Users can then sign in from their workspaces:

Signing in to GitLab from a workspace

Sign in to GitLab with OAuth from the GitLab Workflow extension that runs in a workspace. A successful sign-in also verifies that the GitLab application and the GitLab Workflow OAuth configuration are set up correctly.

Prerequisites
  • Registering a GitLab application for the IDE redirect and mounting the GitLab Workflow OAuth configuration are completed.

  • A workspace is running with an editor based on Visual Studio Code, such as Che Code, and with the GitLab Workflow extension installed.

  • You are signed in to Che in the browser in which the IDE runs. The OAuth redirect requires an active Che session.

Procedure
  1. In the sidebar of the IDE, open the GitLab view.

  2. Start the sign-in, for example by clicking Authenticate to GitLab.

  3. In the Select GitLab instance list, select the instance that the GitLab application is registered on.

  4. In the Select authentication method list, select OAuth.

  5. In the browser tab that opens, review the permissions and click Authorize.

    GitLab redirects back to Che, which forwards the authorization code to the workspace. The IDE shows a notification that a GitLab account is added.

Verification
  • Verify that the GitLab view lists your issues and merge requests.

Additional resources