> ## 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)

> Permetti agli utenti di accedere a Notifuse con il tuo identity provider (Google Workspace, Keycloak, Okta, …) tramite OpenID Connect, accanto all'accesso con codice magico.

Notifuse supporta il **single sign-on (SSO)** tramite [OpenID Connect](https://openid.net/connect/) (OIDC): il tuo team può accedere con un identity provider (IdP) esterno come Google Workspace, Keycloak, Okta, Microsoft Entra ID, Authentik o Dex.

L'SSO si affianca all'accesso integrato con codice magico, che resta disponibile. Quando l'SSO è attivo, la pagina di accesso mostra un pulsante **"Accedi con SSO"** in più accanto al modulo email; entrambi i metodi fanno entrare l'utente nello stesso account.

> [!WARNING]
>
> **L'SSO richiede una licenza che lo includa** (il livello Enterprise). Su un'installazione senza licenza adatta, il pulsante **Accedi con SSO** non compare, comunque sia configurato l'SSO, e tutti accedono con un codice di accesso. Nessuno resta bloccato fuori: ogni account SSO ha un indirizzo email verificato, l'accesso con codice funziona sempre e le sessioni già aperte non cambiano. In questo caso il log di avvio riporta `sso_gated=true`, e **Impostazioni → Sistema** lo segnala accanto all'interruttore. Installare una licenza che include l'SSO fa ricomparire subito il pulsante, senza riavvio. Vedi [Chiavi di licenza](https://www.notifuse.com/it/docs/self-hosting/licence.md). Su Notifuse Cloud la chiave è gestita per te e l'SSO è incluso nel piano Business: vedi [Su Notifuse Cloud](https://www.notifuse.com/it/docs/self-hosting/licence.md#on-notifuse-cloud).

> [!NOTE]
>
> L'SSO è disattivato per impostazione predefinita. I deployment esistenti che non lo configurano non vedono alcuna differenza: la pagina di accesso resta identica, con il solo modulo per il codice magico.

## Come funziona

Notifuse agisce come _Relying Party_ OIDC con l'**Authorization Code flow con PKCE**:

1. L'utente fa clic su **Accedi con SSO** e Notifuse lo reindirizza al tuo IdP.
2. L'utente si autentica presso l'IdP (con l'MFA e le policy che applichi lì).
3. L'IdP reindirizza a `…/api/user.oidc.callback`; Notifuse verifica l'ID token lato server (firma, issuer, audience, nonce, scadenza) e fa accedere l'utente.

I token dell'IdP vengono scambiati e verificati interamente sul server: al browser arriva solo il token di sessione di Notifuse. PKCE è sempre attivo e il client secret non viene mai esposto al frontend.

> [!NOTE]
>
> **Accedere non equivale ad avere accesso a un workspace.** Un accesso SSO riuscito autentica l'_utente_, ma non dà accesso a nessun workspace. Gli utenti SSO hanno comunque bisogno di un invito a un workspace (o di essere un `ROOT_EMAIL`) prima di poter fare qualsiasi cosa. Vedi [Provisioning](#provisioning) più sotto.

## Configurazione

OIDC si configura in tre modi, in questo ordine di precedenza:

1. **Variabili d'ambiente** (`OIDC_*`): consigliate in produzione, prevalgono sempre.
2. **Procedura guidata di configurazione**: una sezione **Single sign-on** facoltativa al primo avvio, con il redirect URI da registrare presso il tuo IdP e gli scope.
3. **Impostazioni di sistema** → **SSO (OpenID Connect)**: il pannello di amministrazione nel selettore dei workspace della console dopo l'installazione.

Quando un valore è impostato da una variabile d'ambiente, il campo corrispondente appare in sola lettura nella procedura guidata e nelle impostazioni. Nella procedura guidata, impostare `OIDC_ENABLED`, `OIDC_ISSUER_URL` o `OIDC_CLIENT_ID` blocca l'intera sezione, che elenca allora le variabili impostate. Salvare le impostazioni OIDC dall'interfaccia provoca un riavvio controllato del server per ricaricare la configurazione (come per le impostazioni SMTP). Il client secret è cifrato a riposo nel database.

### Variabili d'ambiente

| Variabile                     | Descrizione                                                                                                                                                                                                                                                                                                                                                                                                           | Predefinito                |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| `OIDC_ENABLED`                | Interruttore generale. Se è `false` o non impostata, l'SSO è disattivato e il pulsante è nascosto.                                                                                                                                                                                                                                                                                                                    | `false`                    |
| `OIDC_ISSUER_URL`             | URL dell'issuer del tuo IdP (deve essere **https**). Notifuse ricava il resto da `<issuer>/.well-known/openid-configuration`. Obbligatoria quando l'SSO è attivo.                                                                                                                                                                                                                                                     | -                          |
| `OIDC_CLIENT_ID`              | Client ID OAuth2 fornito dal tuo IdP. Obbligatoria quando l'SSO è attivo.                                                                                                                                                                                                                                                                                                                                             | -                          |
| `OIDC_CLIENT_SECRET`          | Client secret OAuth2 (client confidenziale). Cifrato a riposo, mai inviato al browser. Obbligatoria quando l'SSO è attivo.                                                                                                                                                                                                                                                                                            | -                          |
| `OIDC_REDIRECT_URI`           | L'URL di callback registrato presso il tuo IdP. Se vuoto, è derivato come `<API_ENDPOINT>/api/user.oidc.callback`.                                                                                                                                                                                                                                                                                                    | derivato da `API_ENDPOINT` |
| `OIDC_SCOPES`                 | Scope separati da spazi. `openid` è sempre incluso; `email` è obbligatorio e `profile` fornisce il nome visualizzato facoltativo.                                                                                                                                                                                                                                                                                     | `openid email profile`     |
| `OIDC_BUTTON_LABEL`           | Testo mostrato sul pulsante di accesso.                                                                                                                                                                                                                                                                                                                                                                               | `Sign in with SSO`         |
| `OIDC_AUTO_CREATE_USERS`      | Provisioning just-in-time. Quando è `true`, richiede `OIDC_ALLOWED_DOMAINS`. Vedi [Provisioning](#provisioning).                                                                                                                                                                                                                                                                                                      | `false`                    |
| `OIDC_ALLOWED_DOMAINS`        | Elenco dei domini email autorizzati, separati da virgole, punti e virgola o spazi, che limita la creazione automatica. **Obbligatoria** quando `OIDC_AUTO_CREATE_USERS=true` (altrimenti il server non parte).                                                                                                                                                                                                        | -                          |
| `OIDC_ALLOW_UNVERIFIED_EMAIL` | Accetta un ID token senza claim `email_verified`, per i provider che non lo inviano mai (Microsoft Entra ID, Cloudflare Access). Al primo accesso, un token con `email_verified: false` viene rifiutato; un'identità già collegata a un account accede tramite il suo subject e non viene ricontrollata. Un indirizzo non verificato non conta mai per un invito in sospeso (vedi [Utenti invitati](#invited-users)). | `false`                    |

> [!WARNING]
>
> Quando `OIDC_ENABLED=true`, il server convalida la configurazione all'avvio e si ferma subito se non è valida (issuer, client o secret mancanti, un issuer non https, oppure la creazione automatica senza elenco di domini). La stessa convalida avviene prima del salvataggio dal pannello delle impostazioni, quindi una configurazione errata viene respinta con un errore invece di essere salvata.

## Provisioning

Per impostazione predefinita l'SSO è **riservato agli utenti invitati**: un utente può accedere con SSO solo se ha già un account Notifuse o è stato invitato a un workspace (vedi [Utenti invitati](#invited-users)). Un accesso SSO per un indirizzo che nessuno ha invitato viene respinto con un messaggio "nessun account". Così resta valido il modello di Notifuse, in cui nessuno si registra da solo.

Per creare automaticamente i nuovi utenti al loro primo accesso SSO, imposta:

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

Con la creazione automatica attiva, al primo accesso viene creato un account quando l'IdP dichiara un'email verificata **e** il suo dominio è in `OIDC_ALLOWED_DOMAINS`. Anche così, il nuovo utente non ha accesso a nessun workspace finché non viene invitato. Un indirizzo con un invito in attesa segue invece le regole degli [Utenti invitati](#invited-users), in entrambi i sensi: l'invito può creare l'account al di fuori dell'elenco dei domini, e un provider non autorevole per l'indirizzo non ne crea nessuno.

### Utenti invitati

Chi è stato invitato non deve aprire il link ricevuto via email prima di accedere con SSO. Al suo primo accesso SSO, un invito in sospeso al suo indirizzo crea il suo account. Succede anche in modalità solo invitati, e anche quando il suo dominio non è in `OIDC_ALLOWED_DOMAINS`, perché un invito è la scelta esplicita di un proprietario per quel singolo indirizzo. L'invito non viene accettato al posto suo: l'utente arriva all'elenco dei workspace, sotto **Inviti in sospeso**, e fa clic su **Unisciti**.

Questo avviene solo quando il tuo identity provider è autorevole per l'indirizzo, perché l'adesione dalla console si basa sull'indirizzo che il provider dichiara:

| Provider                 | Autorevole quando                                                                                                                                                                                                                                                                                                                                            |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Google                   | L'indirizzo termina con `@gmail.com`, oppure appartiene a un account Google Workspace (il claim `hd`). Google non garantisce per un account Google personale registrato con l'indirizzo di un altro dominio.                                                                                                                                                 |
| Microsoft Entra ID       | L'utente è membro del tuo tenant e l'ID token contiene il claim facoltativo `xms_edov` impostato a true. Aggiungilo nella registrazione dell'app in **Token configuration → Add optional claim → ID**. Gli ospiti che accedono con un account Microsoft o Google personale, o con un passcode monouso, non contano: Entra imposta `xms_edov` anche per loro. |
| Qualsiasi altro provider | L'ID token contiene `email_verified: true`. Un provider che fa da intermediario per altri (Keycloak, Dex, le connessioni social di Auth0) garantisce i loro indirizzi con il proprio `email_verified`, quindi trasmettilo solo per indirizzi di cui ti fidi.                                                                                                 |

Quando il provider non è autorevole, l'SSO non crea nessun account per un indirizzo invitato (nemmeno con `OIDC_AUTO_CREATE_USERS`), e la persona invitata apre invece il link nell'email di invito. Una volta accettato l'invito, da quel momento l'SSO funziona anche per lei.

> [!NOTE]
>
> Gli utenti vengono riconosciuti dalla coppia stabile `(issuer, subject)` fornita dall'IdP, non dall'email: un utente mantiene lo stesso account anche se la sua email cambia presso l'IdP. L'email serve solo al primo accesso, per collegare un'identità SSO a un account esistente o per trovare gli inviti in attesa per quell'indirizzo. Un account `ROOT_EMAIL` non può mai essere collegato automaticamente a un'identità esterna (una protezione contro la presa di controllo dell'amministratore della piattaforma).

## Configurazione dell'identity provider

L'URL di callback (redirect) da registrare presso ogni provider è:

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

> [!WARNING]
>
> Il redirect URI deve corrispondere **byte per byte** tra il tuo IdP e Notifuse. Se lavori dietro un reverse proxy che riscrive lo schema o l'host, imposta esplicitamente `OIDC_REDIRECT_URI` con l'URL visibile dall'esterno; altrimenti l'IdP restituisce un errore `redirect_uri_mismatch`.

### Google Workspace

1. Nella [Google Cloud Console](https://console.cloud.google.com/apis/credentials), vai in **APIs & Services → Credentials → Create credentials → OAuth client ID**.
2. Scegli **Web application**.
3. In **Authorized redirect URIs**, aggiungi `https://<your-notifuse-domain>/api/user.oidc.callback`.
4. Copia il **Client ID** e il **Client secret**.
5. Configura 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]
>
> Gli account personali `@gmail.com` e gli account del tuo Workspace condividono l'issuer `accounts.google.com`. Usa `OIDC_ALLOWED_DOMAINS` (o mantieni la modalità predefinita solo invitati) per limitare l'accesso alla tua organizzazione. Un indirizzo `@gmail.com` che hai invitato può comunque accedere (vedi [Utenti invitati](#invited-users)).

### Keycloak

1. Nel tuo realm, crea un client: **Client type** OpenID Connect, **Client authentication** ON (confidenziale), **Standard flow** attivo.
2. Imposta **Valid redirect URIs** su `https://<your-notifuse-domain>/api/user.oidc.callback`.
3. Copia il secret dalla scheda **Credentials** del client.
4. Configura 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]
>
> Gli scope client predefiniti di Keycloak emettono già `email`, `email_verified`, `name` e `sub`. Se qualcuno ha rimosso il mapper dell'email dal tuo client, gli accessi SSO vengono respinti (nessun claim email): aggiungi di nuovo lo scope integrato `email`.

### Altri provider

Qualsiasi provider certificato OpenID Connect funziona allo stesso modo: imposta `OIDC_ISSUER_URL` sull'issuer del provider, registra il redirect URI e fornisci client ID e secret. Tra questi ci sono Okta, Microsoft Entra ID (Azure AD), Authentik e Dex.

## Note sulla sicurezza

- Al browser arrivano solo due valori non segreti: `window.OIDC_ENABLED` e il testo del pulsante. Client ID, client secret e URL dell'issuer non vengono mai esposti nella pagina.
- Gli ID token sono verificati con le chiavi pubblicate dall'issuer (ruotate automaticamente tramite JWKS); firma, issuer, audience, nonce e scadenza vengono tutti controllati, e sono accettati solo algoritmi asimmetrici (RS256/ES256).
- Lo stato CSRF, nonce e PKCE del flusso è conservato in un cookie `HttpOnly` cifrato e di breve durata.
- Le chiamate HTTP di OIDC (discovery, recupero delle chiavi, scambio del token) hanno un limite di tempo: un issuer lento o irraggiungibile non può bloccare l'accesso, e l'accesso con codice magico non ne risente.

## Risoluzione dei problemi

| Sintomo                                                                                                 | Causa e soluzione                                                                                                                                                                                                                                                                                                                                               |
| ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **"Il single sign-on è temporaneamente non disponibile"** dopo il clic su SSO                           | Notifuse non riesce a raggiungere o a rilevare l'issuer. Verifica che `OIDC_ISSUER_URL` sia corretto, raggiungibile dal server e che serva un documento di discovery. Notifuse riprova automaticamente quando l'issuer torna disponibile.                                                                                                                       |
| **"Nessun account Notifuse è collegato… Se hai ricevuto un invito, apri il link nell'email di invito"** | L'indirizzo non ha un account e l'SSO non ha nulla da cui crearne uno. O nessuno l'ha invitato (invita l'utente, oppure attiva `OIDC_AUTO_CREATE_USERS` con un elenco di domini), oppure ha un invito in sospeso ma il tuo provider non è autorevole per l'indirizzo (vedi [Utenti invitati](#invited-users)), e l'utente accetta l'invito tramite il suo link. |
| **"Il single sign-on non può creare un account per il tuo dominio email"**                              | La creazione automatica è attiva e l'indirizzo è fuori da `OIDC_ALLOWED_DOMAINS`. Aggiungi il dominio, oppure invita l'utente: un invito supera l'elenco dei domini per quell'indirizzo quando il tuo provider è autorevole (vedi [Utenti invitati](#invited-users)); altrimenti l'utente accetta l'invito tramite il suo link.                                 |
| **`redirect_uri_mismatch` / `invalid_redirect_uri` presso l'IdP**                                       | Il redirect URI registrato presso l'IdP non corrisponde esattamente a quello inviato da Notifuse. Registra `…/api/user.oidc.callback` e imposta `OIDC_REDIRECT_URI` se sei dietro un proxy che riscrive schema o host.                                                                                                                                          |
| **Il server non parte dopo aver attivato OIDC**                                                         | La convalida della configurazione non è riuscita. Controlla che `OIDC_ISSUER_URL` sia https, che `OIDC_CLIENT_ID` e `OIDC_CLIENT_SECRET` siano impostati e che `OIDC_ALLOWED_DOMAINS` non sia vuota quando `OIDC_AUTO_CREATE_USERS=true`.                                                                                                                       |
| **Un utente riesce ad accedere ma non vede nessun workspace**                                           | È il comportamento previsto: accedere non significa essere autorizzati. Invita l'utente nel workspace giusto (o aggiungilo a `ROOT_EMAIL`); un invito in sospeso compare nel suo elenco dei workspace con un pulsante **Unisciti**.                                                                                                                             |

> [!NOTE]
>
> Hai più repliche di Notifuse dietro un load balancer? Il codice monouso che completa il passaggio SSO è conservato in ogni singola istanza, quindi attiva le **sticky session** perché l'SSO funzioni in modo affidabile tra le repliche. I deployment con una sola istanza non richiedono altra configurazione.
