Authentification unique (OIDC)

Mugnsoft prend en charge l’authentification unique (SSO) basee sur des standards via OpenID Connect (OIDC), en complement de l’authentification locale par mot de passe et de LDAP. Tout fournisseur d’identite conforme fonctionne — Microsoft Entra ID, Okta, Auth0, Keycloak, Google Workspace — en utilisant uniquement l’OIDC standard, sans API specifique au fournisseur.

Vue d’ensemble

OIDC est une troisieme methode d’authentification optionnelle. Elle coexiste avec la connexion locale et LDAP — l’activer ne desactive pas les autres (sauf si vous choisissez le mode SSO uniquement). Lorsqu’elle est activee, la page de connexion affiche un bouton Se connecter avec {fournisseur}.

Comportements cles :

• Flux de code d’autorisation avec PKCE (S256) — le flux navigateur moderne et securise.
• Provisionnement a la volee (JIT) — lors de la premiere connexion SSO d’un utilisateur sur le plan de controle, un compte Mugnsoft est cree automatiquement a partir des revendications du jeton d’identite. Aucune creation prealable necessaire. (Un frontal DMZ en lecture seule ne provisionne pas — voir SSO sur un frontal DMZ en lecture seule.)
• Mappage des roles a chaque connexion — les groupes du fournisseur sont traduits en group + type de compte Mugnsoft et resynchronises a chaque connexion, l’acces suit donc le fournisseur.
• Garde anti-detournement — une connexion SSO ne peut jamais reprendre silencieusement un compte local ou LDAP existant portant le meme nom d’utilisateur.
• Mode SSO uniquement — masque optionnellement le formulaire nom d’utilisateur/mot de passe pour que les utilisateurs s’authentifient exclusivement via le fournisseur (avec une issue de secours integree).
• Deconnexion unique (Single Logout) — termine optionnellement aussi la session du fournisseur lors de la deconnexion, afin que la prochaine connexion redemande les identifiants.

Voir Gestion des utilisateurs SSO pour le cycle de vie au quotidien (colonne Auth, desactivation vs suppression).

Architecture

Le jeton d’identite est verifie par la bibliotheque go-oidc par rapport au JWKS du fournisseur (signature, emetteur, audience, expiration). Mugnsoft ne stocke dans le navigateur que son propre cookie de session a duree de vie courte — jamais les jetons d’acces ou d’identite du fournisseur. Le secret client est stocke chiffre dans le magasin de configuration KV et n’est jamais journalise ni renvoye au navigateur.

Le compte provisionne est un utilisateur Mugnsoft standard avec type d'auth = oidc. Les utilisateurs OIDC n’ont pas de mot de passe local et ne peuvent pas utiliser le formulaire de mot de passe.

Configuration

Connectez-vous en tant qu'administrateur et allez dans Parametres → Services externes → AUTHENTICATION → SSO (OIDC).

Cliquez sur l’icone de test (eclair) a cote de l’URL de l’emetteur — ou l’icone eclair sur la tuile SSO — pour verifier la decouverte aupres du fournisseur. Les parametres SSO sont enregistres en meme temps que le reste des parametres du serveur web a l’aide du bouton enregistrer (disquette) principal en haut de la fenetre ; il n’y a pas de bouton d’enregistrement SSO separe. La configuration prend effet immediatement — aucun redemarrage.

Mappage des roles

Le mappage des roles traduit un groupe du fournisseur vers le modele d’autorisation Mugnsoft (group parmi admin/user/viewer, plus un accountType et un perimetre optionnel). Il est reapplique a chaque connexion.

{
  "Mugnsoft_Admins":   { "group": "admin",  "accountType": "full" },
  "Mugnsoft_NetTeam":  { "group": "user",   "tags": "network,core", "apps": "vpn,dns" },
  "Mugnsoft_Viewers":  { "group": "viewer", "tags": "public" }
}

Lorsqu’un utilisateur appartient a plusieurs groupes mappes, le privilege le plus eleve l’emporte (admin > user > viewer). Si aucun groupe ne correspond, le Groupe par defaut / Type de compte par defaut s’appliquent.

Perimetre (tags / apps)

Chaque entree de mappage peut porter des champs optionnels tags et apps (separes par des virgules) qui restreignent ce que l’utilisateur voit — les memes champs de perimetre qu’un utilisateur local. Le perimetre effectif est l'union sur tous les groupes auxquels l’utilisateur correspond, et il s’applique a tous les groupes, y compris admin (un admin peut aussi etre restreint). Les deux sont resynchronises depuis le mappage a chaque connexion.

