Fehlersuche bei SAML SSO-Anmeldeproblemen in Payhawk

Wenn Sie Probleme mit der Anmeldung bei Payhawk über SAML-basiertes Single Sign-On (SSO) haben, hilft Ihnen dieser Leitfaden beim Sammeln von Diagnoseinformationen, die die Fehlersuche und -behebung beschleunigen können.

Die meisten SSO-Anmeldeprobleme treten auf, wenn Benutzerkonten oder SSO-Konfigurationen vom Administrator in Ihrem Identitätsanbieter (IdP) oder in Payhawk nicht ordnungsgemäß eingerichtet wurden.

Erfassen der erforderlichen Daten

Die folgenden Schritte helfen Ihnen bei der Erfassung der erforderlichen Daten zur Ermittlung der Ursache:

Schritt 1: Erstellen einer HAR-Datei

Eine HAR-Datei (HTTP-Archiv) erfasst alle Netzwerkaktivitäten während Ihres Anmeldeversuchs, einschließlich Umleitungen, Anfragen und Antworten, und hilft so bei der Diagnose von Problemen mit der Verbindung, Weiterleitungen oder dem Authentifizierungsablauf. Um die für die Fehlerbehebung benötigte Datei zu erstellen, lesen Sie den Artikel zum Thema Erstellen von HAR-Dateien.

Sie können die HAR-Datei in den folgenden Fällen verwenden:

Wenn Ihre Anmeldung ohne Fehlermeldung fehlschlägt
Wenn Sie auf einem leeren Bildschirm oder einem Ladebildschirm hängen bleiben
Im Falle des Auftretens einer SSO-Umleitungsschleife

Schritt 2: Erfassen der SAML-Antwort

Die SAML-Antwort ist die Authentifizierungsnachricht, die von Ihrem IdP an Payhawk gesendet wird. Sie enthält Informationen über den Benutzer, die Authentifizierung und etwaige Fehler, die während des Authentifizierungsprozesses aufgetreten sind.

Die Erfassung dieser Antwort hilft bei der Ermittlung von Konfigurationsfehlern, fehlenden Ansprüchen oder ungültigen Authentifizierungen.

Sie können die SAML-Antwort auf die folgenden Arten erfassen:

Verwendung der Entwicklungswerkzeuge Ihres Browsers

Die zuverlässigste Methode zur Erfassung einer SAML-Antwort während einer Live-Anmeldung ist die Verwendung der Entwicklerwerkzeuge Ihres Browsers:

Öffnen Sie die Entwicklerwerkzeuge Ihres Browsers – drücken Sie F12 oder klicken Sie mit der rechten Maustaste und wählen Sie Prüfen.
Gehen Sie zur Registerkarte Netzwerk.
Initiieren Sie eine SSO-Anmeldung bei Payhawk von Ihrem Identitätsanbieter aus.
Suchen Sie nach einer POST-Anfrage an https://id.payhawk.com/saml2/idpresponse.
Klicken Sie auf diese Anfrage und navigieren Sie zum Abschnitt Payload oder Formulardaten.
Suchen Sie den SAMLResponse-Parameter. Der Wert ist eine Base64-kodierte Zeichenfolge.
Kopieren Sie die gesamte Base64-Zeichenfolge.
Dekodieren Sie sie mit einem Online-Base64-Decoder, wie z. B. diesen, um das vollständige SAML-Assertion-XML anzuzeigen.

In der dekodierten XML-Datei müssen Sie nach den folgenden Informationen suchen:

Die <saml:Issuer> muss mit der Entity-ID Ihres IdP übereinstimmen.
Die <saml:Audience> muss mit der Entity-ID von Payhawk übereinstimmen.
Die <saml:NameID> muss die E-Mail-Adresse oder die Kennung des Benutzers enthalten.
Fehlermeldungen oder ungültige Bedingungen.

Verwendung einer Browsererweiterung

Browser-Erweiterungen können das automatische Erfassen und Dekodieren von SAML-Nachrichten vereinfachen.

Eine Reihe von empfohlenen Erweiterungen sind:

SAML-tracer (Firefox): Zur Installation.
SAML Chrome Panel (Chrome): Zur Installation.

Verwendung der Browsererweiterung zur Fehlersuche:

Installieren Sie die Erweiterung.
Öffnen Sie das Erweiterungs-Panel (normalerweise in den Entwicklerwerkzeugen oder als Symbol in der Browser-Symbolleiste).
Starten Sie den SSO-Anmeldevorgang.
Die Erweiterung erfasst die SAML-Anfrage automatisch und zeigt die SAML-Antwort an.
Exportieren oder kopieren Sie die entschlüsselte SAML-Antwort-XML.

Überprüfung der Protokolle Ihres IdP

Einige IdPs, wie z. B. Microsoft Entra ID (Azure AD), Okta oder Google Workspace, stellen detaillierte Anmeldeprotokolle zur Verfügung, die die SAML-Assertion oder die an Payhawk gesendeten Forderungen enthalten können.

Wenn Sie Microsoft Entra ID verwenden:

Melden Sie sich beim Azure Portal an.
Gehen Sie zu Azure Active Directory > Unternehmensanwendungen > [Ihre Payhawk-App].
Navigieren Sie zu Anmeldeprotokolle.
Suchen Sie nach dem fehlgeschlagenen Anmeldeversuch und klicken Sie, um die Details anzuzeigen.
Suchen Sie nach SAML-Token-Details oder ausgestellten Forderungen.

Wenn Sie andere IdPs verwenden, prüfen Sie die offizielle Dokumentation Ihres IdPs für den Zugriff auf Anmelde- oder Audit-Protokolle.

Schritt 3: Die Diagnosedaten an den Payhawk Support übermitteln

Wenn Sie die HAR-Datei und die SAML-Antwort erfasst haben, senden Sie sie an support@payhawk.com oder in den Chat, damit der Payhawk Support sie analysieren kann:

In Ihrer Nachricht müssen Sie die folgenden Informationen angeben:

Eine Beschreibung des Problems (z. B. „SSO-Anmeldung schlägt mit Fehler X fehl“)
Die HAR-Datei
Die entschlüsselte SAML-Antwort-XML
Ihr Firmenname und Ihre Benutzer-E-Mail-Adresse

Gängige SAML-Probleme und was zu überprüfen ist

Problem	Mögliche Ursache	Was ist zu prüfen?
Fehlgeschlagene Anmeldung ohne Fehlermeldung	Benutzer nicht der Payhawk-App im IdP zugewiesen	Überprüfen Sie, ob der Benutzer im IdP zugewiesen ist (z. B. Azure AD, Okta).
Ungültige SAML-Antwort	Falsch konfigurierte Entity-IDs oder Endpunkte	Überprüfen Sie, ob die Entity-ID und die ACS-URL von Payhawk mit Ihrer IdP-Konfiguration übereinstimmen.
Benutzer nicht gefunden	E-Mail-Adresse oder NameID stimmen nicht überein	Stellen Sie sicher, dass die SAML NameID mit der Payhawk-E-Mail-Adresse des Benutzers übereinstimmt.
Fehler im Zertifikat	Abgelaufenes oder falsches Signaturzertifikat	Vergewissern Sie sich, dass das IdP-Zertifikat in den Payhawk-SSO-Einstellungen auf dem neuesten Stand ist.
Umleitungsschleife	Falsche SSO-Initiierungs-URL	Vergewissern Sie sich, dass Sie die richtige Payhawk-SSO-Anmelde-URL verwenden.