Aller au contenu

Auto-hébergement

Authentification unique (OIDC)

Permettre aux utilisateurs de se connecter à Notifuse avec votre fournisseur d'identité (Google Workspace, Keycloak, Okta, …) via OpenID Connect, en plus de la connexion par code magique.

Notifuse prend en charge l’Authentification unique (SSO) via OpenID Connect (OIDC) : votre équipe peut se connecter avec un fournisseur d’identité externe (IdP) comme Google Workspace, Keycloak, Okta, Microsoft Entra ID, Authentik ou Dex.

Le SSO fonctionne à côté de la connexion par code magique intégrée, sans la remplacer. Quand le SSO est activé, la page de connexion affiche un bouton “Se connecter avec le SSO” à côté du formulaire d’email. Les deux méthodes connectent l’utilisateur au même compte.

Attention

Le SSO demande une licence qui l’inclut (le niveau Enterprise). Sur une installation qui n’en a pas, le bouton Se connecter avec le SSO n’est pas proposé, quelle que soit la configuration du SSO, et tout le monde se connecte avec un code. Personne n’est bloqué : chaque compte SSO a une adresse email vérifiée, la connexion par code fonctionne toujours, et les sessions déjà ouvertes ne sont pas touchées. Dans ce cas, le log de démarrage indique sso_gated=true, et Paramètres → Système le signale à côté de l’interrupteur. Installer une licence qui inclut le SSO fait revenir le bouton tout de suite, sans redémarrage. Voir Clés de licence. Sur Notifuse Cloud, la clé est gérée pour vous et le SSO fait partie de l’offre Business : voir Sur Notifuse Cloud.

Note

Le SSO est désactivé par défaut. Pour les déploiements existants qui ne le configurent pas, rien ne change : la page de connexion reste la même, avec seulement le formulaire de code magique.

Fonctionnement

Notifuse joue le rôle de Relying Party OIDC et utilise le flux Authorization Code avec PKCE :

  1. L’utilisateur clique sur Se connecter avec le SSO, et Notifuse le redirige vers votre IdP.
  2. L’utilisateur s’authentifie auprès de l’IdP (avec les règles et la MFA que vous y imposez).
  3. L’IdP le renvoie vers …/api/user.oidc.callback. Notifuse vérifie l’ID token côté serveur (signature, émetteur, audience, nonce, expiration) et connecte l’utilisateur.

Les tokens de l’IdP sont échangés et vérifiés entièrement sur le serveur : seul le token de session de Notifuse arrive jusqu’au navigateur. PKCE est toujours activé, et le client secret n’est jamais exposé au frontend.

Note

Se connecter ne donne pas accès à un espace de travail. Une connexion SSO réussie authentifie l’utilisateur, sans lui ouvrir aucun espace de travail. Un utilisateur SSO a encore besoin d’une invitation à un espace de travail (ou d’être un ROOT_EMAIL) pour faire quoi que ce soit. Voir Provisionnement plus bas.

Configuration

OIDC se configure de trois façons, par ordre de priorité :

  1. Variables d’environnement (OIDC_*) : recommandées en production, elles l’emportent toujours.
  2. Assistant d’installation : une section facultative Authentification unique (SSO) au premier lancement, avec l’URI de redirection à enregistrer chez votre IdP et les scopes.
  3. Paramètres système → SSO (OpenID Connect) : le panneau d’administration sur le sélecteur d’espace de travail dans la console, après l’installation.

Quand une valeur est définie par une variable d’environnement, le champ correspondant apparaît en lecture seule dans l’assistant et dans les paramètres. Dans l’assistant, définir OIDC_ENABLED, OIDC_ISSUER_URL ou OIDC_CLIENT_ID verrouille toute la section, qui liste alors les variables définies. Enregistrer les réglages OIDC depuis l’interface déclenche un redémarrage propre du serveur pour recharger la configuration (comme pour les réglages SMTP). Le client secret est chiffré au repos dans la base de données.

Variables d’environnement