Une dimension que vous omettez n’est pas effacee — si une entree n’a pas de tags, l’utilisateur conserve les tags deja presents sur son enregistrement (definis manuellement, ou repris d’une connexion precedente). Pour accorder une visibilite totale, ne definissez simplement aucun perimetre pour ce groupe. Sur un frontal DMZ en lecture seule, le perimetre est calcule en direct depuis les groupes de la connexion, avec repli sur l’enregistrement replique quand le mappage n’en definit aucun.

Mode SSO uniquement

Avec SSO uniquement active, la carte de connexion masque le formulaire nom d’utilisateur/mot de passe et n’affiche que le bouton SSO — la page reste par ailleurs identique. Pour eviter tout verrouillage, deux issues de secours restaurent toujours le formulaire local :

• Ajoutez ?local=1 a l’URL de connexion.
• Toute tentative SSO echouee renvoie a la page de connexion avec le formulaire local visible.

Gestion des utilisateurs SSO

Les comptes SSO apparaissent dans Parametres → Utilisateurs aux cotes des utilisateurs locaux et LDAP. Le tableau des utilisateurs comporte une colonne Auth indiquant la source de chaque utilisateur — SSO, LDAP ou Local — afin de voir d’un coup d’oeil comment chacun se connecte.

Desactiver vs supprimer un utilisateur SSO

Comme les comptes SSO sont provisionnes a la volee, les deux actions se comportent differemment :

Pour retirer quelqu’un definitivement, desactivez-le ou supprimez-le chez le fournisseur d’identite (ou desactivez-le dans Mugnsoft). Le groupe et le type de compte sont resynchronises depuis le fournisseur a chaque connexion ; modifier directement le groupe d’un utilisateur dans Mugnsoft est donc ecrase a la connexion suivante — modifiez plutot le mappage ou le groupe cote fournisseur.

SSO sur un frontal DMZ en lecture seule

Un frontal Mugnsoft deploye en DMZ est une replique en lecture seule alimentee par une replication a sens unique depuis le plan de controle. Le SSO y fonctionne, mais le provisionnement a la volee est desactive : le frontal ne cree ni ne modifie jamais d’enregistrement utilisateur. Il n’admet que les utilisateurs SSO deja presents dans le magasin d’utilisateurs replique (et reapplique leur role d’apres les groupes de la connexion en cours).

Consequence pratique : un nouvel utilisateur SSO doit d’abord se connecter sur le plan de controle (ce qui le provisionne et permet a la replication de porter l’enregistrement vers la DMZ). Se connecter sur la DMZ avant que le compte ne soit replique est refuse avec ?ssoerror=provision.

Le frontal s’authentifie en client public PKCE (aucun secret en DMZ)

Vous ne configurez pas OIDC sur le frontal. Le plan de controle conserve la configuration confidentielle (emetteur, client ID, secret client, mappage de roles) et ne replique jamais le secret — le bucket setting reste interne. A la place, quand vous enregistrez les parametres OIDC, le plan de controle publie une config publique sans secret que la replication porte automatiquement vers le frontal.

Comme un secret client ne doit jamais se trouver sur un hote DMZ expose, le frontal se connecte en client public OAuth via Code d’autorisation + PKCE — sans secret. Le code_verifier PKCE protege l’echange ; l’IdP n’a besoin que de l’ID du client public et de l’URI de redirection propre au frontal.

Pour l’activer :

1. Chez votre IdP, enregistrez un second client pour le frontal en client public (PKCE requis, sans secret), avec l’URI de redirection https://<hote-frontal>/auth/oidc/callback. Voir la note client public sous chaque fournisseur.
2. Dans Mugnsoft → Parametres → SSO (OIDC), renseignez :
   • Front client ID (public) — l’ID du client public. (Laissez vide seulement si votre client principal est lui-meme public/compatible PKCE.)
   • Front redirect URL — https://<hote-frontal>/auth/oidc/callback.
3. Enregistrez. La config publique est repliquee vers le frontal selon la cadence de replication habituelle (et le bouton Se connecter avec SSO y apparait des qu’elle arrive).

Configuration des fournisseurs

Les valeurs a enregistrer chez chaque fournisseur sont identiques :

• URI de redirection : https://<hote-mugnsoft>/auth/oidc/callback
• Flux : Code d’autorisation (+ PKCE)
• Scopes : openid profile email (plus une revendication/un scope de groupes)

Microsoft Entra ID

1. Centre d’administration Entra → Inscriptions d’applications → Nouvelle inscription.
   • URI de redirection (Web) : https://<hote-mugnsoft>/auth/oidc/callback.
