Enable logins with GitLab accounts

Introduction

Debusine supports OpenID Connect authentication: these are the instructions for setting up authentication against a GitLab server.

Set up

Configure the provider in your Debusine instance

In your local settings:

from debusine.project.utils import read_secret_key
from debusine.server.signon import providers

SIGNON_PROVIDERS = [
    # Example using salsa.debian.org
    providers.GitlabProvider(
        # Provider name to use in the Redirect URI
        name="salsa",
        # User-visible name
        label="Salsa",
        # Optional icon (path under the static directory)
        icon="signon/gitlabian.svg",
        # URL to the GitLab instance
        url="https://salsa.debian.org",
        # OIDC parameters
        client_id="<to be filled with GitLab-provided Application ID>",
        client_secret=read_secret_key("/etc/debusine/gitlab-app-secret"),
        scope=("openid", "profile", "email"),
        # Restrict local user creation to users with these matching claims
        restrict=("email-verified", "group:debian"),
    ),
]

Create /etc/debusine/gitlab-app-secret with the application secret provided by GitLab and make sure the file is only readable by the debusine-server user:

echo "<to be filled with Gitlab-provided Secret>" > /etc/debusine/gitlab-app-secret
chmod 0600 /etc/debusine/gitlab-app-secret
chown debusine-server:debusine-server /etc/debusine/gitlab-app-secret

Create the application in GitLab

Go to your profile preferences, under “Applications”
Create a new application:
1. Tick “Confidential” checkbox
2. Select scopes: “openid”, “profile”, “email”
3. Redirect URI: https://your.debusine.server/accounts/accounts/oidc_callback/$PROVIDER_NAME/ (note that https is required, and this cannot be deployed over plain http)
4. Copy the Application ID and the Secret to your Debusine local settings

Restart debusine

When everything is set up, restart debusine-server:

systemctl restart debusine-server

In the login page you should now see the option to log in using the provider you configured.

User mapping

Remote users are matched to local users according to their email claim; if there is no matching local user, a new one is created with the remote-provided account information, as long as it respects the restrict setting.

Settings

SIGNON_PROVIDERS

List of configured remove providers, as instances of debusine.server.signon.providers.Provider subclasses. Please refer to the documentation of individual subclasses for details.

GitlabProvider.restrict

Configures restrictions for matching remote users to local accounts.

Restrictions match the claims provided by the remote authentication provider, and a user whose claims do not match the restriction cannot be automatically mapped to a local user.

restrict can be set to a sequence of strings, each specifying a restriction:

group:name: the given group name must be present
email-verified: the primary email needs to be reported as verified

All listed restrictions must be met (i.e. they are AND-ed together).

Example:

restrict=["group:debian", "email-verified"],