VariableDescriptionPar défaut
OIDC_ENABLEDInterrupteur général. À false ou non définie, le SSO est désactivé et le bouton masqué.false
OIDC_ISSUER_URLL’URL d’émetteur de votre IdP (obligatoirement en https). Notifuse découvre le reste à partir de <issuer>/.well-known/openid-configuration. Requise quand le SSO est activé.-
OIDC_CLIENT_IDClient ID OAuth2 fourni par votre IdP. Requis quand le SSO est activé.-
OIDC_CLIENT_SECRETClient secret OAuth2 (client confidentiel). Chiffré au repos, jamais envoyé au navigateur. Requis quand le SSO est activé.-
OIDC_REDIRECT_URIL’URL de callback enregistrée chez votre IdP. Si elle est vide, elle vaut <API_ENDPOINT>/api/user.oidc.callback.dérivée de API_ENDPOINT
OIDC_SCOPESScopes séparés par des espaces. openid est toujours inclus, email est requis et profile fournit le nom affiché, facultatif.openid email profile
OIDC_BUTTON_LABELTexte du bouton de connexion.Sign in with SSO
OIDC_AUTO_CREATE_USERSProvisionnement à la volée. À true, demande OIDC_ALLOWED_DOMAINS. Voir Provisionnement.false
OIDC_ALLOWED_DOMAINSListe des domaines d’email autorisés pour la création automatique, séparés par des virgules, des points-virgules ou des espaces. Obligatoire quand OIDC_AUTO_CREATE_USERS=true (sinon le serveur refuse de démarrer).-
OIDC_ALLOW_UNVERIFIED_EMAILAccepte un ID token sans claim email_verified, pour les fournisseurs qui n’en envoient jamais (Microsoft Entra ID, Cloudflare Access). À une première connexion, un token qui indique email_verified: false est refusé. Une identité déjà liée à un compte se connecte par son subject, sans nouvelle vérification. Une adresse non vérifiée ne compte jamais pour une invitation en attente (voir Utilisateurs invités).false

Attention

Quand OIDC_ENABLED=true, le serveur valide la configuration au démarrage et s’arrête aussitôt si elle est invalide (émetteur, client ou secret manquant, émetteur hors https, ou création automatique sans liste de domaines). La même validation a lieu avant l’enregistrement depuis le panneau des paramètres : une mauvaise configuration est rejetée avec une erreur au lieu d’être enregistrée.

Provisionnement

Par défaut, le SSO est réservé aux utilisateurs invités : un utilisateur ne peut se connecter en SSO que s’il a déjà un compte Notifuse ou s’il a été invité dans un espace de travail (voir Utilisateurs invités). Une connexion SSO pour une adresse que personne n’a invitée est rejetée avec un message « aucun compte ». Notifuse garde ainsi son modèle sans inscription libre.

Pour que les nouveaux utilisateurs soient créés automatiquement à leur première connexion SSO, définissez :

OIDC_AUTO_CREATE_USERS=true
OIDC_ALLOWED_DOMAINS=yourcompany.com

Avec la création automatique, un compte est créé à la première connexion quand l’IdP atteste un email vérifié et que son domaine figure dans OIDC_ALLOWED_DOMAINS. Même alors, le nouvel utilisateur n’a accès à aucun espace de travail tant qu’il n’est pas invité. Une adresse qui a une invitation en attente suit plutôt les règles des Utilisateurs invités, dans les deux sens : l’invitation peut créer le compte hors de la liste de domaines, et un fournisseur qui ne fait pas autorité pour l’adresse n’en crée aucun.

Utilisateurs invités

Une personne invitée n’a pas besoin d’ouvrir le lien reçu par email avant de se connecter en SSO. À sa première connexion SSO, une invitation en attente pour son adresse crée son compte. C’est vrai en mode réservé aux invités, et même quand son domaine ne figure pas dans OIDC_ALLOWED_DOMAINS, puisqu’une invitation est le choix explicite d’un propriétaire pour cette adresse précise. L’invitation n’est pas acceptée à sa place : la personne arrive sur la liste des espaces de travail, la trouve sous Invitations en attente et clique sur Rejoindre.

