SSO-Fehlerbehebung

Diese Anleitung behandelt häufige Probleme, auf die Sie bei der Einrichtung oder Verwendung von Single Sign-On mit Zenovay stoßen können, zusammen mit deren Lösungen.

SAML 2.0-Fehler

"SAML signature verification failed"

Ursache: Das X.509-Zertifikat in Zenovay stimmt nicht mit dem Zertifikat überein, das Ihr Identitätsanbieter zum Signieren der SAML-Antwort verwendet hat.

Lösung:

1. Laden Sie eine aktuelle Kopie des Signaturzertifikats von Ihrem IdP herunter
2. Gehen Sie in Zenovay zu Settings → Security → SSO
3. Bearbeiten Sie den SAML-Anbieter und ersetzen Sie das Zertifikat
4. Stellen Sie sicher, dass Sie das gesamte Zertifikat kopiert haben, einschließlich -----BEGIN CERTIFICATE----- und -----END CERTIFICATE-----

"SAML digest mismatch"

Ursache: Die SAML-Antwort wurde während der Übertragung geändert oder es ist ein falsches Zertifikat konfiguriert.

Lösung:

1. Überprüfen Sie, dass das Zertifikat in Zenovay mit dem aktiven Signaturzertifikat in Ihrem IdP übereinstimmt
2. Falls Ihr IdP kürzlich Zertifikate rotiert hat, laden Sie das neue Zertifikat herunter
3. Stellen Sie sicher, dass keine Proxys oder Middleware die SAML-Antwort ändern

"Referenced element not found"

Ursache: Die SAML-Antwort enthält nicht das erwartete signierte Element.

Lösung:

1. Überprüfen Sie, dass Ihr IdP eine standardmäßige SAML 2.0-Antwort sendet
2. Überprüfen Sie, dass die Antwort ein Assertion-Element mit einem gültigen ID-Attribut enthält
3. Wenden Sie sich an Ihren IdP-Administrator, falls das Problem weiterhin besteht

"Entity ID mismatch" oder "Audience mismatch"

Ursache: Die SP Entity ID, die in Ihrem IdP konfiguriert ist, entspricht nicht dem, was Zenovay erwartet.

Lösung:

• Stellen Sie die SP Entity ID / Audience URI in Ihrem IdP genau auf: https://auth.zenovay.com
• Verwenden Sie keinen abschließenden Schrägstrich oder Pfad

"Invalid ACS URL" oder "Reply URL mismatch"

Ursache: Die ACS URL in Ihrem IdP entspricht nicht dem Callback-Endpunkt von Zenovay.

Lösung:

• Stellen Sie die ACS URL genau auf: https://auth.zenovay.com/api/sso/saml/callback
• Stellen Sie sicher, dass es keinen abschließenden Schrägstrich gibt

"NameID not found" oder "Email not provided"

Ursache: Die SAML-Antwort enthält nicht die E-Mail-Adresse des Benutzers im erwarteten Format.

Lösung:

1. Stellen Sie das NameID format in Ihrem IdP auf EmailAddress ein
2. Stellen Sie sicher, dass der NameID value der E-Mail-Adresse des Benutzers entspricht
3. Überprüfen Sie, dass der Benutzer eine gültige E-Mail-Adresse in Ihrem IdP-Verzeichnis hat

OAuth 2.0 / OIDC-Fehler

"Invalid redirect URI" oder "Redirect URI mismatch"

Ursache: Der Redirect URI, der in Ihrem IdP konfiguriert ist, entspricht nicht dem, was Zenovay sendet.

Lösung:

• Stellen Sie den Redirect URI genau auf: https://auth.zenovay.com/api/sso/oauth/callback
• Stellen Sie sicher, dass es keinen abschließenden Schrägstrich gibt
• Der URI muss eine genaue Übereinstimmung sein (Groß-/Kleinschreibung beachtet)

"Invalid client credentials"

Ursache: Die Client ID oder das Client Secret, das in Zenovay eingegeben wurde, ist falsch.

Lösung:

1. Überprüfen Sie die Client ID und das Client Secret in Ihrem IdP-Dashboard
2. Falls das Secret abgelaufen ist, generieren Sie ein neues
3. Aktualisieren Sie die Werte in Zenovay

"OIDC discovery failed"

Ursache: Zenovay kann den OpenID Connect Discovery-Endpunkt unter Ihrer Issuer URL nicht erreichen.

Lösung:

