Skip to content
downpipes docs

Sign in to downpipes with GitLab

downpipes signs in a person who holds a role, an invite or a mapped group against GitLab over OpenID Connect. This works whether you run on GitLab.com or your own self-managed or Dedicated host. You register one Application at GitLab, then paste your GitLab host, the application id and the secret into the console. The shared add-a-connection mechanics and the pre-save test live on Connect OIDC or OAuth2.

What you need

  • A GitLab account where you can create an Application at the level you want, whether your own user, a group, or the instance for a self-managed admin.
  • Owner access to the downpipes console, since connection management is owner-only and asks for a step-up sign-in.

Set it up

  1. Decide where to register the Application: your user, a group, or (self-managed) the instance. The owner decides who manages it, not who can sign in.
  2. Open the matching Applications page. For a user it is your avatar, then Edit profile, Access, Applications; for a group it is the group Settings, Applications; for the instance it is the Admin area, Applications.
  3. Enter a Name (for example “downpipes”) and set the Redirect URI to your downpipes callback URL, which is your console origin followed by /admin/oidc/callback/<connId>, for example https://console.example.com/admin/oidc/callback/gitlab.
  4. Under Scopes, tick openid, profile and email, then Save application.
  5. Copy the Application ID and Secret.
  6. In the downpipes console, open Govern, Identity providers (the /access/idp screen), choose the GitLab tile and Add a connection. This is owner-only and asks for a step-up sign-in.
  7. Set your GitLab host (gitlab.com by default, or your own host for self-managed), paste the application id and secret, run Test connection, then choose Add GitLab.

Group-to-role mapping

downpipes reads membership from the groups_direct claim in the ID token, which carries your direct group memberships and needs no setup beyond the openid scope. A mapping is also what admits a member: with no invite and no mapped group, the engine refuses a GitLab sign-in. Map a GitLab group onto a downpipes role on Group-to-role mapping. Inherited group memberships and the owner, maintainer and developer roles are not in groups_direct; those are served only at GitLab’s userinfo endpoint, which this ID-token flow does not read.

Good to know

  • groups_direct needs GitLab 16.11 or newer. Older self-managed instances do not emit it, so there is nothing for group mapping to read there.
  • Set your real host for self-managed or Dedicated. Point the connection at your own GitLab host rather than gitlab.com so discovery reads your issuer.
  • Any GitLab.com account can complete a GitLab sign-in. downpipes admits only an account you invite or whose GitLab group you map.
  • Pick the right level before you register, since moving an Application between a user, a group and the instance later means registering it again.

Last updated .