Skip to main content

Configure per-org SSO

Each organization brings its own IdP that authenticates its own members. Configured at Organizations → <org> → SSO tab. For a single-tenant install with one IdP, see Configure global SSO instead.

When to use per-org SSO​

  • Multi-tenant deployment — each customer org has its own Azure AD / Okta / Keycloak / Auth0 instance.
  • Mixed identity model — some orgs SSO-only, others local- password.
  • Compliance — the org admin wants their IdP audit log to be the source of truth for who accessed dtedge from their tenant.

Steps​

  1. Open the form. Organizations → <org> → SSO tab. You need to be an org admin (or super-admin) for the org.

  2. Fill IdP details:

    • Issuer URL — OIDC discovery base.
    • Client ID + Client secret — from your IdP app.
    • Scopes — openid profile email plus groups if your IdP needs an explicit scope.
    • Claim mappings — defaults match standard OIDC. Override for IdP-specific names (e.g. Auth0 namespaced claims: https://dtedge.io/groups).

  3. Auto-provision (toggle):

    • On: first-time SSO login auto-creates the user and adds them to the org with the default role below.
    • Off: only pre-invited users can SSO in.

  4. Default role: required when auto-provision is on. Pick from the org's existing roles. (UI dropdown is sourced from the org's role catalog.)

  5. Group → role mapping (optional, high-value):

    • Each row: IdP group name → dtedge role in this org.
    • On every SSO login the user's roles in this org are reconciled:
      • Added: roles for groups the user is in
      • Removed: roles for groups they're no longer in (only roles that came from this mapping; manual role assignments stay)
      • The "default role" above stays granted even when no mapping row matches.

    Example:

    acme-admins      → admin
    acme-engineers   → editor
    acme-readonly    → viewer

  6. Require SSO (toggle): when on, members of this org can't use local password to access dtedge. They must go through this IdP. Super-admins keep local as break-glass.

  7. Save. The form validates:

    • PingIssuer — discovery URL responds
    • Each mapping row's role exists in the org's role catalog
    • If auto-provision on, default role exists

    Errors come back with a detail field naming the failing field.

Verifying​

  1. Log out of dtedge.
  2. Open /login → Sign in with SSO → enter the org slug.
  3. The form posts to /api/auth/discovery with the slug. If the org has SSO enabled, you get an oidc button labeled with the IdP.
  4. Click → IdP redirect → callback → dashboard.

Backend log on a successful login:

sso callback claims has_groups=true groups=[acme-admins]
sso group reconcile added role role=admin

SSO setup walkthroughs (per IdP)​

The dtedge form is generic; the IdP-specific knobs (where to set the redirect URI, how to namespace the groups claim, App Roles vs Groups in Entra) are documented in the backend docs:

(URLs depend on your docs deployment — the backend repo's docs/guides/sso-setup/ has the source of truth.)

Troubleshooting​

SymptomCause
Form save fails with ISSUER_UNREACHABLEWrong issuer URL or network blocked.
Save fails with DEFAULT_ROLE_UNKNOWNThe role typed doesn't exist in this org. Create it under Roles tab first.
Save fails with GROUP_ROLE_MAP_UNKNOWNA mapping row's role doesn't exist in this org.
User logs in but lands on "not provisioned"Auto-provision off; user not pre-invited. Or email claim missing on the ID token (IdP scope misconfigured).
User loses admin on every loginMapping is configured but the IdP isn't shipping the groups claim. Backend log: has_groups=false. Fix the IdP scope / Action / mapper.
Org admin can't disable SSOMember tries to delete the SSO config? Check super-admin permissions — some orgs gate SSO config to super-admin only.

What members see​

Once the org has SSO enabled:

  • Members can still go to /login and use local password if Require SSO is off — they pick which path on the login page.
  • If Require SSO is on, members see only the SSO button when they enter the org slug.
  • The Members tab shows each member's SSO status (linked, last IdP login).

See also​