1. Überprüfen Sie, dass die Issuer URL korrekt ist
2. Testen Sie die Discovery URL in Ihrem Browser: {issuer-url}/.well-known/openid-configuration
3. Einige IdPs erfordern einen abschließenden Schrägstrich in der Issuer URL (z. B. Auth0: https://tenant.us.auth0.com/)
4. Stellen Sie sicher, dass Ihr IdP öffentlich erreichbar ist

"Token verification failed"

Ursache: Das ID Token von Ihrem IdP konnte nicht überprüft werden.

Lösung:

1. Stellen Sie sicher, dass der JWKS-Endpunkt Ihres IdP erreichbar ist
2. Überprüfen Sie, dass der Signaturalgorithmus des Token dem entspricht, was Ihr IdP ankündigt
3. Überprüfen Sie, dass der aud (Audience) Claim im Token der Client ID entspricht

"State parameter mismatch"

Ursache: Der Authentifizierungsstatus war verloren oder wurde manipuliert, typischerweise aufgrund von Sitzungsproblemen.

Lösung:

1. Löschen Sie Browser-Cookies und versuchen Sie es erneut
2. Stellen Sie sicher, dass Sie keine Browser-Erweiterung verwenden, die Cookies blockiert
3. Versuchen Sie es in einem privaten Fenster

Domänenverifikationsprobleme

"Domain not verified"

Ursache: Ihre E-Mail-Domäne wurde nicht für SSO verifiziert.

Lösung:

1. Gehen Sie zu Settings → Security → SSO
2. Klicken Sie auf Ihren SSO-Anbieter
3. Klicken Sie auf Add Domain und geben Sie Ihre E-Mail-Domäne ein
4. Folgen Sie den DNS-Verifikationsschritten
5. Geben Sie der DNS-Propagation Zeit (bis zu 48 Stunden)

"Domain already in use"

Ursache: Die E-Mail-Domäne ist bereits mit einem anderen SSO-Anbieter oder einer anderen Organisation verknüpft.

Lösung:

1. Überprüfen Sie, ob ein anderer SSO-Anbieter in Ihrer Organisation diese Domäne bereits verwendet
2. Entfernen Sie die Domäne zunächst vom anderen Anbieter
3. Falls die Domäne mit einer anderen Organisation verknüpft ist, wenden Sie sich an [email protected]

Zertifikatsprobleme

Zertifikatsablauf

SAML-Signaturzertifikate haben ein Ablaufdatum. Wenn sie ablaufen, schlägt die SSO-Authentifizierung fehl.

So überprüfen Sie es:

1. Überprüfen Sie das Zertifikatsablaufdatum in Ihrem IdP-Dashboard
2. Stellen Sie eine Kalendernotiz 30 Tage vor Ablauf ein

So aktualisieren Sie es:

1. Laden Sie das neue Zertifikat von Ihrem IdP herunter
2. Bearbeiten Sie in Zenovay den SSO-Anbieter
3. Ersetzen Sie das Zertifikat und speichern Sie
4. Testen Sie die Verbindung

Zertifikatsformat

Zenovay erwartet das X.509-Zertifikat im PEM-Format:

-----BEGIN CERTIFICATE-----
MIIDpDCCAoygAwIBAgIGAX...
(base64 encoded certificate data)
...
-----END CERTIFICATE-----

• Schließen Sie die BEGIN- und END-Zeilen ein
• Fügen Sie keine zusätzlichen Leerzeichen oder Header ein
• Falls Ihr IdP eine .cer- oder .der-Datei bereitstellt, konvertieren Sie diese zunächst in das PEM-Format

Allgemeine Probleme

"SSO provider not found"

Ursache: Die bei der Anmeldung eingegebene E-Mail-Domäne entspricht keinem konfigurierten SSO-Anbieter.

Lösung:

1. Überprüfen Sie, dass die Domäne auf dem SSO-Anbieter in Zenovay hinzugefügt und verifiziert ist
2. Stellen Sie sicher, dass der Benutzer eine E-Mail mit der korrekten Domäne eingibt

Benutzer können sich nach SSO-Erzwingung nicht anmelden

Ursache: SSO ist erzwungen, aber Benutzer können sich nicht beim IdP authentifizieren.

Lösung:

1. Deaktivieren Sie die SSO-Erzwingung vorübergehend in Settings → Security → SSO
2. Melden Sie sich mit E-Mail/Passwort an, um auf die Einstellungen zuzugreifen
3. Beheben Sie die SSO-Konfiguration
4. Aktivieren Sie die Erzwingung erneut

Neue Benutzer werden nicht erstellt

Ursache: Der Benutzer existiert in Ihrem IdP, hat aber kein Zenovay-Konto.

Lösung: Zenovay stellt automatisch neue Benutzerkonten bei der ersten SSO-Anmeldung bereit. Falls dies nicht geschieht:

1. Überprüfen Sie, dass die SAML-Antwort oder das OIDC Token die E-Mail-Adresse des Benutzers enthält
2. Überprüfen Sie, dass die E-Mail-Domäne der verifizierten Domäne entspricht
3. Stellen Sie sicher, dass der Benutzer der Zenovay-Anwendung in Ihrem IdP zugewiesen ist

Test-Checkliste

Bevor Sie SSO erzwingen, überprüfen Sie:

• SSO-Anbieter ist in Zenovay mit korrekten IdP-Werten konfiguriert
• E-Mail-Domäne ist verifiziert
• Benutzer sind der Anwendung in Ihrem IdP zugewiesen
• Test-Anmeldung funktioniert in einem privaten Fenster
• Bereitstellung neuer Benutzer funktioniert (Test mit einem Benutzer, der noch kein Zenovay-Konto hat)
• Mindestens ein Owner kann sich immer mit E-Mail/Passwort als Backup anmelden

Hilfe erhalten

Falls Sie immer noch Probleme haben:

• E-Mail: [email protected]
• Enterprise-Support: [email protected]

Wenn Sie den Support kontaktieren, geben Sie an:

1. Name und Protokoll des Identitätsanbieters (SAML/OAuth/OIDC)
2. Die genaue Fehlermeldung, die Sie sehen
3. Ob es sich um eine neue Einrichtung oder eine bestehende handelt, die nicht mehr funktioniert
4. Alle kürzlichen Änderungen an Ihrer IdP-Konfiguration