OIDC with GitLab¶
Connect GitLab as an upstream identity provider so users sign in with their GitLab account. This works with gitlab.com and with a self-managed GitLab instance.
The general mechanics are covered in OIDC Setup. This page covers what is specific to GitLab.
What the preset supplies¶
Selecting the GitLab provider type pre-fills:
- Issuer and discovery URL:
https://gitlab.com - Scopes:
openid profile email - Correlation claim:
sub
GitLab's sub is the user's numeric ID. It does not change when the user renames their account or changes their email address.
Self-managed GitLab¶
Replace the issuer with your instance's URL, for example https://gitlab.example.com, and leave the discovery URL blank. WeftID then reads the discovery document from your instance instead of gitlab.com. The issuer must match the external_url your instance is configured with, or the connection test fails with an issuer mismatch.
Step 1: Create the GitLab application¶
An application can belong to a user, a group, or (on a self-managed instance) the whole instance. A group or instance application survives the person who created it leaving.
- Open the application settings:
- Group: the group's Settings > Applications
- Instance (self-managed): Admin area > Applications
- User: Edit profile > Applications
- Click Add new application and give it a name
- Under Redirect URI, paste the callback URL from your WeftID connection's Details tab (you can create the WeftID connection first and fill this in afterwards)
- Leave Confidential checked
- Under Scopes, select
openid,profile, andemail - Click Save application and copy the Application ID and Secret
Step 2: Configure the WeftID connection¶
- In WeftID, go to Identity Providers > OIDC and create a connection with provider type GitLab
- For a self-managed instance, replace the issuer (see above)
- Paste the application ID as the client ID, and the secret as the client secret
- Click Test Connection, then enable the connection
Email linking¶
GitLab includes email_verified in its tokens, so email linking can match existing accounts when you turn it on. The security trade-off described there still applies. On a self-managed instance, email_verified is only as trustworthy as the instance: its administrators can mark any address verified. Turn on email linking only for an instance whose administrators you trust with your WeftID accounts.
Groups¶
GitLab returns the full paths of the user's groups, such as acme/engineering, in a groups claim. Enter groups as the connection's group claim to sync them. To sync only the groups the user belongs to directly, use groups_direct instead.
Troubleshooting¶
- "The redirect URI included is not valid"
- The URI registered on the GitLab application does not exactly match WeftID's. Copy it again from the connection's Details tab.
- Issuer mismatch when testing a self-managed connection
- The issuer in WeftID differs from the one your instance publishes. Open
https://<your-instance>/.well-known/openid-configurationand copy itsissuervalue into the connection. - "The requested scope is invalid, unknown, or malformed"
- The GitLab application lacks one of the
openid,profile, oremailscopes. Edit the application and add it.