Skip to content
downpipes docs

Sign in to downpipes with Okta

downpipes signs people in to the console against Okta over OpenID Connect. You paste your Okta domain and the authorisation server id, and register one OIDC Web app. The shared add-a-connection mechanics and the pre-save test live on Connect OIDC or OAuth2.

What you need

  • An Okta Admin Console account that can create an app integration and edit a custom authorisation server.
  • 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 Okta Admin Console, open Applications, Applications, Create App Integration, choose OIDC - OpenID Connect, then Web Application, and Next.
  2. Name it (for example “downpipes”) and set Sign-in 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/okta.
  3. Under Assignments, assign the app to the users or groups who may sign in, then Save. An unassigned user is refused at Okta before the engine sees the sign-in.
  4. On the app’s General tab, copy the Client ID and Client secret from Client Credentials.
  5. In the downpipes console, open the external identity providers screen (/access/idp), choose the Okta tile and Add a connection. This is owner-only and asks for a step-up sign-in.
  6. Enter your Okta domain and the Authorization server id (default unless you use another), paste the client id and secret, run Test connection, then Add the connection.

Group-to-role mapping

Okta emits groups through a groups claim that you configure on a custom authorisation server; the org default server cannot emit custom claims, which is why the issuer ends in /oauth2/default. In the Okta console open Security, API, Authorization Servers, open the default server, then Claims, Add Claim. Name it groups, set Include in token type to ID Token and Always, Value type to Groups, and Filter to Matches regex .*, then Create. Then map an Okta group onto a downpipes role on Group-to-role mapping.

Good to know

  • A claim returns at most 100 groups. If more groups match the filter the token request fails, so narrow the regex or use a tighter filter for a large directory.
  • Match the client authentication method. This engine uses client_secret_post; Okta web apps default to client_secret_basic, so set the app to match or the token call returns a 401.
  • The org default server does not emit a groups claim, so use a custom authorisation server (the built-in one named default works).
  • Assign the app to the right users or groups in Okta, because an unassigned user is turned away at Okta before downpipes is involved.

Last updated .