Skip to content
downpipes docs

Sign in to downpipes with Keycloak

downpipes signs people in to the console against a Keycloak realm over OpenID Connect. You point the connection at your realm, whose issuer is https://<host>/realms/<realm>, and register one confidential client. The shared add-a-connection mechanics and the pre-save test live on Connect OIDC or OAuth2. This page covers the downpipes + Keycloak specifics: the realm settings and mapper toggles unique to this provider.

What you need

  • Keycloak Admin Console access to the realm downpipes should use, with rights to create a client.
  • 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 the Keycloak Admin Console, select the realm downpipes should use from the realm selector at the top left.
  2. Open Clients, Create client, set Client type to OpenID Connect and a Client ID (for example “downpipes”), then Next.
  3. On Capability config, turn Client authentication On (this makes the client confidential), keep Standard flow enabled, then Next.
  4. On Login settings, set Valid redirect URIs 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/keycloak, then Save.
  5. Open the Credentials tab and copy the Client secret, and copy the Client ID from the Settings tab.
  6. In the downpipes console, open the external identity providers screen (/access/idp), choose the Keycloak tile and Add a connection. This is owner-only and asks for a step-up sign-in.
  7. Enter your Keycloak host and realm, paste the client id and secret, run Test connection, then Add the connection.

Group-to-role mapping

Keycloak puts roles and groups in the access token only by default, and this engine verifies the ID token, so you turn on Add to ID token for the mappers you want downpipes to read. On the client’s dedicated scope, add a Group Membership mapper with Token Claim Name groups and Full group path Off, and set Add to ID token On. For roles, set Add to ID token On for the realm-roles mapper too. Then map a Keycloak group or role onto a downpipes role on Group-to-role mapping. Keeping Full group path Off means the claim carries plain group names, which is what downpipes maps on, rather than /parent/child paths.

Good to know

  • Turn Add to ID token On, or no roles or groups arrive. By default Keycloak emits them in the access token only, so sign-in works but mapping finds nothing until you toggle the mappers.
  • Use the modern path, not /auth. Recent Keycloak serves /realms/<realm>; only legacy installs before version 17 (and RH-SSO) use /auth/realms, so do not put /auth in the host.
  • This preset accepts RS256 and ES256 ID-token signatures, so confirm your realm’s active signing key uses one of them.
  • Keep Full group path Off so the groups claim carries plain names rather than full /parent/child paths, because downpipes maps on names.
  • See how native SSO fits into a downpipe’s overall security model on the downpipes security page.

Last updated .