Skip to content
downpipes docs

Connect any OpenID Connect provider

The Generic OIDC preset connects any provider that publishes a spec-compliant /.well-known/openid-configuration, for providers without a named tile here, including PingOne, OneLogin, Authentik, Zitadel and Curity. You point it at your issuer and supply the client id and secret. The shared add-a-connection mechanics and the pre-save test live on Connect OIDC or OAuth2.

If your identity provider issues only an access token with no ID token, use the Generic OAuth2 integration instead of this page.

What you need

  • An OpenID Connect provider where you can register a confidential web client, plus its issuer URL.
  • 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 identity provider, register a new OpenID Connect application as a confidential web client.
  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/oidc.
  3. Enable the authorisation-code flow with PKCE and the openid, email and profile scopes.
  4. Copy the issuer URL (the base that serves /.well-known/openid-configuration), the client id and the client secret.
  5. In the downpipes console, open the external identity providers screen (/access/idp), choose the Generic OIDC tile and Add a connection. This is owner-only and asks for a step-up sign-in.
  6. Paste the issuer, client id and secret, set the groups or roles claim name if your provider emits one, run Test connection, then Add the connection.

Group-to-role mapping

If your provider can put a groups or roles array in the ID token, set that claim’s name on the connection, then map a value onto a downpipes role on Group-to-role mapping. Because the engine verifies the ID token, make sure the claim is in the ID token itself, not only in the access token or at the userinfo endpoint. Leave the claim name blank for sign-in only, with roles assigned per person inside downpipes.

Good to know

  • The issuer must match its tokens exactly. It has to serve /.well-known/openid-configuration over HTTPS and match the iss value in the tokens it signs, character for character.
  • The issuer also decides where the engine will fetch keys, so it is screened. Discovery, the JWKS key fetch and the token exchange must all be https, and the host may not be an IP literal, localhost, or a .localhost name, with a further classifier for IPv6 unique-local, link-local and obfuscated forms. Redirects are never followed, so an endpoint answering a 3xx towards a metadata address or a private range is refused rather than chased. This matters more on this preset than on a named one, because here you type the issuer yourself. See connect an OIDC provider.
  • Named presets are easier where one fits. This preset absorbs PingOne, OneLogin, Authentik, Zitadel, Curity and similar; use a named provider tile instead if your provider has one.
  • This preset accepts RS256 and ES256 ID-token signatures, so confirm your provider signs with one of them.
  • Put the groups or roles claim in the ID token, since this flow reads the ID token and does not call the userinfo endpoint for membership.

Last updated .