2. Certificats et secrets → Nouveau secret client → copiez la valeur.
3. Configuration des jetons → Ajouter une revendication de groupes → selectionnez Groupes de securite (ou les groupes affectes a l’application). Ajoutez-la au jeton d’identite.
4. Notez l'ID d’application (client) et l'ID de l’annuaire (tenant).
5. Dans Mugnsoft :
   • URL de l’emetteur : https://login.microsoftonline.com/<tenant-id>/v2.0
   • ID client / Secret : des etapes 1 a 2.
   • Revendication groupes : groups.

Okta

1. Admin Okta → Applications → Create App Integration → OIDC → Web Application.
2. Sign-in redirect URI : https://<hote-mugnsoft>/auth/oidc/callback. Sign-out redirect URI : votre URL de redirection apres deconnexion.
3. Copiez le Client ID et le Client secret.
4. Ajoutez une revendication groupes : Security → API → Authorization Servers → default → Claims → Add claim :
   • Nom : groups, Include in : ID token, Value type : Groups, Filtre : Matches regex .* (ou un filtre plus strict).
5. Dans Mugnsoft :
   • URL de l’emetteur : https://<votre-org>.okta.com/oauth2/default (ou l’emetteur de votre serveur d’autorisation personnalise).
   • ID client / Secret de l’etape 3.
   • Revendication groupes : groups.

Auth0

1. Tableau de bord Auth0 → Applications → Create Application → Regular Web Application (client confidentiel avec secret).
2. Settings → Allowed Callback URLs : https://<hote-mugnsoft>/auth/oidc/callback. Allowed Logout URLs : votre URL de redirection apres deconnexion.
3. Copiez le Domain, le Client ID et le Client Secret.
4. Auth0 n’emet pas les groupes ou roles dans le jeton d’identite par defaut, et Auth0 rejette toute revendication personnalisee qui n’est pas une URI avec espace de noms. Ajoutez une Action post-connexion (Actions → Library → Build Custom, ajoutee au flux Login) qui injecte les roles/groupes de l’utilisateur comme revendication avec espace de noms :

exports.onExecutePostLogin = async (event, api) => {
  const ns = "https://mugnsoft/";
  const roles = event.authorization?.roles || []; // necessite RBAC active
  api.idToken.setCustomClaim(ns + "groups", roles);
};

5. Dans Mugnsoft :
   • URL de l’emetteur : https://<tenant>.<region>.auth0.com/ — conservez la barre oblique finale ; elle doit correspondre a la valeur iss qu’Auth0 place dans le jeton.
   • ID client / Secret de l’etape 3.
   • Revendication groupes : https://mugnsoft/groups — le nom complet avec espace de noms issu de l’Action, pas un simple groups.

Keycloak

Un guide local complet (Docker, realm, client, mappeur de groupes, utilisateur de test) figure dans le tutoriel du depot. En resume :

1. Creez un realm ; l’emetteur devient http://<hote>:8080/realms/<realm>.
2. Creez un client OpenID Connect, Client authentication ON (confidentiel), Standard flow ON. URI de redirection https://<hote-mugnsoft>/auth/oidc/callback.
3. Copiez le secret depuis l’onglet Credentials.
4. Ajoutez un mappeur Group Membership sur le scope dedie du client (<client>-dedicated), pas un scope client Optional. Token Claim Name doit valoir groups — Keycloak emet la revendication sous Token Claim Name, pas sous le Name du mappeur ; laisser ce champ vide ne produit aucune revendication groups, meme avec tous les interrupteurs sur ON. Activez Add to ID token et/ou Add to userinfo (au moins un). Full group path peut etre active ou non — Mugnsoft ignore la barre oblique de tete dans les deux cas. Un mappeur sur le scope dedie est toujours emis ; un mappeur sur un scope Optional n’est envoye que si le client demande ce scope par son nom.
5. Dans Mugnsoft, definissez l’URL de l’emetteur, l’ID client = client, le secret, la revendication groupes groups.

Google Workspace

Google emet des jetons d’identite avec email, name et sub, mais n’inclut pas l’appartenance aux groupes dans le jeton d’identite standard. La connexion de base fonctionne immediatement ; pour le mappage de roles base sur les groupes, vous devez exposer les groupes separement (Cloud Identity / une synchronisation d’annuaire), sinon tous les utilisateurs basculent sur le Groupe par defaut.

