Skip to main content
Notifuse supports Single Sign-On (SSO) via OpenID Connect (OIDC), so your team can sign in with an external identity provider (IdP) such as Google Workspace, Keycloak, Okta, Microsoft Entra ID, Authentik, or Dex. SSO runs alongside the built-in magic-code login — it does not replace it. When SSO is enabled, the sign-in page shows an additional “Sign in with SSO” button next to the email form; either method signs the user into the same account.
SSO needs a licence that includes it (the Enterprise tier). On an installation without one, the Sign in with SSO button is not offered, however SSO is configured — everyone signs in with a login code instead. Nobody is locked out: every SSO account carries a verified email address, login-code sign-in always works, and sessions already open are unaffected. The startup log says sso_gated=true when this applies, and Settings → System says so next to the switch. Installing a licence that includes SSO brings the button back immediately, with no restart. See Licence keys.
SSO is off by default. Existing deployments that don’t configure it see no change — the sign-in page stays exactly as before, with only the magic-code form.

​
How it works

Notifuse acts as an OIDC Relying Party using the Authorization Code flow with PKCE:
  1. The user clicks Sign in with SSO → Notifuse redirects them to your IdP.
  2. The user authenticates at the IdP (with whatever MFA/policies you enforce there).
  3. The IdP redirects back to …/api/user.oidc.callback; Notifuse verifies the ID token server-side (signature, issuer, audience, nonce, expiry) and signs the user in.
The IdP’s tokens are exchanged and verified entirely on the server — only Notifuse’s own session token ever reaches the browser. PKCE is always enabled, and the client secret is never exposed to the frontend.
Login is not the same as workspace access. A successful SSO login authenticates the user; it does not grant access to any workspace. SSO users still need a workspace invitation (or to be a ROOT_EMAIL) before they can do anything. See Provisioning below.

​
Configuration

OIDC can be configured three ways, in this precedence order:
  1. Environment variables (OIDC_*) — recommended for production; these always win.
  2. Setup Wizard — an optional SSO step on first launch.
  3. Settings → SSO — an admin drawer in the console after install.
When a value is set via an environment variable, the matching field is shown as read-only in the wizard/settings UI. Saving OIDC settings from the UI triggers a graceful server restart to reload the configuration (the same behavior as SMTP settings). The client secret is encrypted at rest in the database.

​
Environment variables

When OIDC_ENABLED=true, the server validates the configuration at startup and fails fast on an invalid one (missing issuer/client/secret, a non-https issuer, or auto-create with no allowlist). The same validation runs before the Settings drawer saves, so a bad config is rejected with an error rather than persisted.

​
Provisioning

By default, SSO is invited-users-only: a user can sign in with SSO only if they already have a Notifuse account or have been invited to a workspace (see Invited users). An SSO login for an address nobody invited is rejected with a “no account” message. This preserves Notifuse’s no-self-signup model. To let new users be created automatically on first SSO login, set:
With auto-create on, an account is created on first login when the IdP asserts a verified email and its domain is in OIDC_ALLOWED_DOMAINS. Even then, the new user has no workspace access until invited. An address with an invitation waiting follows the Invited users rules instead, both ways: the invitation can create the account outside the allowlist, and a provider that is not authoritative for the address creates none.

​
Invited users

An invitee doesn’t need to open the emailed link before signing in with SSO. On their first SSO login, a pending invitation to their address creates their account — in invited-only mode, and even when their domain is not in OIDC_ALLOWED_DOMAINS, since an invitation is an owner’s explicit choice of that one address. The invitation is not accepted for them: they land on the workspace list, under Pending invitations, and click Join. That only happens when your identity provider is authoritative for the address, because joining from the console relies on the address the provider asserts: When the provider is not authoritative, SSO creates no account for an invited address — not even with OIDC_AUTO_CREATE_USERS — and the invitee opens the link in their invitation email instead. Once they have accepted it, SSO works for them from then on.
Users are matched by the durable (issuer, subject) pair from the IdP, not by email — so a user keeps the same account even if their email changes at the IdP. Email is used only on first login: to link an SSO identity to an existing account, or to find the invitations waiting for that address. A ROOT_EMAIL account can never be auto-linked to an external identity (a safeguard against platform-admin takeover).

​
Identity provider setup

The callback/redirect URL to register at every provider is:
The redirect URI must match byte-for-byte between your IdP and Notifuse. If you run behind a reverse proxy that rewrites the scheme or host, set OIDC_REDIRECT_URI explicitly to the externally-visible URL — otherwise the IdP returns a redirect_uri_mismatch error.

​
Google Workspace

  1. In the Google Cloud Console, go to APIs & Services → Credentials → Create credentials → OAuth client ID.
  2. Choose Web application.
  3. Under Authorized redirect URIs, add https://<your-notifuse-domain>/api/user.oidc.callback.
  4. Copy the Client ID and Client secret.
  5. Configure Notifuse:
Personal @gmail.com accounts and your Workspace accounts share the accounts.google.com issuer. Use OIDC_ALLOWED_DOMAINS (or keep the default invited-only mode) to restrict sign-in to your organization. A @gmail.com address you have invited can still sign in — see Invited users.

​
Keycloak

  1. In your realm, create a client: Client type OpenID Connect, Client authentication ON (confidential), Standard flow enabled.
  2. Set Valid redirect URIs to https://<your-notifuse-domain>/api/user.oidc.callback.
  3. Copy the secret from the client’s Credentials tab.
  4. Configure Notifuse:
The default Keycloak client scopes already emit email, email_verified, name, and sub. If someone has stripped the email mapper from your client, SSO logins will be rejected (no email claim) — re-add the built-in email scope.

​
Other providers

Any OpenID-Connect–certified provider works the same way — set OIDC_ISSUER_URL to the provider’s issuer, register the redirect URI, and supply the client ID/secret. This includes Okta, Microsoft Entra ID (Azure AD), Authentik, and Dex.

​
Security notes

  • Only two non-secret values reach the browser: window.OIDC_ENABLED and the button label. The client ID, client secret, and issuer URL are never exposed in the page.
  • ID tokens are verified with the issuer’s published keys (auto-rotated via JWKS); signature, issuer, audience, nonce, and expiry are all checked, and only asymmetric algorithms (RS256/ES256) are accepted.
  • The flow’s CSRF/nonce/PKCE state is held in a short-lived, encrypted, HttpOnly cookie.
  • OIDC HTTP calls (discovery, key fetch, token exchange) are time-bounded, so a slow or unreachable issuer cannot stall the sign-in path; magic-code login is unaffected.

​
Troubleshooting

Running multiple Notifuse replicas behind a load balancer? The one-time code used to complete the SSO handoff is held per-instance, so enable sticky sessions for SSO to work reliably across replicas. Single-instance deployments need no extra configuration.