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

# 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](https://openid.net/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.

> [!WARNING]
>
> **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](https://www.notifuse.com/fr/docs/self-hosting/licence.md). Sur Notifuse Cloud, la clé est gérée pour vous et le SSO fait partie de l'offre Business : voir [Sur Notifuse Cloud](https://www.notifuse.com/fr/docs/self-hosting/licence.md#on-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](#provisioning) 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

| Variable                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                     | Par défaut                |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| `OIDC_ENABLED`                | Interrupteur général. À `false` ou non définie, le SSO est désactivé et le bouton masqué.                                                                                                                                                                                                                                                                                                                                                       | `false`                   |
| `OIDC_ISSUER_URL`             | L'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_ID`              | Client ID OAuth2 fourni par votre IdP. Requis quand le SSO est activé.                                                                                                                                                                                                                                                                                                                                                                          | -                         |
| `OIDC_CLIENT_SECRET`          | Client secret OAuth2 (client confidentiel). Chiffré au repos, jamais envoyé au navigateur. Requis quand le SSO est activé.                                                                                                                                                                                                                                                                                                                      | -                         |
| `OIDC_REDIRECT_URI`           | L'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_SCOPES`                 | Scopes 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_LABEL`           | Texte du bouton de connexion.                                                                                                                                                                                                                                                                                                                                                                                                                   | `Sign in with SSO`        |
| `OIDC_AUTO_CREATE_USERS`      | Provisionnement à la volée. À `true`, demande `OIDC_ALLOWED_DOMAINS`. Voir [Provisionnement](#provisioning).                                                                                                                                                                                                                                                                                                                                    | `false`                   |
| `OIDC_ALLOWED_DOMAINS`        | Liste 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_EMAIL` | Accepte 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](#invited-users)). | `false`                   |

> [!WARNING]
>
> 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](#invited-users)). 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 :

```bash
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](#invited-users), 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 :

| Fournisseur            | Fait autorité quand                                                                                                                                                                                                                                                                                                                                                                  |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Google                 | L'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 ID     | L'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 fournisseur | L'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
```

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

```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]
>
> 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](#invited-users)).

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

```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]
>
> 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ôme                                                                                                    | Cause et solution                                                                                                                                                                                                                                                                                                                                                                                       |
| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **"L'authentification unique est temporairement indisponible"** après un clic sur SSO                       | Notifuse 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](#invited-users)), 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](#invited-users)). Sinon, l'utilisateur accepte l'invitation par son lien.                                           |
| **`redirect_uri_mismatch` / `invalid_redirect_uri` chez l'IdP**                                             | L'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'OIDC**                                                    | La 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 travail**                                | C'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.
