> ## Documentation Index
> Fetch the complete documentation index at: https://www.notifuse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Single Sign-On (OIDC)

> Let users sign in to Notifuse with your identity provider (Google Workspace, Keycloak, Okta, …) using OpenID Connect, alongside magic-code login.

Notifuse supports **Single Sign-On (SSO)** via [OpenID Connect](https://openid.net/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.

> [!WARNING]
>
> **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](https://www.notifuse.com/docs/self-hosting/licence.md). On Notifuse Cloud the key is managed for you and SSO is included in the Business plan: see [On Notifuse Cloud, including instances still on their earlier terms](https://www.notifuse.com/docs/self-hosting/licence.md#on-notifuse-cloud).

> [!NOTE]
>
> 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.

> [!NOTE]
>
> **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](#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 **Single sign-on** section on first launch, with the redirect URI to register at your IdP and the scopes.
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. In the wizard, setting `OIDC_ENABLED`, `OIDC_ISSUER_URL` or `OIDC_CLIENT_ID` locks the whole section, which then lists the variables set. 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

| Variable                      | Description                                                                                                                                                                                                                                                                                                                                                                                             | Default                     |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| `OIDC_ENABLED`                | Master switch. When `false`/unset, SSO is disabled and the button is hidden.                                                                                                                                                                                                                                                                                                                            | `false`                     |
| `OIDC_ISSUER_URL`             | Your IdP's issuer URL (must be **https**). Notifuse discovers the rest from `<issuer>/.well-known/openid-configuration`. Required when enabled.                                                                                                                                                                                                                                                         | -                           |
| `OIDC_CLIENT_ID`              | OAuth2 client ID from your IdP. Required when enabled.                                                                                                                                                                                                                                                                                                                                                  | -                           |
| `OIDC_CLIENT_SECRET`          | OAuth2 client secret (confidential client). Encrypted at rest; never sent to the browser. Required when enabled.                                                                                                                                                                                                                                                                                        | -                           |
| `OIDC_REDIRECT_URI`           | The callback URL registered at your IdP. If empty, derived as `<API_ENDPOINT>/api/user.oidc.callback`.                                                                                                                                                                                                                                                                                                  | derived from `API_ENDPOINT` |
| `OIDC_SCOPES`                 | Space-separated scopes. `openid` is always included; `email` is required and `profile` supplies the optional display name.                                                                                                                                                                                                                                                                              | `openid email profile`      |
| `OIDC_BUTTON_LABEL`           | Text shown on the sign-in button.                                                                                                                                                                                                                                                                                                                                                                       | `Sign in with SSO`          |
| `OIDC_AUTO_CREATE_USERS`      | Just-in-time provisioning. When `true`, requires `OIDC_ALLOWED_DOMAINS`. See [Provisioning](#provisioning).                                                                                                                                                                                                                                                                                             | `false`                     |
| `OIDC_ALLOWED_DOMAINS`        | Comma/semicolon/space-separated email-domain allowlist that gates auto-creation. **Mandatory** when `OIDC_AUTO_CREATE_USERS=true` (the server refuses to boot otherwise).                                                                                                                                                                                                                               | -                           |
| `OIDC_ALLOW_UNVERIFIED_EMAIL` | Accept an ID token that carries no `email_verified` claim, for providers that never send one (Microsoft Entra ID, Cloudflare Access). On a first sign-in, a token saying `email_verified: false` is refused; an identity already linked to an account signs in by its subject and is not re-checked. An unverified address never counts for a pending invitation — see [Invited users](#invited-users). | `false`                     |

> [!WARNING]
>
> 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](#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:

```bash
OIDC_AUTO_CREATE_USERS=true
OIDC_ALLOWED_DOMAINS=yourcompany.com
```

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](#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:

| Provider           | Authoritative when                                                                                                                                                                                                                                                                                                                         |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Google             | The address ends in `@gmail.com`, or it belongs to a Google Workspace account (the `hd` claim). Google does not vouch for a personal Google account registered with another domain's address.                                                                                                                                              |
| Microsoft Entra ID | The user is a member of your tenant and the ID token carries the optional `xms_edov` claim, set to true. Add it in your app registration under **Token configuration → Add optional claim → ID**. Guests signing in with a personal Microsoft or Google account, or a one-time passcode, do not count: Entra sets `xms_edov` for them too. |
| Any other provider | The ID token carries `email_verified: true`. A provider that brokers others (Keycloak, Dex, Auth0 social connections) vouches for their addresses with its own `email_verified`, so pass it through only for addresses you trust.                                                                                                          |

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.

> [!NOTE]
>
> 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:

```
https://<your-notifuse-domain>/api/user.oidc.callback
```

> [!WARNING]
>
> 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](https://console.cloud.google.com/apis/credentials), 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:

```bash
OIDC_ENABLED=true
OIDC_ISSUER_URL=https://accounts.google.com
OIDC_CLIENT_ID=xxxxxxxx.apps.googleusercontent.com
OIDC_CLIENT_SECRET=your-client-secret
# Restrict to your organization's domain:
OIDC_ALLOWED_DOMAINS=yourcompany.com
```

> [!NOTE]
>
> 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](#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:

```bash
OIDC_ENABLED=true
OIDC_ISSUER_URL=https://keycloak.example.com/realms/<your-realm>
OIDC_CLIENT_ID=notifuse
OIDC_CLIENT_SECRET=your-client-secret
```

> [!TIP]
>
> 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

| Symptom                                                                                          | Cause & fix                                                                                                                                                                                                                                                                                                                                           |
| ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **"Single sign-on is temporarily unavailable"** after clicking SSO                               | Notifuse can't reach or discover the issuer. Verify `OIDC_ISSUER_URL` is correct, reachable from the server, and serves a discovery document. Notifuse retries automatically once the issuer is back.                                                                                                                                                 |
| **"No Notifuse account is linked… If you were invited, open the link in your invitation email"** | The address has no account and nothing SSO can create one from. Either nobody invited it — invite the user, or enable `OIDC_AUTO_CREATE_USERS` with an allowlist — or it has a pending invitation but your provider is not authoritative for the address (see [Invited users](#invited-users)), and the user accepts the invitation through its link. |
| **"Single sign-on cannot create an account for your email domain"**                              | Auto-create is on and the address is outside `OIDC_ALLOWED_DOMAINS`. Add the domain, or invite the user — an invitation overrides the allowlist for that address when your provider is authoritative for it (see [Invited users](#invited-users)); otherwise the user accepts the invitation through its link.                                        |
| **`redirect_uri_mismatch` / `invalid_redirect_uri` at the IdP**                                  | The redirect URI registered at the IdP doesn't exactly match what Notifuse sends. Register `…/api/user.oidc.callback`, and set `OIDC_REDIRECT_URI` if you're behind a proxy that rewrites scheme/host.                                                                                                                                                |
| **The server won't start after enabling OIDC**                                                   | Configuration validation failed. Check that `OIDC_ISSUER_URL` is https and `OIDC_CLIENT_ID`/`OIDC_CLIENT_SECRET` are set, and that `OIDC_ALLOWED_DOMAINS` is non-empty when `OIDC_AUTO_CREATE_USERS=true`.                                                                                                                                            |
| **A user can sign in but can't access any workspace**                                            | Expected — login is not authorization. Invite the user to the relevant workspace (or add them to `ROOT_EMAIL`); a pending invitation shows on their workspace list with a **Join** button.                                                                                                                                                            |

> [!NOTE]
>
> 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.