Cela ne se produit que si votre fournisseur d’identité fait autorité pour l’adresse, car rejoindre un espace depuis la console repose sur l’adresse que le fournisseur atteste :

FournisseurFait autorité quand
GoogleL’adresse se termine par @gmail.com, ou elle appartient à un compte Google Workspace (le claim hd). Google ne se porte pas garant d’un compte Google personnel créé avec l’adresse d’un autre domaine.
Microsoft Entra IDL’utilisateur est membre de votre tenant et l’ID token porte le claim facultatif xms_edov, à true. Ajoutez-le dans l’inscription de votre application, sous Token configuration → Add optional claim → ID. Les invités qui se connectent avec un compte Microsoft ou Google personnel, ou avec un code à usage unique, ne comptent pas : Entra leur attribue aussi xms_edov.
Tout autre fournisseurL’ID token porte email_verified: true. Un fournisseur qui en relaie d’autres (Keycloak, Dex, les connexions sociales d’Auth0) se porte garant de leurs adresses avec son propre email_verified : ne le transmettez que pour des adresses en lesquelles vous avez confiance.

Quand le fournisseur ne fait pas autorité, le SSO ne crée aucun compte pour une adresse invitée (même avec OIDC_AUTO_CREATE_USERS), et la personne invitée ouvre le lien de son email d’invitation. Une fois l’invitation acceptée, le SSO fonctionne pour elle.

Note

Les utilisateurs sont reconnus par la paire durable (issuer, subject) fournie par l’IdP, pas par leur email : un utilisateur garde le même compte même si son email change chez l’IdP. L’email ne sert qu’à la première connexion, pour lier une identité SSO à un compte existant ou pour trouver les invitations qui attendent cette adresse. Un compte ROOT_EMAIL ne peut jamais être lié automatiquement à une identité externe (une protection contre la prise de contrôle d’un compte d’administration de la plateforme).

Configurer le fournisseur d’identité

L’URL de callback (ou de redirection) à enregistrer chez chaque fournisseur est :

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

Attention

L’URI de redirection doit être identique octet pour octet chez votre IdP et dans Notifuse. Derrière un reverse proxy qui réécrit le schéma ou l’hôte, définissez explicitement OIDC_REDIRECT_URI avec l’URL visible de l’extérieur. Sinon, l’IdP renvoie une erreur redirect_uri_mismatch.

Google Workspace

  1. Dans la Google Cloud Console, allez dans APIs & Services → Credentials → Create credentials → OAuth client ID.
  2. Choisissez Web application.
  3. Sous Authorized redirect URIs, ajoutez https://<your-notifuse-domain>/api/user.oidc.callback.
  4. Copiez le Client ID et le Client secret.
  5. Configurez 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

Note

Les comptes personnels @gmail.com et vos comptes Workspace partagent l’émetteur accounts.google.com. Utilisez OIDC_ALLOWED_DOMAINS (ou gardez le mode par défaut, réservé aux invités) pour limiter la connexion à votre organisation. Une adresse @gmail.com que vous avez invitée peut tout de même se connecter (voir Utilisateurs invités).

Keycloak

  1. Dans votre realm, créez un client : Client type OpenID Connect, Client authentication sur ON (client confidentiel), Standard flow activé.
  2. Mettez https://<your-notifuse-domain>/api/user.oidc.callback dans Valid redirect URIs.
  3. Copiez le secret depuis l’onglet Credentials du client.
  4. Configurez Notifuse :
OIDC_ENABLED=true
OIDC_ISSUER_URL=https://keycloak.example.com/realms/<your-realm>
OIDC_CLIENT_ID=notifuse
OIDC_CLIENT_SECRET=your-client-secret

Astuce

Les client scopes par défaut de Keycloak émettent déjà email, email_verified, name et sub. Si quelqu’un a retiré le mapper d’email de votre client, les connexions SSO sont rejetées (pas de claim email) : rajoutez le scope intégré email.

