Authentification unique avec OpenID Connect Module

Vaks PM · Guide d'intégration · OIDC · Juillet 2026

Ce que vous obtiendrez. Un bouton sur l'écran de connexion Vaks PM qui envoie les utilisateurs vers votre fournisseur d'identité puis les ramène, connectés. Les comptes sont rapprochés sur l'identifiant d'objet immuable du fournisseur, et peuvent optionnellement être créés à la première connexion avec un rôle dérivé de l'appartenance aux groupes. Ce guide couvre Microsoft Entra ID, Google Workspace, Okta et Keycloak ; tout fournisseur conforme à la spécification fonctionne de la même manière.

Comment ça marche

Vaks PM agit comme partie de confiance OpenID Connect. Il utilise le flux d'autorisation par code avec PKCE, et découvre automatiquement les points de terminaison de votre fournisseur — vous ne saisissez jamais d'URL d'autorisation ou de jeton à la main, seulement l'adresse de discovery.

Trois comportements méritent d'être compris avant toute configuration, car ils déterminent ce que votre fournisseur doit émettre :

Les comptes sont rapprochés sur une seule revendication : l'identifiant d'objet. Par défaut il s'agit de oid, avec repli sur sub. L'adresse email n'est jamais utilisée pour lier un compte existant — si un compte local porte déjà l'email entrant mais aucun identifiant d'objet correspondant, la connexion est refusée plutôt que de prendre silencieusement le contrôle du compte.
Les rôles viennent d'une revendication de groupes, que la plupart des fournisseurs n'émettent pas sans qu'on le leur demande. Sans elle, chaque utilisateur atterrit sur le rôle par défaut et vos mappages semblent sans effet.
Les utilisateurs inconnus sont soit créés, soit refusés, à votre choix. Les créer consomme un siège de licence ; les refuser non.

Les revendications lues sont, par ordre de repli : l'identifiant d'objet depuis oid puis sub ; l'email depuis email, puis preferred_username, puis upn ; le nom affiché depuis name, puis l'email ; les groupes depuis groups, puis roles.

Les noms de revendications ne sont pas modifiables dans l'interface d'administration. Le mappage existe dans l'API mais n'a pas de champ de formulaire : en pratique, votre fournisseur doit donc émettre ses revendications sous les noms standard ci-dessus. Pour les groupes, c'est le point à ne pas manquer : nommez la revendication exactement groups côté fournisseur. Okta et Keycloak permettent tous deux de choisir le nom de la revendication ; faites-le plutôt que d'attendre que Vaks PM s'adapte.

Prérequis

Côté	Ce qu'il vous faut
Fournisseur d'identité	Le droit d'enregistrer une application et, si vous voulez le mappage des rôles, d'ajouter une revendication de groupes au jeton. Sur Entra, cela signifie une app registration plus une configuration de jeton ; sur Google Workspace, un accès super-administrateur.
Vaks PM	Le droit `org:manage` — un administrateur d'organisation.
Licence	Une licence couvrant la fonctionnalité d'authentification unique. Vous pouvez configurer un fournisseur sans licence ; la connexion fédérée reste bloquée tant que la licence n'est pas importée dans Admin → Organisation → Licence.
Infrastructure	Redis doit être joignable — la poignée de main de connexion y est conservée pendant 10 minutes. L'URL de discovery du fournisseur doit être en HTTPS et résoluble publiquement ; un fournisseur d'identité sur une plage d'adresses privée est rejeté.

Conservez un administrateur de secours. Avant d'activer quoi que ce soit, assurez-vous qu'au moins un administrateur peut encore se connecter avec un mot de passe local et le MFA. L'authentification unique dépend de votre fournisseur, de Redis et d'horloges système correctes ; chacun des trois peut tomber. Sans administrateur local, cette panne enferme tout le monde dehors sans aucun moyen de rentrer.

Étape 1 — Commencer dans Vaks PM pour obtenir le redirect URI

Il vous faut le redirect URI avant de pouvoir enregistrer quoi que ce soit chez votre fournisseur, et Vaks PM le génère à partir d'un slug que vous choisissez.

Ouvrez Admin → Intégrations → Single sign-on, ajoutez un fournisseur, et renseignez les trois premiers champs :

