Setting up OAuth 2.0 authentication using GitLab#

This tutorial will guide you through the process of setting up authentication for your Juice instance using GitLab as an OAuth 2.0 provider. This means that users will be able to log in to your Juice instance using their GitLab credentials. Only users part of a specific GitLab group will be able to log in.

1. Prerequisites#

  1. Your Juice instance is publicly accessible over HTTPS, i.e. https://<your-juice-instance>. You can use a reverse proxy like Traefik or Cloudflare Tunnel to expose your Juice instance securely.

  2. You have a GitLab account, either on GitLab.com or on a self-hosted GitLab instance, with permissions to create applications and manage groups.

2. Create or choose a GitLab group#

  1. Create a new GitLab group or choose an existing one that contains the users you want to allow to log in to your Juice instance. Only users who are members of this group will be able to authenticate with GitLab and access your Juice instance. It does not matter which role the users have in the group, for example “Guest” is already sufficient for authentication to work. See Groups in the GitLab documentation for more information on how to create and manage groups.

  2. Note down the Group ID of the group you want to use. You can find this info from the group page. See Finding a group ID in the GitLab documentation for more details.

3. Create a GitLab application#

  1. Follow the instructions in the GitLab documentation to create a new application in GitLab. Decide whether you want to set up a user-owned application, a group-owned application, or an instance-wide application. This has no impact on the authentication process, but depends on the way you want to manage the application in GitLab. It’s good practice to create the application in the same group that you want to use for authentication, but this is not strictly necessary.

  2. In the new application page, enter the following settings:

    • Name: Choose a name for your application (e.g., “My Juice Instance”).

    • Redirect URI: Set this to https://<your-juice-instance>/hub/oauth_callback, replacing <your-juice-instance> with the actual domain of your Juice instance.

    • Confidential: Check this box to indicate that your application is confidential (i.e., it can securely store a client secret).

    • Scopes: Select the the following scopes: read_api, read_user, openid, profile and email.

  3. Save the application and note down the Application ID and Secret. You will need these values to configure Juice.

4. Configure and restart Juice#

  1. Add the following section to /etc/juice/config/orchestration.toml:

    [jupyterhub.main_hub]
authenticator_class = "gitlab"
oauth_callback_url = "https://<your-juice-instance>/hub/oauth_callback"

    Again, replace <your-juice-instance> with the actual domain of your Juice instance. If your config file already has a [jupyterhub.main_hub] section, simply add the authenticator_class and oauth_callback_url settings to that section.

  2. Configure the secrets for the GitLab OAuth 2.0 provider by creating a file at /etc/juice/jupyterhub/secrets.env with the following content. If the file already exists, add the following lines to the existing file.

    JUPYTERHUB_OAUTH_APP_ID=<your-application-id>
JUPYTERHUB_OAUTH_APP_SECRET=<your-application-secret>
JUPYTERHUB_OAUTH_GITLAB_URL=https://<your-gitlab-instance>
JUPYTERHUB_OAUTH_GITLAB_GROUP=<your-group-id>

    Replace <your-application-id>, <your-application-secret>, <your-gitlab-instance> and <your-group-id> with the actual values from your GitLab application and group. It’s very important the the GitLab URL has not trailing slash. So, for example, it should be https://gitlab.com and not https://gitlab.com/!

  3. Apply the config and restart Juice by running the following command:

    juice install --restart

  4. After the command is done, you can log in to your Juice instance using GitLab credentials. Navigate to your Juice instance and click “Sign in with GitLab” to test the authentication. If everything is configured correctly and you are part of the specified GitLab group, you should be able to log in successfully. If you get a “403 Forbidden” error after logging in, this means that you are not part of the specified GitLab group.