Autres fournisseurs

Tout fournisseur certifié OpenID Connect fonctionne de la même façon : mettez l’émetteur du fournisseur dans OIDC_ISSUER_URL, enregistrez l’URI de redirection et fournissez le client ID et le secret. C’est le cas d’Okta, Microsoft Entra ID (Azure AD), Authentik et Dex.

Sécurité

  • Seules deux valeurs non secrètes arrivent jusqu’au navigateur : window.OIDC_ENABLED et le libellé du bouton. Le client ID, le client secret et l’URL de l’émetteur ne sont jamais exposés dans la page.
  • Les ID tokens sont vérifiés avec les clés publiées par l’émetteur (renouvelées automatiquement via JWKS). Signature, émetteur, audience, nonce et expiration sont tous contrôlés, et seuls les algorithmes asymétriques (RS256/ES256) sont acceptés.
  • L’état CSRF, nonce et PKCE du flux est conservé dans un cookie HttpOnly chiffré, de courte durée.
  • Les appels HTTP OIDC (découverte, récupération des clés, échange de tokens) ont une durée limitée : un émetteur lent ou injoignable ne peut pas bloquer la connexion, et la connexion par code magique n’est pas touchée.

Dépannage

SymptômeCause et solution
“L’authentification unique est temporairement indisponible” après un clic sur SSONotifuse ne parvient pas à joindre ou à découvrir l’émetteur. Vérifiez que OIDC_ISSUER_URL est correcte, joignable depuis le serveur, et qu’elle sert un document de découverte. Notifuse réessaie automatiquement quand l’émetteur revient.
“Aucun compte Notifuse n’est lié… Si vous avez été invité, ouvrez le lien de votre e-mail d’invitation”L’adresse n’a pas de compte, et le SSO n’a rien à partir de quoi en créer un. Soit personne ne l’a invitée (invitez l’utilisateur, ou activez OIDC_AUTO_CREATE_USERS avec une liste de domaines), soit elle a une invitation en attente mais votre fournisseur ne fait pas autorité pour l’adresse (voir Utilisateurs invités), et l’utilisateur accepte l’invitation par son lien.
“L’authentification unique ne peut pas créer de compte pour votre domaine de messagerie”La création automatique est activée et l’adresse est hors de OIDC_ALLOWED_DOMAINS. Ajoutez le domaine, ou invitez l’utilisateur : une invitation passe outre la liste de domaines pour cette adresse quand votre fournisseur fait autorité pour elle (voir Utilisateurs invités). Sinon, l’utilisateur accepte l’invitation par son lien.
redirect_uri_mismatch / invalid_redirect_uri chez l’IdPL’URI de redirection enregistrée chez l’IdP ne correspond pas exactement à celle qu’envoie Notifuse. Enregistrez …/api/user.oidc.callback, et définissez OIDC_REDIRECT_URI si vous êtes derrière un proxy qui réécrit le schéma ou l’hôte.
Le serveur ne démarre plus après l’activation d’OIDCLa validation de la configuration a échoué. Vérifiez que OIDC_ISSUER_URL est en https, que OIDC_CLIENT_ID et OIDC_CLIENT_SECRET sont définis, et que OIDC_ALLOWED_DOMAINS n’est pas vide quand OIDC_AUTO_CREATE_USERS=true.
Un utilisateur peut se connecter mais n’accède à aucun espace de travailC’est normal : se connecter ne donne pas de droits. Invitez l’utilisateur dans l’espace de travail voulu (ou ajoutez-le à ROOT_EMAIL). Une invitation en attente apparaît sur sa liste d’espaces de travail avec un bouton Rejoindre.

Note

Plusieurs réplicas de Notifuse derrière un load balancer ? Le code à usage unique qui termine le passage de relais SSO est conservé par instance : activez les sticky sessions pour que le SSO fonctionne de façon fiable d’un réplica à l’autre. Un déploiement à une seule instance n’a besoin d’aucune configuration supplémentaire.