Skip to content
downpipes docs

Connect an OAuth2 provider without an ID token

The Generic OAuth2 preset is for any OAuth2 provider that issues no ID token, such as Discord, Bitbucket or GitLab’s OAuth mode. There is no signed token to verify, so trust comes from the TLS-protected token exchange and identity from an authenticated userinfo call keyed on an immutable id. Sign-in needs an email address, so you also tell the preset where the provider returns it, as Email address explains. Groups come from an optional endpoint, as Group-to-role mapping explains. The shared add-a-connection mechanics and the pre-save test live on Connect OIDC or OAuth2.

What you need

  • An OAuth2 provider where you can register an application, plus its authorisation, token and userinfo endpoints from its API docs.
  • The endpoint that returns the person’s email address, and the scopes the provider needs to return it.
  • Engine 0.3.6 or later. An older engine gives this preset no email fields, so it cannot complete a sign-in.
  • Owner access to the downpipes console, since connection management is owner-only and asks for a step-up sign-in.

Set it up

  1. In your provider, register a new OAuth 2.0 application.
  2. 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/generic-oauth2, which is the id the form pre-fills for this preset.
  3. From the provider’s API docs, copy the authorisation URL, the token URL, the API base URL and a userinfo (profile) URL.
  4. Find the field in the profile response that holds the person’s immutable id (often id), and note its name.
  5. Find the endpoint that returns the person’s email address and the name of its email field. This can be the userinfo URL. Note the scopes the provider needs to return the email.
  6. In the downpipes console, open Govern, Identity providers (the /access/idp screen), choose the Generic OAuth2 tile and Add a connection. This is owner-only and asks for a step-up sign-in.
  7. Paste the endpoints and the immutable-id field name. Enter the scopes, separated by spaces, the Email URL and the Email field. Enter the client id and secret, run Test connection, then Add the connection. The test checks that the Email URL and the Groups URL are usable https URLs, and it fails when the Email URL is empty. It does not call the email endpoint, so the email field names are first used at sign-in.

Email address

This preset keys the person on the immutable id field you named. It reads the email address from the Email URL:

  • With an Email field, the engine reads that field from the response. If you also set the Email-verified field, the engine uses the email only when that field is true. With no Email-verified field, the engine trusts the email the provider returns.
  • With no Email field, the Email URL must return a list of {email, primary, verified} entries, as GitHub does. The engine uses the entry that is both primary and verified.

The engine refuses a sign-in that carries no email, with the reason “the IdP asserted no usable email; grant the email scope on this connection”. Without an Email URL, a connection cannot complete a sign-in.

Group-to-role mapping

For group-to-role mapping, set the Groups URL to an endpoint that returns a list. Set the Group name field to the field that holds each group’s name. An entry in the GitHub team or organisation shape is read as GitHub’s entries are. With no Groups URL, the connection carries no groups.

Good to know

  • Name the immutable id, never a username. Use the numeric or opaque id the provider guarantees is stable, so renaming a user never loses their access.
  • There is no token signature to check. Trust comes from the TLS-protected token exchange, and the access token is used only as a bearer credential against the provider’s own API, never decoded as a claim source.

Last updated .