Skip to content
downpipes docs

Sign in to downpipes with Microsoft Entra ID

downpipes signs people in to the console against Microsoft Entra ID over OpenID Connect. You create one app registration, paste your directory (tenant) id, and add a client secret and the redirect URI. The preset uses the v2.0 endpoints, so the issuer ends in /v2.0. The shared add-a-connection mechanics and the pre-save test live on Connect OIDC or OAuth2.

What you need

  • Microsoft Entra admin access with rights to create an app registration and a client secret.
  • 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 Microsoft Entra admin center, open App registrations, then New registration. Name it (for example “downpipes”), choose the single-tenant option (this directory only), and Register.
  2. Open Manage, Authentication, Add a platform, choose Web, and 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/entra, then Configure.
  3. Open Certificates and secrets, Client secrets, New client secret, then copy the secret Value immediately. Copy the Value, not the Secret ID, and it is hidden once you leave the page.
  4. From the Overview pane, copy the Application (client) ID and the Directory (tenant) ID.
  5. In the downpipes console, open the external identity providers screen (/access/idp), choose the Microsoft Entra ID tile and Add a connection. This is owner-only and asks for a step-up sign-in.
  6. Paste the tenant id, client id and secret, run Test connection, then Add the connection.

Group-to-role mapping

Entra carries authorisation through App Roles, which surface in the signed roles claim of the ID token. On the app registration, open App roles, Create app role, set Allowed member types to Users/Groups and a Value (the role name downpipes matches, for example admin). Then open Enterprise applications, your downpipes app, Users and groups, and assign a user or group to that role; the Value then arrives in the roles claim. Map each App Role value onto a downpipes role on Group-to-role mapping. App Roles are the recommended path over raw group object-ids: they avoid the overflow that hits past about 200 groups and the problem of matching GUIDs back to names.

Good to know

  • Copy the secret Value, not the Secret ID. The Value is shown only once and it expires (24 months at most), so set a renewal reminder.
  • Assigning a group to a role needs Entra ID P1 or P2. Assigning individual users to an App Role does not, so you can start with user assignments on any tier.
  • The preset uses the v2.0 endpoints, so the issuer ends in /v2.0; do not use the v1.0 sts.windows.net issuer.
  • A person with no assigned App Role still signs in, but maps to the viewer floor until you assign one.

Last updated .