Dépannage et référence SSO

Cet article couvre les autorisations, les valeurs de référence rapide et les solutions aux problèmes SSO courants. Pour les instructions de configuration, consultez le Guide de configuration des métadonnées SSO.

Autorisations

Toutes les actions de gestion des métadonnées SSO sont restreintes aux Super Administrateurs, à une exception près : un administrateur d'équipe peut télécharger les métadonnées IdP via un fichier pour le domaine de sa propre équipe.

Action	Rôle requis
Afficher l'onglet Métadonnées SSO	Super Administrateur
Télécharger les métadonnées IdP via un fichier (POST /admin/saml-metadata/upload)	Super Administrateur, ou un administrateur d'équipe dont sso_domain correspond au email_domain de son équipe
Télécharger les métadonnées IdP via XML collé (POST /admin/saml-metadata/upload-text)	Super Administrateur uniquement
Télécharger les métadonnées stockées (GET /admin/saml-metadata/download)	Super Administrateur
Supprimer les métadonnées stockées (DELETE /admin/saml-metadata/delete)	Super Administrateur

Note

Le point de terminaison des métadonnées SP à /saml/well-known/sp-metadata est public par conception. Il ne contient aucun secret — uniquement l'ID d'entité SP, l'URL ACS, le format NameID et le certificat de signature publique.

Référence rapide

Hôte backend

<your-backend-host> (par exemple ek-api.corp.acme.com)

Gère tout le trafic SAML — métadonnées SP, initiation SSO et le point de terminaison ACS. C'est le seul hôte que votre IdP doit connaître.

Hôte frontend

<your-frontend-host> (par exemple ek.corp.acme.com)

L'interface web que vos utilisateurs ouvrent. Configurée sur le backend via FRONTEND_ROOT_URL. N'apparaît jamais dans la configuration IdP.

URL des métadonnées SP

https://<your-backend-host>/saml/well-known/sp-metadata

Partagez ceci avec votre administrateur IdP pour enregistrer EK en tant qu'application SAML.

URL ACS

https://<your-backend-host>/user/generic/sso/saml/acs/admin

Où votre IdP envoie les réponses SAML. Toujours l'hôte backend — jamais le frontend.

Point d'entrée SSO lancé par le SP

https://<your-backend-host>/sso/login?enterprise_id=<email-domain>

Le point de terminaison backend vers lequel le frontend redirige lorsqu'un utilisateur initie SSO.

Format NameID requis

urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

Votre IdP doit envoyer l'adresse e-mail de l'utilisateur dans ce format.

Variables d'environnement du mode SSO frontend

Variable	Description
VITE_ALLOW_ONLY_SSO_LOGIN	true pour SSO à clic unique, false (par défaut) pour SSO modal par e-mail.
VITE_SSO_ENTERPRISE_ID	Mode à clic unique uniquement. Doit correspondre à un domaine qui a des métadonnées IdP téléchargées dans l'onglet Métadonnées SSO.

• Où télécharger les métadonnées IdP ? Tableau de bord Super Administrateur → onglet Métadonnées SSO → Ajouter des métadonnées / Mise à jour
• Un document par domaine. Le re-téléchargement remplace les métadonnées existantes. La suppression désactive SSO pour ce domaine.
• Rôle requis ? Super Administrateur pour toutes les actions, sauf que les administrateurs d'équipe peuvent télécharger via un fichier pour le domaine de leur propre équipe.

Dépannage

Erreur "Veuillez entrer un domaine valide"

Le champ Domaine e-mail de l'équipe SSO s'attend à un domaine simple comme acme.com ou eu.acme.co.uk. Supprimez tout @ initial, https://, chemins ou numéros de port avant de soumettre.

Erreur "Le fichier doit être un fichier XML"

Le téléchargeur de fichiers n'accepte que les fichiers avec l'extension .xml. Si votre IdP a fourni les métadonnées sous forme de fichier .txt ou sans extension, renommez-le en .xml ou basculez vers l'option Coller le contenu XML à la place.

Erreur "Le contenu ne semble pas être un XML valide"

Lors de l'utilisation de Coller le contenu XML, le contenu collé doit commencer par <?xml ou < après suppression des espaces blancs. Assurez-vous d'avoir copié le document de métadonnées complet et qu'aucun préambule ou commentaire n'a été inclus.

La connexion réussit avec l'IdP mais EK rejette l'assertion

Cela est presque toujours causé par l'une des raisons suivantes :

