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. 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.
  • 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/oauth2.
  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. In the downpipes console, open the external identity providers screen (/access/idp), choose the Generic OAuth2 tile and Add a connection. This is owner-only and asks for a step-up sign-in.
  6. Paste the endpoints, the immutable-id field name, the client id and secret, run Test connection, then Add the connection.

Group-to-role mapping

Group mapping depends on the provider’s own API, so downpipes signs the person in from the profile response and keys on the immutable id field you named. Where the provider exposes membership through its API, map a value onto a downpipes role on Group-to-role mapping. For a provider that exposes no membership, this stays sign-in only, with roles assigned per person inside downpipes.

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 .