1. Console Google Cloud → API et services → Identifiants → Creer un ID client OAuth → Application Web.
2. URI de redirection autorise : https://<hote-mugnsoft>/auth/oidc/callback.
3. Utilisez l’URL de l’emetteur https://accounts.google.com, revendication nom d’utilisateur email. Google positionne email_verified=true pour les comptes Workspace geres, ce que Mugnsoft exige avant d’accepter un email comme nom d’utilisateur.

Deconnexion

La deconnexion efface toujours la session Mugnsoft. Ce qui arrive a la session du fournisseur depend du parametre Deconnexion unique :

• Deconnexion unique activee (par defaut) — lorsque le document de decouverte du fournisseur expose un end_session_endpoint, Mugnsoft effectue une deconnexion initiee par l’application : le navigateur est redirige vers le fournisseur pour terminer sa session, puis revient vers la Redirection apres deconnexion. La connexion suivante redemande les identifiants. La deconnexion est transparente — aucun ecran de confirmation « voulez-vous vous deconnecter ? » du fournisseur.
• Deconnexion unique desactivee — seule la session Mugnsoft locale est effacee. La session du fournisseur est conservee ; recliquer sur Se connecter avec {fournisseur} peut donc reconnecter l’utilisateur sans invite.

Cela fonctionne avec tout fournisseur annoncant un end_session_endpoint (Entra ID, Okta, Keycloak, Auth0). Google Workspace n’en fournit pas, la deconnexion reste donc toujours locale quel que soit le reglage.

Depannage

Les tentatives SSO echouees renvoient a la page de connexion avec un parametre ?ssoerror=<code>. Codes :

Problemes courants sans code d’erreur :

• Groupe/role non applique — le fournisseur n’emet pas du tout la revendication groupes (aucun mappage de groupe/role configure, ou il est rattache a un scope que le client ne demande pas), le nom de la revendication ne correspond pas a la Revendication groupes configuree, ou les cles de groupe du mappage de roles ne correspondent pas a ce que le fournisseur envoie (chemin complet ou identifiant opaque au lieu du nom). Mugnsoft lit les groupes d’abord dans le jeton d’identite puis bascule sur l’endpoint UserInfo : emettre la revendication sur l’un ou l’autre suffit — mais si aucun ne la porte, chaque utilisateur recoit le Groupe par defaut. Quand aucun groupe n’arrive, le serveur ecrit une ligne WARN listant les revendications reellement envoyees par le fournisseur — oidcCallback - <user>: groups claim "groups" absent. ID-token claims=[...] UserInfo claims=[...] — pour voir si la revendication manque totalement ou existe sous un autre nom (definissez Revendication groupes sur ce nom). En cas de succes, le log affiche oidcCallback - <user> groups=[...]. Voir la section de configuration de votre fournisseur pour savoir ou ajouter la revendication de groupe.
• Echec du test de decouverte — mauvais emetteur (barre oblique finale, mauvais realm/tenant) ou fournisseur injoignable depuis l’hote serveur. Ouvrez l’URL .well-known/openid-configuration depuis l’hote pour confirmer.
• Le callback s’interrompt avec une reponse vide — le schema de l’URL de redirection ne correspond pas au serveur. Sur un serveur HTTPS, utilisez une redirection https:// dans Mugnsoft et chez le fournisseur.
• Un utilisateur SSO supprime revient sans cesse — c’est attendu (re-provisionnement a la volee). Desactivez-le dans Mugnsoft, ou retirez-le chez le fournisseur. Voir Gestion des utilisateurs SSO.

Notes de securite

• Les jetons d’identite sont verifies pour la signature, l’emetteur, l’audience et l’expiration par rapport au JWKS du fournisseur ; les jetons non signes ne sont jamais approuves.
• La validation du state + nonce et le PKCE (S256) protegent contre le CSRF et l’interception du code.
• La verification TLS est toujours active.
• Le secret client est stocke chiffre et n’est jamais ecrit dans les journaux ni renvoye au navigateur.
• Seul le cookie de session Mugnsoft (HTTPOnly, SameSite=Lax, Secure en HTTPS) est place dans le navigateur — aucun jeton du fournisseur.
• Un nom d’utilisateur n’est jamais tire d’une revendication email non verifiee, et les noms d’utilisateur sont normalises (minuscules, detoures) afin que les variantes de casse ne creent pas de comptes en double.
• Les cibles du mappage de roles sont validees a admin/user/viewer a l’enregistrement ; un groupe invalide ne peut jamais etre ecrit sur un enregistrement utilisateur.
• Un frontal DMZ en lecture seule n’effectue aucune ecriture utilisateur lors de la connexion SSO — il ne peut ni creer, ni modifier, ni reactiver de comptes.

Traductions

• en: Single Sign-On (OIDC)