Single sign-on (OIDC)

EE signs users in through any OpenID Connect provider — Keycloak, Authentik, Entra ID, Google Workspace and anything else that speaks OIDC discovery.

Setup

Create a client at the identity provider (Authorization Code flow, confidential) and register the callback address:

https://dns.example.com/api/v1/auth/sso/callback

Then configure the instance:

DNSE_SSO_ISSUER=https://id.example.com/realms/firma
DNSE_SSO_CLIENT_ID=dns-editor
DNSE_SSO_CLIENT_SECRET=…
DNSE_SSO_REDIRECT_URL=https://dns.example.com/api/v1/auth/sso/callback
DNSE_SSO_AUTOPROVISION=on          # default

All four of the first variables must be set. If one is missing, SSO simply stays off — there is no half-active state. When it is active, GET /api/v1/instance reports it with sso: true, and the login form additionally shows Sign in with SSO.

Flow

1. The user clicks Sign in with SSO (/api/v1/auth/sso/login).
2. Redirect to the identity provider — Authorization Code with PKCE; state and verifier live in short-lived HttpOnly cookies (10 minutes).
3. After signing in, return to the callback address, verification of state and ID token.
4. Matching to the account by email address, falling back to the username.
5. Return to the interface with the session token in the URL fragment: https://dns.example.com/#token=…. The interface takes it, cleans up the address bar and sends it as Authorization: Bearer from then on.
6. From here on, a perfectly normal session runs — all permissions come from roles and project memberships as usual.

Why the fragment of all things?

Now that the login travels in a header (no more cookie), a redirect can no longer simply set it — the identity provider sends the browser back, and a redirect knows no headers.

That leaves fragment or query string. The fragment wins because a browser never sends anything after # to a server. The token therefore appears in no access log, no referrer and no proxy log. In the query string it would appear in all three.

The short-lived handshake cookies (state, verifier, 10 minutes) stay cookies — they carry no login, they only bind the one running exchange to the browser that started it.

The provider’s metadata (discovery) is fetched on first use, not at startup: a temporarily unreachable identity provider does not prevent the instance from starting.

Auto-provisioning

With DNSE_SSO_AUTOPROVISION=on (default), an account is automatically created for an unknown identity confirmed by the provider — with an unusable random password, so only the SSO path works. New accounts get the normal user role; the administrator then grants permissions through projects and teams.

With DNSE_SSO_AUTOPROVISION=off, an unknown identity is rejected (HTTP 403). This is the way to go when accounts are to be created up front in a controlled manner.

Interplay with local accounts

SSO does not replace local login — both paths exist side by side. That is deliberate and stays that way: an administrator can still get in even when the identity provider is down.

Two-factor login applies to the local login path. With SSO, the identity provider is responsible for a second factor.