Si vous rencontrez des problèmes pour vous connecter à Payhawk via le Single Sign-On (SSO) basé sur SAML, ce guide vous aidera à collecter des informations de diagnostic qui peuvent accélérer le dépannage et la résolution des problèmes.
La plupart des problèmes de connexion SSO surviennent lorsque les comptes d'utilisateurs ou les configurations SSO ne sont pas correctement configurés par l'administrateur de votre fournisseur d'identité (IdP) ou de Payhawk.
Saisir les données nécessaires
Les étapes suivantes vous aideront à recueillir les données nécessaires à l'identification de la cause première : .
Étape 1 : Générez un fichier HAR
Un fichier HAR (HTTP Archive) capture toute l'activité du réseau pendant votre tentative de connexion, y compris les redirections, les demandes et les réponses, ce qui permet de diagnostiquer les problèmes de connectivité, de redirection ou de flux d'authentification. Pour créer le fichier nécessaire à la résolution du problème, consultez l'article générer des fichiers HAR.
Vous pouvez utiliser le fichier HAR dans les cas suivants :
Lorsque votre connexion échoue sans message d'erreur .
Si vous êtes bloqué sur un écran vide ou un écran de chargement .
En cas de boucle de redirection SSO
Étape 2 : Capturez la réponse SAML
La réponse SAML est le message d'authentification envoyé par votre IdP à Payhawk. Elle contient des informations sur l'utilisateur, l'assertion et toutes les erreurs qui ont pu se produire pendant le processus d'authentification.
La capture de cette réponse permet d'identifier les erreurs de configuration, les revendications manquantes ou les affirmations non valides.
Vous pouvez capturer la réponse SAML de la manière suivante :
Utilisation des outils de développement de votre navigateur
L'utilisation des outils de développement de votre navigateur est la méthode la plus fiable pour capturer une réponse SAML lors d'une connexion en direct :.
Ouvrez les outils de développement de votre navigateur – appuyez sur
F12ou cliquez avec le bouton droit de la souris et sélectionnez Inspecter.Accédez à l'onglet Réseau.
Initiez une connexion SSO à Payhawk depuis votre fournisseur d'identité.
Recherchez une requête
POSTàhttps://id.payhawk.com/saml2/idpresponse.Cliquez sur cette demande et accédez à la section Charge utile ou Données du formulaire.
Localisez le paramètre
SAMLResponse. La valeur sera une chaîne de caractères codée en Base64.Copiez la chaîne Base64 entière.
Décodez-la à l'aide d'un décodeur Base64 en ligne, tel que celui-ci, pour afficher le XML complet de l'assertion SAML.
Vous devrez rechercher les informations suivantes dans le XML décodé :.
Le
<saml:Issuer>doit correspondre à l'identifiant de l'entité de votre IdP.Le
<saml:Audience>doit correspondre à l'identifiant de l'entité Payhawk.Le
<saml:NameID>doit contenir l'adresse e-mail ou l'identifiant de l'utilisateur.Tout message d'erreur ou condition non valide.
Utilisation d'une extension de navigateur
Les extensions de navigateur peuvent simplifier la capture et le décodage automatiques des messages SAML.
Il est recommandé d'utiliser les extensions suivantes : .
SAML-tracer (Firefox) : installer ici. .
SAML Chrome Panel (Chrome) : installer ici.
Pour utiliser l'extension du navigateur afin de résoudre le problème :
Installez l'extension.
Ouvrez le panneau d'extension (généralement dans les outils de développement ou sous forme d'icône dans la barre d'outils du navigateur).
Démarrez le flux de connexion SSO.
L'extension capturera et affichera automatiquement la demande et la réponse SAML.
Exportez ou copiez la réponse SAML XML décodée.
Vérifiez les journaux de votre IdP
Certains fournisseurs d'identité, tels que Microsoft Entra ID (Azure AD), Okta ou Google Workspace, fournissent des journaux de connexion détaillés qui peuvent inclure l'assertion SAML ou les réclamations envoyées à Payhawk..
Si vous utilisez Microsoft Entra ID :.
Connectez-vous au Portail Azure.
Accédez à Azure Active Directory > Applications d’entreprise > [Votre application Payhawk].
Accédez à Journaux de connexion.
Trouvez la tentative de connexion qui a échoué et cliquez pour afficher les détails.
Recherchez les détails du jeton SAML ou les réclamations émises.
Si vous utilisez d'autres IdP, consultez la documentation officielle de votre IdP pour accéder aux journaux de connexion ou d'audit.
Étape 3 : Partagez les données de diagnostic avec le service d'assistance de Payhawk
Après avoir collecté le fichier HAR et la réponse SAML, envoyez-les à support@payhawk.com ou dans le chat pour que le support Payhawk les analyse :
Dans votre message, vous devez inclure les informations suivantes : .
Une description du problème (par exemple, « Échec de la connexion SSO avec l'erreur X »)
Le fichier HAR
La réponse SAML décodée en XML
Votre nom d'entreprise et l'adresse e-mail de l'utilisateur
Problèmes SAML courants et ce qu'il faut vérifier
Problème | Cause possible | Ce qu'il faut vérifier |
|---|---|---|
L'ouverture de session échoue silencieusement | L'utilisateur n'est pas assigné à l'application Payhawk dans l'IdP | Vérifiez que l'utilisateur est assigné dans l'IdP (par exemple, Azure AD, Okta). |
Réponse SAML non valide | ID d'entité ou points d'extrémité mal configurés | Vérifiez que l'ID d'entité et l'URL ACS de Payhawk correspondent à votre configuration IdP. |
Utilisateur non trouvé | Inadéquation entre l'adresse e-mail et le nom de l'utilisateur | Assurez-vous que l'identifiant SAML NameID corresponde à l'adresse e-mail Payhawk de l'utilisateur. |
Erreur de certificat | Certificat de signature expiré ou non conforme | Vérifiez que le certificat IdP est à jour dans les paramètres SSO de Payhawk. |
Boucle de redirection | URL d'initiation SSO incorrecte | Confirmez que vous utilisez l'URL de connexion Payhawk SSO correcte. |