• Incompatibilité de certificat — le certificat de signature IdP dans les métadonnées téléchargées ne correspond plus au certificat que votre IdP utilise réellement. Cela se produit généralement après une rotation de certificat IdP. Obtenez des métadonnées fraîches auprès de votre administrateur IdP et utilisez Mise à jour.
• Format NameID incorrect — l'IdP n'envoie pas l'adresse e-mail comme NameID. Confirmez que le format est défini sur urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress du côté IdP.
• Incompatibilité d'ID d'entité — l'audience ou l'ID d'entité configuré dans votre IdP ne correspond pas à votre ID d'entité d'instance EK. Reshérez les métadonnées XML SP d'EK et demandez à votre administrateur IdP de les réimporter.

L'utilisateur se connecte avec succès mais l'accès est refusé

Cela est contrôlé par Super Administrateur → Contrôles d'accès, pas par l'onglet Métadonnées SSO. Consultez le guide Contrôles d'accès SAML pour plus de détails sur Autoriser tout nouvel utilisateur par rapport à Restreindre aux métadonnées SAML et les règles d'affectation d'équipe/projet automatisées.

SSO lancé par IdP ne fonctionne pas

Par défaut, EK n'accepte que les réponses SAML lancées à partir de son propre point de terminaison /sso/login — ce qui signifie SSO lancé par le SP uniquement. Pour activer SSO lancé par IdP (non sollicité), l'opérateur local doit définir ALLOW_IDP_INITIATED_SSO=true sur le backend EK et redémarrer le service. C'est un paramètre au niveau du déploiement, pas quelque chose de configurable dans l'onglet Métadonnées SSO.

IdP configuré avec l'hôte frontend au lieu de l'hôte backend

Si l'application IdP a été configurée avec le nom d'hôte frontend EK pour l'URL ACS ou l'ID d'entité, les réponses SAML seront envoyées au mauvais service et l'authentification échouera silencieusement — généralement en affichant une erreur 404 ou une page d'erreur générique après l'écran de connexion IdP.

Demandez à votre administrateur IdP de confirmer :

• L'URL ACS est https://<your-backend-host>/user/generic/sso/saml/acs/admin.
• L'ID d'entité / Audience correspond au entityID dans https://<your-backend-host>/saml/well-known/sp-metadata.

L'hôte frontend ne doit jamais apparaître dans la configuration de l'application SAML de l'IdP.

Le bouton SSO à clic unique ne fait rien (ou affiche "Impossible de déterminer le domaine pour la connexion SSO")

VITE_SSO_ENTERPRISE_ID n'est pas défini sur le frontend. Définissez-le sur le domaine e-mail pour lequel vous avez téléchargé les métadonnées IdP, puis redéployez ou redémarrez le frontend pour que la valeur prenne effet.

Le bouton SSO à clic unique redirige mais SSO échoue sur le backend

VITE_SSO_ENTERPRISE_ID est défini mais ne correspond à aucun domaine avec métadonnées téléchargées dans l'onglet Métadonnées SSO. Corrigez cela par l'une des deux méthodes :

• Télécharger les métadonnées IdP pour le domaine actuellement dans VITE_SSO_ENTERPRISE_ID — recommandé, car cela garde votre configuration frontend inchangée.
• Mise à jour de VITE_SSO_ENTERPRISE_ID pour correspondre à un domaine qui a déjà des métadonnées téléchargées, puis redéployement ou redémarrage du frontend.

Les deux valeurs doivent correspondre exactement (insensible à la casse).

SSO modal par e-mail affiche 'Votre organisation n'est pas configurée pour la connexion SSO'

Le domaine e-mail de l'utilisateur n'a pas de métadonnées IdP téléchargées dans l'onglet Métadonnées SSO. Soit téléchargez les métadonnées pour ce domaine, soit demandez à l'utilisateur de se connecter en utilisant l'e-mail/mot de passe ou OAuth à la place.

Les utilisateurs terminent SSO mais atterrissent sur la mauvaise page ou obtiennent une erreur de redirection

Après une réponse SAML réussie, EK redirige l'utilisateur vers l'URL frontend définie par FRONTEND_ROOT_URL sur le backend. Si cette variable n'est pas définie, pointe vers le mauvais hôte, ou utilise le mauvais schéma ou port, l'utilisateur semblera terminer l'authentification mais finira sur une page cassée.

Demandez à votre opérateur local de confirmer que FRONTEND_ROOT_URL correspond exactement à https://<your-frontend-host> — schéma correct, port correct, pas de problèmes de barre oblique finale.