Single sign-on
Warden supports any number of OpenID Connect identity providers. The built-in templates are:
- Google, with Google’s issuer preconfigured.
- OpenID Connect, for Dex, Keycloak, Authentik, Authelia, Okta, Entra ID, and other standards-compliant providers.
Templates only supply provider-specific defaults. Every provider uses the same secure authorization-code flow, storage model, administration API, and login UI, so more templates can be added later without creating another settings system.
Configure a provider
Section titled “Configure a provider”An administrator opens Settings → Security → Identity providers and selects Add provider.
- Choose Google or OpenID Connect and enter the display name shown on the login page.
- For generic OpenID Connect, enter the exact issuer from the provider’s discovery document.
- Save the provider once and copy its final callback URL into the provider’s OAuth/OIDC client.
- Enter the client ID and secret. Optionally restrict access to a comma-separated list of exact email domains.
- Enable auto-provisioning if new verified identities should be created automatically.
- Enable the provider and save.
- Use Test connection to verify OIDC discovery, then complete a real login in a private browser window.
Each provider gets an immutable callback URL:
https://warden.example.com/api/auth/sso/provider-id/callbackThe URI registered at the provider must match the URL shown by Warden exactly, including scheme, hostname, port, path, and provider ID. A new provider starts disabled, and Warden will not enable it without a client ID and secret. Leaving the secret field empty while editing preserves the stored value.
Providers can be added, disabled, removed, or moved up and down. Their order in Settings is their order on the login page. A provider linked to existing users cannot be deleted; disable it instead. This protects account identity and prevents a deleted provider ID from being reused accidentally.
The public login page reads GET /api/auth/sso/providers. It returns only enabled, complete providers in display order, with id, template, and name. Credentials and access rules are never public.
The authenticated administration endpoints require the admin role:
| Method | Path | Purpose |
|---|---|---|
GET | /api/sso/providers | List full provider metadata with secretConfigured, never the secret |
POST | /api/sso/providers | Create a provider or disabled draft |
PUT | /api/sso/providers/{id} | Update a provider; an empty clientSecret preserves the stored secret |
DELETE | /api/sso/providers/{id} | Remove an unlinked provider |
PUT | /api/sso/providers/order | Set the complete order with { "ids": [...] } |
POST | /api/sso/providers/{id}/test | Run OIDC discovery against the stored issuer |
Provider IDs are generated by Warden and cannot be changed. The public authorization and callback routes are /api/auth/sso/{id} and /api/auth/sso/{id}/callback.
Users, passwords, and roles
Section titled “Users, passwords, and roles”Authentication and authorization remain separate:
- The identity provider verifies the person’s password, MFA, and identity.
- Warden verifies the signed ID token, issuer, audience, expiry, nonce, PKCE exchange, and verified email.
- Warden stores the account’s local role and session.
New auto-provisioned SSO users always start as viewer. An existing Warden administrator changes the role under Settings → Users. Signing in again does not overwrite that role, and provider groups or claims do not grant Warden permissions automatically.
| Role | Access |
|---|---|
admin | Full access, including identity providers, users, and role assignment |
editor | Can change operational resources but cannot administer security or users |
viewer | Read-only dashboard access; default for new SSO users |
status_viewer | Only explicitly assigned status pages |
SSO users do not have a Warden password. Password changes, resets, MFA, and disabling the upstream identity belong to the identity provider. Warden hides password controls for SSO accounts and rejects attempts to add a local password to them. Local accounts continue using their Warden username and password and provide a recovery path if an identity provider is unavailable.
When auto-provisioning is disabled, identities already linked to Warden can still sign in, but unknown identities are rejected.
Existing email behavior
Section titled “Existing email behavior”A matching email alone is not enough to merge a local password account with an external identity.
| Existing account | Incoming identity | Result |
|---|---|---|
| Same provider ID and subject | Same identity | Signs in and preserves the Warden role |
| Local password account with the same email | Any SSO provider | Rejected; explicit account linking is required |
| SSO-only account with the same email | A different configured provider | Relinked to the new provider and existing role preserved |
| No matching account | Auto-provisioning enabled | Created as viewer |
| No matching account | Auto-provisioning disabled | Rejected |
Manual account linking is intentionally deferred. Until that flow exists, do not pre-create a password account for a person expected to use SSO. Let them complete the first SSO login, then assign their Warden role.
Google template
Section titled “Google template”Create an OAuth 2.0 Web application in Google Cloud, register the callback URL shown by Warden, and enter its client ID and secret. The template uses https://accounts.google.com as the issuer. If allowed domains are configured, Warden also sends the first domain as Google’s hd login hint, but still enforces the complete allowlist itself after token verification.
If Google’s consent screen is in testing mode, add each tester as a test user before exercising the flow.
Generic OpenID Connect template
Section titled “Generic OpenID Connect template”Use the exact issuer published by the provider. Warden discovers its authorization, token, and signing-key endpoints and requests openid, profile, and email. The provider must return a stable subject and a verified email claim.
LDAP is supported through an OIDC bridge such as Keycloak or Authentik; Warden does not bind directly to LDAP or store directory credentials.
Safe validation checklist
Section titled “Safe validation checklist”Keep a working administrator session open while testing in a private browser window.
- Confirm Test connection succeeds.
- Enable one provider and verify its button appears in the configured position.
- Complete a login with an allowed, verified account and confirm the new user is a viewer.
- Change that user to editor or admin in Settings → Users, sign in again, and confirm the role remains.
- Configure a domain that excludes the test account and confirm Warden rejects it without creating a session.
- Disable auto-provisioning and confirm an unknown identity is rejected while an existing linked identity still works.
- Disable the provider and confirm its button disappears without deleting users or existing sessions.
- Verify the administrator’s local password login still works.
Testing discovery does not validate the complete login. A production smoke test must follow the browser redirect, authenticate at the provider, return through the callback, and create a Warden session.