Notifuse supporta il single sign-on (SSO) tramite OpenID 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.
Attenzione
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. Su Notifuse Cloud la chiave è gestita per te e l’SSO è incluso nel piano Business: vedi Su Notifuse Cloud.
Nota
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:
- L’utente fa clic su Accedi con SSO e Notifuse lo reindirizza al tuo IdP.
- L’utente si autentica presso l’IdP (con l’MFA e le policy che applichi lì).
- 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.
Nota
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 più sotto.
Configurazione
OIDC si configura in tre modi, in questo ordine di precedenza:
- Variabili d’ambiente (
OIDC_*): consigliate in produzione, prevalgono sempre. - 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.
- 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. | 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). | false |
Attenzione
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). 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:
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, 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 |
|---|---|
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.
Nota
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
Attenzione
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
- Nella Google Cloud Console, vai in APIs & Services → Credentials → Create credentials → OAuth client ID.
- Scegli Web application.
- In Authorized redirect URIs, aggiungi
https://<your-notifuse-domain>/api/user.oidc.callback. - Copia il Client ID e il Client secret.
- Configura Notifuse:
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
Nota
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).
Keycloak
- Nel tuo realm, crea un client: Client type OpenID Connect, Client authentication ON (confidenziale), Standard flow attivo.
- Imposta Valid redirect URIs su
https://<your-notifuse-domain>/api/user.oidc.callback. - Copia il secret dalla scheda Credentials del client.
- Configura Notifuse:
OIDC_ENABLED=true
OIDC_ISSUER_URL=https://keycloak.example.com/realms/<your-realm>
OIDC_CLIENT_ID=notifuse
OIDC_CLIENT_SECRET=your-client-secret
Suggerimento
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_ENABLEDe 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
HttpOnlycifrato 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), 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); 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. |
Nota
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.
