Skip to main content

Configure global SSO

Single sign-on for the whole install — one IdP, every user. Configured by a super-admin at Admin → Settings → Global SSO. Per-org SSO is a separate path; see Configure per-org SSO.

When to use global SSO:

  • Single-tenant deployment — one customer owns the whole platform, manages every org from one place. The IdP authenticates every user; org membership + role come from IdP groups via the org-role assignment grid.
  • Mixed tenancy — some orgs have their own SSO, others don't. Global SSO is the fallback for the orgs without per-org SSO and for super-admin break-glass.

Steps​

  1. Open the form. Admin → Settings → Global SSO. If the block is collapsed, click the header.

  2. Fill in IdP details:

    • Issuer URL — the IdP's OIDC discovery base (e.g. https://acme.eu.auth0.com/). The form runs a discovery check on Save and refuses if the URL doesn't serve /.well-known/openid-configuration.
    • Client ID — from the IdP application you created for dtedge.
    • Client secret — paste the new value. Stored AES-encrypted at rest; the form shows (stored — leave blank to keep) on subsequent edits.
    • Scopes — defaults openid profile email; add groups when the IdP needs an explicit scope to ship groups.
    • Claim mappings — override the standard claim names if your IdP uses non-standard ones (Auth0 namespacing, Azure roles, etc.). Empty = standard email / name / groups.

  3. Choose policy toggles:

    • Auto-provision — first-time SSO user creates a fresh dtedge user record.
    • Default role — required when auto-provision is on; the role the new user gets in the org. (Less relevant for global SSO — the org-role assignment grid usually drives it.)
    • Require SSO — disables local password login for every non-super-admin user across the install. Use this when the IdP is the only intended path in. Super-admins always keep local as a break-glass.

  4. Org-role assignments (optional but high-value). Rows of (IdP group → org → role). On every SSO login the user's membership is reconciled: added to orgs whose IdP group they're in, removed from orgs they're not. Manual memberships outside the grid stay untouched.

    Example:

    acme-admins      → Acme    → admin
    acme-engineers   → Acme    → editor
    bortech-viewers  → BorTech → viewer

    See Manage global org-role assignments for the full row-by-row workflow.

  5. Save. The form runs:

    • PingIssuer (discovery URL must respond)
    • Validation of each org-role assignment row (org must exist; role must exist in that org)

    If validation fails, the response toast names the offending row. Common errors:

    • GLOBAL_SSO_ASSIGNMENT_UNKNOWN_ORG — the org was deleted or the UUID was hand-edited
    • GLOBAL_SSO_ASSIGNMENT_UNKNOWN_ROLE — the role doesn't exist in that org's role catalog

Verifying​

After Save:

  1. Open an incognito tab → /login → click Sign in with SSO.
  2. Enter the org slug (or leave blank for global). The form posts to /api/auth/discovery and shows the SSO button.
  3. Click it. You go through the IdP. After successful login, you land in the dtedge dashboard.
  4. Backend logs at INFO show: 
    sso callback claims has_groups=true groups=[admin editor]
    sso group reconcile added role role=admin

Troubleshooting​

SymptomCause
Save returns ISSUER_UNREACHABLETypo in the issuer URL, or the dtedge pod can't reach it (egress firewall, internal-only IdP).
Login lands on /sso/error with "NOT_PROVISIONED"Auto-provision is off and the user hasn't been pre-invited. Turn auto-provision on or invite the user first.
User logs in but has no roleEither default_role is empty (and no group matches the assignment grid), or the IdP isn't shipping groups. Backend log shows has_groups=false in the second case.
Roles disappear on every loginGroup→role mapping is configured but the IdP stopped shipping the groups claim. dtedge skips reconcile in that case as of the HasGroupsClaim fix — but if you see roles getting revoked, confirm has_groups=true in the backend log.
Local password login refused with SSO_REQUIREDYou turned Require SSO on. Use the SSO path or, if you're a super-admin and locked out, fall back to local password (super-admins are exempt).

See also​