Protocole — OIDC. Réglable uniquement à la création.
Slug — lettres minuscules, chiffres et tirets, de 2 à 40 caractères (par exemple entra). Il est figé une fois enregistré, car il est incorporé au redirect URI. Changer d'avis plus tard impose de supprimer le fournisseur et de le recréer.
Nom affiché — le libellé que les utilisateurs voient sur le bouton de connexion, par exemple « Se connecter avec Microsoft ».

Le formulaire affiche alors Redirect URI (généré) avec un bouton de copie. Il ressemble à ceci :

https://<votre-hôte>/api/v1/auth/oidc/<slug>/callback

Copiez-le. C'est cette chaîne exacte, caractère pour caractère, dont votre fournisseur a besoin.

Si vous exploitez plusieurs organisations sur des sous-domaines distincts, le redirect URI est dérivé de l'hôte qui sert chacune d'elles — chaque sous-domaine produit donc un URI différent, et chacun d'eux doit être enregistré chez le fournisseur.

Étape 2 — Dans votre fournisseur d'identité

Suivez la section correspondant à votre fournisseur, puis revenez à l'étape 3. Tous demandent les trois mêmes choses : le redirect URI que vous venez de copier, un client ID et un secret client.

Microsoft Entra ID

Rendez-vous dans Microsoft Entra admin center → Identity → Applications → App registrations → New registration. Nommez l'application, choisissez le mono-tenant, et sous Redirect URI sélectionnez la plateforme Web puis collez l'URI de l'étape 1.
Depuis Overview, copiez l'Application (client) ID et le Directory (tenant) ID.
Sous Certificates & secrets → Client secrets → New client secret, créez-en un et copiez immédiatement sa Value — elle n'est affichée qu'une fois.
Pour le mappage des rôles, allez dans Token configuration → Add groups claim, choisissez les groupes à inclure (groupes de sécurité, ou groupes affectés à l'application), et vérifiez que la revendication est bien émise dans l'ID token. Entra émet les object ID des groupes : vos mappages utiliseront donc des GUID plutôt que des noms de groupes.

Vaks PM construit pour vous l'adresse de discovery à partir du tenant ID — vous collerez le tenant ID plutôt qu'une URL.

Revendication de groupes, ou app roles. Si votre annuaire comporte des utilisateurs appartenant à un très grand nombre de groupes, Entra remplace la revendication par un lien au lieu de la liste, et le mappage des rôles cesse de fonctionner. Dans ce cas, définissez plutôt des app roles sur l'enregistrement et affectez-y les utilisateurs : ils arrivent dans la revendication roles, que Vaks PM lit en repli des groupes.

Alternative Entra — authentification par certificat (sans secret)

Au lieu d'un secret client partagé, Entra accepte qu'une application s'authentifie avec un certificat (private_key_jwt, RFC 7523) : l'application signe elle-même une preuve d'identité de courte durée avec sa clé privée, et Entra ne détient jamais que le certificat public correspondant. Rien de secret ne transite sur le réseau ni n'est communiqué à Entra. C'est une alternative complète au secret client de l'étape précédente, pas un complément — vous choisissez l'une ou l'autre méthode.

Générez une paire clé privée / certificat auto-signé (par exemple avec OpenSSL) : openssl req -x509 -newkey rsa:2048 -keyout vaks.key -out vaks.cer -days 730 -nodes -subj "/CN=vaks-pm". Conservez vaks.key (la clé privée, au format PEM PKCS#8) en lieu sûr — c'est ce que vous coller dans Vaks PM.
Dans Entra, sur la même application que celle enregistrée pour le SSO, allez dans Certificates & secrets → Certificates → Upload certificate et téléversez le fichier public vaks.cer.
Une fois l'upload accepté, Entra affiche l'empreinte du certificat (thumbprint) — copiez-la.
Dans Vaks PM, sur le formulaire du fournisseur, basculez Authentification sur Certificat, collez l'empreinte et le contenu de vaks.key (clé privée PEM). Laissez le champ secret client vide.

Comment Vaks PM choisit entre les deux méthodes. La règle est simple : si une clé privée est enregistrée pour ce fournisseur, l'authentification par certificat est utilisée ; sinon, c'est le secret client. La clé privée est chiffrée au repos et n'est plus jamais réaffichée après l'enregistrement — en modification, laissez le champ vide pour conserver celle déjà stockée, ou collez-en une nouvelle pour la remplacer. L'empreinte, elle, n'est pas secrète et reste visible.

Piège connu : la librairie OIDC standard ne convient pas ici. La plupart des clients OIDC génériques signent une assertion private_key_jwt avec un en-tête kid, mais Entra ne fait correspondre le certificat que sur l'en-tête x5t (l'empreinte du certificat). Une assertion sans x5t est silencieusement rejetée par Entra. Vaks PM signe donc lui-même cette assertion avec le bon en-tête — ce détail n'a d'incidence que si vous cherchez à reproduire ce flux ailleurs.

Cette même méthode d'authentification par certificat est aussi disponible, avec les mêmes étapes côté Entra, pour le provisionnement Microsoft Teams (dont le contexte SharePoint hérite) et pour un annuaire d'agents Entra Agent ID — quatre intégrations, un seul certificat à gérer si vous réutilisez la même application Entra pour plusieurs d'entre elles, ou un certificat distinct par application si vous préférez les isoler.

Google Workspace

Dans la Google Cloud console, sélectionnez ou créez un projet, puis allez dans APIs & Services → OAuth consent screen et configurez-le en Internal pour que seuls vos utilisateurs Workspace puissent l'utiliser.
Allez dans APIs & Services → Credentials → Create credentials → OAuth client ID, type d'application Web application. Sous Authorized redirect URIs, collez l'URI de l'étape 1.
Copiez le Client ID et le Client secret affichés après la création.
L'URL de discovery est la même pour tous les tenants Google : https://accounts.google.com.

Google n'émet pas l'appartenance aux groupes dans son ID token. Le mappage groupe vers rôle ne peut donc pas fonctionner avec Google Workspace en OIDC — chaque utilisateur recevra le rôle par défaut, et vous attribuerez manuellement dans Vaks PM tout rôle élevé. Si le mappage des rôles compte pour vous, utilisez plutôt SAML avec Google, où les attributs de groupes peuvent être envoyés.

Okta

Dans la console d'administration Okta, allez dans Applications → Create App Integration, choisissez OIDC — OpenID Connect et Web Application.
Sous Sign-in redirect URIs, collez l'URI de l'étape 1. Réglez les affectations sur les utilisateurs ou groupes qui doivent avoir accès.
Copiez le Client ID et le Client secret depuis l'onglet General de l'application.
Votre URL de discovery est https://<your-org>.okta.com/oauth2/default (ou le serveur d'autorisation personnalisé que vous comptez utiliser).
Pour le mappage des rôles, ouvrez Security → API → Authorization Servers, sélectionnez le serveur, et sous Claims ajoutez une revendication nommée exactement groups, incluse dans l'ID token, avec un filtre correspondant aux groupes que vous voulez envoyer.

Keycloak

Dans le realm que vous utilisez, allez dans Clients → Create client, type de client OpenID Connect, et donnez-lui un client ID.
Activez Client authentication (ce qui en fait un client confidentiel, ce qu'attend Vaks PM), et laissez le flux standard activé.
Sous Valid redirect URIs, collez l'URI de l'étape 1.
Récupérez le secret client dans l'onglet Credentials.
Votre URL de discovery est https://<keycloak-host>/realms/<realm>.
Pour le mappage des rôles, allez dans les Client scopes du client, ouvrez le scope dédié, et ajoutez un mapper Group Membership avec le nom de revendication de jeton groups. Désactivez Full group path sauf si vous comptez mapper des chemins du type /engineering/backend.

Tout autre fournisseur

Rien ici n'est spécifique à Microsoft. Tout fournisseur qui publie un document de discovery standard fonctionne : enregistrez un client web confidentiel avec le redirect URI de l'étape 1, récupérez le client ID et le secret, et fournissez l'adresse de discovery. Les deux seules exigences sont que l'ID token porte un identifiant de sujet stable et une adresse email, et — si vous voulez le mappage des rôles — une revendication nommée groups.

Étape 3 — Terminer dans Vaks PM

De retour dans le formulaire du fournisseur, complétez les champs restants :

Champ	Valeur
Microsoft Entra — Directory (tenant) ID	Pour Entra : le GUID du tenant, un domaine vérifié, ou `organizations`. La discovery URL en est construite et affichée sous le champ.
Discovery URL OIDC	Pour tous les autres fournisseurs : suivez le lien Utiliser une discovery URL OIDC personnalisée et collez l'adresse de l'étape 2 (`https://accounts.google.com`, votre serveur d'autorisation Okta, votre realm Keycloak). Doit être en HTTPS.
Client ID (application ID)	Depuis l'étape 2.
Authentification	Client secret (par défaut) ou Certificat — voir l'alternative par certificat pour Entra. Les deux méthodes sont chiffrées au repos et jamais réaffichées après l'enregistrement ; laissez les champs vides en modification pour conserver ce qui est déjà stocké.
Scopes	Compléments séparés par des espaces ou des virgules. `openid` est toujours inclus ; laisser ce champ vide demande `openid profile email`, ce qui convient dans presque tous les cas.
Rôle par défaut (JIT)	Le rôle attribué à un utilisateur nouvellement créé qui ne correspond à aucun mappage de groupe.
Utilisateur inconnu (aucun objectId correspondant)	Créer le compte automatiquement (JIT) ou Refuser la connexion (ne pas consommer de siège). Voir ci-dessous.

Le choix sur les utilisateurs inconnus est celui qui a de vraies conséquences. Créer le compte automatiquement provisionne le compte à la première connexion et consomme un siège de licence. Refuser la connexion signifie que seuls les comptes déjà existants peuvent s'authentifier — le réglage le plus sûr quand les sièges sont limités, ou quand vous provisionnez via SCIM et voulez que l'annuaire reste la seule source de comptes.

Étape 4 — Mapper les groupes aux rôles

Sous Mappages groupe → rôle, ajoutez une ligne par groupe : l'identifiant du groupe à gauche, le rôle Vaks PM à droite. Sur Entra, l'identifiant est l'object ID du groupe ; sur Okta et Keycloak, c'est le nom du groupe tel qu'émis dans la revendication.

Deux règles gouvernent l'évaluation :

L'ordre fait la priorité. Un utilisateur a exactement un rôle d'organisation : la première ligne correspondante en partant du haut l'emporte. Utilisez les flèches pour placer vos groupes les plus privilégiés en premier. La correspondance est une égalité de chaîne exacte — pas de jokers, pas d'insensibilité à la casse.
Aucune correspondance donne le rôle par défaut pour un nouveau compte, et aucun changement du tout pour un compte existant.

La case Le fournisseur d'identité fait autorité sur les rôles étend cela à la rétrogradation : à chaque connexion, un utilisateur ne correspondant à aucun mappage est réinitialisé au rôle par défaut. Laissez-la décochée si vous accordez des rôles élevés à la main dans Vaks PM, car elle les annulerait.

Deux garde-fous à connaître. Une revendication de groupes vide ou absente est traitée comme « inconnue », jamais comme « n'appartient à aucun groupe » — une revendication mal configurée ne peut donc pas rétrograder silencieusement toute votre organisation à la prochaine connexion. Et le dernier administrateur global restant n'est jamais rétrogradé, quoi que disent les mappages.

Étape 5 — Tester, puis activer

Enregistrez le fournisseur, puis pressez Tester sur sa ligne. Pour OIDC, l'opération effectue une récupération de discovery en direct et rapporte l'émetteur trouvé, le client ID et la présence d'un secret enregistré. Elle confirme que la discovery URL est joignable et cohérente — elle ne tente pas de connexion.

Cochez ensuite Activé (affiché sur l'écran de connexion) et enregistrez. Le bouton apparaît sur la page de connexion.

Vérifiez avec une vraie connexion, idéalement dans une fenêtre de navigation privée et avec un utilisateur pilote plutôt qu'avec votre propre compte administrateur :

L'utilisateur atteint le fournisseur, s'authentifie, et revient dans Vaks PM connecté.
Dans Admin → Utilisateurs, le compte affiche le rôle attendu — ce qui confirme que la revendication de groupes est bien arrivée et a bien correspondu.
Le compte dispose d'un siège de licence. Un utilisateur nouvellement créé n'en reçoit pas forcément un, et sans siège il se connecte correctement mais découvre une application vide — ce qui ressemble à un échec de configuration sans en être un. Attribuez le siège ici, ou utilisez une équipe à licence automatique.
Le journal d'audit contient une entrée auth.sso.login.

Terminez la connexion en moins de 10 minutes. La poignée de main est conservée dans Redis pendant 600 secondes et à usage unique. Une pause à mi-parcours, ou le rejeu d'une URL avec le bouton retour du navigateur, échoue avec une erreur d'état invalide. C'est normal et ce n'est pas une erreur de configuration.

Dépannage

Les erreurs de connexion sont affichées sur la page de connexion, dans la langue demandée par votre navigateur — l'utilisateur n'est pas encore authentifié, aucune préférence d'interface n'existe donc. Elles sont reproduites ci-dessous en français.

Symptôme	Cause & correctif
Un compte avec cet email existe déjà mais n'est pas lié à cette identité IdP (objectId)…	Un compte local porte déjà cet email mais n'a jamais été lié à cette identité. C'est délibéré — les comptes ne sont jamais repris par l'email. Renseignez l'identifiant externe du compte avec l'object ID du fournisseur, ou supprimez définitivement le compte et laissez-le être recréé.
Aucun compte ne correspond à cette identité (objectId) et la création automatique est désactivée.	La création automatique est désactivée et aucun compte ne correspond. Soit créez le compte au préalable (à la main ou via SCIM), soit basculez le réglage des utilisateurs inconnus sur la création automatique.
L'id_token ne contient pas d'identifiant ou d'email exploitable.	Le jeton ne porte aucun email exploitable. Ajoutez le scope ou la revendication `email` côté fournisseur ; sur Entra, vérifiez que le compte possède réellement une adresse mail.
État de session SSO invalide ou expiré.	Plus de 10 minutes se sont écoulées, l'URL a été rejouée, ou Redis est indisponible. Réessayez depuis une page de connexion propre ; si cela persiste, vérifiez Redis.
Échec de validation de la réponse de l'IdP.	Le jeton a échoué à la validation. La raison réelle n'est délibérément pas affichée dans le navigateur — consultez les logs du conteneur `api`, qui la consignent.
Provider OIDC incomplet (discovery/clientId manquant).	Le fournisseur a été activé alors qu'un champ manquait. Rouvrez-le et complétez-le.
Le single sign-on OIDC requiert une licence active.	La configuration est permise sans licence, la connexion non. Importez la licence dans Admin → Organisation → Licence.
Tout le monde atterrit sur le rôle par défaut	La revendication de groupes n'arrive pas. Sur Entra, vérifiez que Token configuration l'inclut dans l'ID token ; sur Okta et Keycloak, vérifiez que la revendication est nommée exactement `groups`. Sur Google Workspace, c'est attendu — les groupes ne sont pas émis du tout.
La connexion fonctionne, mais l'utilisateur ne voit rien après son arrivée	Le compte n'a pas de siège de licence. Accordez-en un dans Admin → Utilisateurs, ou utilisez une équipe à licence automatique.

Ce qui est journalisé

Sous Admin → Sécurité & Conformité → Journal d'audit : auth.sso.login à chaque connexion fédérée, avec le fournisseur et l'indication de la création éventuelle du compte ; auth.sso.failure avec le motif de refus ; user.provisioned.sso lorsqu'un compte est créé, avec le rôle appliqué ; et idp.created / idp.updated / idp.deleted pour les changements de configuration, le tout en sévérité critique. Les secrets clients n'apparaissent jamais dans le journal d'audit.

Les échecs de signature et de validation de jeton sont délibérément vagues dans le navigateur, pour ne pas offrir d'oracle de sondage à un attaquant. Leur cause réelle est dans les logs du conteneur api.

À lire aussi : authentification unique SAML si votre fournisseur ne parle pas OIDC · provisioning SCIM pour créer et retirer les comptes automatiquement · toutes les intégrations.