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 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 (created via the setup root, a workspace invitation, or the API). An SSO login for an unknown email is rejected with a “no account — ask to be invited” 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 only 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.
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 to link an SSO identity to an existing invited account on first login. 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.

​
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.