Skip to content
downpipes docs

Sign in to downpipes with GitLab

downpipes signs people in to the console against GitLab over OpenID Connect, 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. A user Application authenticates only you, a group Application suits a team, and an instance Application is for a self-managed admin.
  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 the external identity providers screen (/access/idp), 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 Add the connection.

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. 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.
  • The Application owner decides who can sign in: a user Application authenticates only that user, a group Application suits a team, and an instance Application is self-managed admin only.
  • 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 .