OAuth/OIDC SSO-Einrichtung

Scale Plan

Konfigurieren Sie OAuth 2.0 oder OpenID Connect (OIDC) für Single Sign-On. Eine moderne Alternative zu SAML für Cloud-native Identitätsanbieter.

SAML vs OAuth/OIDC

Merkmal	SAML	OAuth/OIDC
Protokoll	XML-basiert	JSON/REST
Token-Format	XML-Assertion	JWT
Ideal für	Enterprise IdPs	Cloud-Apps
Setup-Komplexität	Höher	Niedriger

Unterstützte Anbieter

Anbieter	Protokoll
Microsoft Entra ID (Azure AD)	OIDC
Okta	OIDC
Auth0	OIDC
Keycloak	OIDC
Benutzerdefiniert	OAuth 2.0 / OIDC

Zenovay OAuth/OIDC-Konfiguration

Redirect URI

Ihr Identitätsanbieter benötigt diese Redirect URI:

Einstellung	Wert
Redirect URI / Callback URL	https://auth.zenovay.com/api/sso/oauth/callback

Sie können diesen Wert (und die SAML-Äquivalente) direkt von Einstellungen → Sicherheit → SSO unter Service Provider Details kopieren.

Erforderliche Scopes

Zenovay benötigt diese Scopes:

openid
email
profile

Wahl zwischen OAuth 2.0 und OpenID Connect

Merkmal	OAuth 2.0	OpenID Connect
ID-Token-Verifizierung	Nicht zutreffend	Automatisch via JWKS
Erforderliche Felder	Client ID, Client Secret, Issuer, Authorization URL, Token URL, Userinfo URL	Client ID, Client Secret, Issuer, Metadata URL
Ideal für	IdPs ohne OIDC-Unterstützung	Moderne IdPs (Okta, Entra ID, Auth0, Keycloak)

Mit OIDC geben Sie die Metadata URL (das .well-known/openid-configuration-Dokument Ihres IdP) an und Zenovay liest die Authorization-, Token-, Userinfo- und JWKS-Endpunkte daraus. Mit reinem OAuth 2.0 geben Sie jeden Endpunkt separat ein.

Microsoft Entra ID OIDC-Einrichtung

Schritt 1: Anwendung registrieren

1. Melden Sie sich beim Microsoft Entra Admin Center an
2. Gehen Sie zu Identität → Anwendungen → App-Registrierungen
3. Klicken Sie auf Neue Registrierung
4. Konfigurieren Sie:

Entra ID-Feld	Wert
Name	Zenovay
Unterstützte Kontotypen	Nur Konten in diesem Organisationsverzeichnis
Redirect URI	Web — https://auth.zenovay.com/api/sso/oauth/callback

5. Klicken Sie auf Registrieren

Schritt 2: Client Secret erstellen

1. Gehen Sie zu Zertifikate & Geheimnisse
2. Klicken Sie auf Neues Client Secret
3. Legen Sie Beschreibung und Ablaufdatum fest
4. Kopieren Sie den Geheimniswert sofort (er wird nicht erneut angezeigt)

Schritt 3: Anwendungsdetails notieren

Notieren Sie diese Werte:

• Anwendungs-ID (Client-ID) — von der Übersichtsseite
• Client Secret — aus Schritt 2
• Mandanten-ID — von der Übersichtsseite

Schritt 4: API-Berechtigungen

1. Gehen Sie zu API-Berechtigungen
2. Überprüfen Sie, dass Microsoft Graph → User.Read (delegiert) aufgeführt ist
3. Falls nicht, klicken Sie auf Berechtigung hinzufügen → Microsoft Graph → Delegierte Berechtigungen → User.Read

Schritt 5: In Zenovay konfigurieren

1. Gehen Sie in Zenovay zu Einstellungen → Sicherheit → SSO
2. Klicken Sie auf Anbieter hinzufügen und wählen Sie OpenID Connect
3. Geben Sie ein:
   • Provider-Name: z. B. „Microsoft Entra ID"
   • Client ID: die Anwendungs-ID (Client-ID) aus Schritt 3
   • Client Secret: der Geheimniswert aus Schritt 2
   • Issuer: https://login.microsoftonline.com/{ihre-mandanten-id}/v2.0
   • Metadata URL: https://login.microsoftonline.com/{ihre-mandanten-id}/v2.0/.well-known/openid-configuration
4. Klicken Sie auf Erstellen
5. Fügen Sie Ihre E-Mail-Domain hinzu und verifizieren Sie diese
6. Testen Sie die Verbindung

Okta OIDC-Einrichtung

Schritt 1: Anwendung erstellen

1. Gehen Sie zur Okta Admin Console → Anwendungen
2. Klicken Sie auf App-Integration erstellen
3. Wählen Sie OIDC - OpenID Connect
4. Wählen Sie Web Application
5. Klicken Sie auf Weiter

Schritt 2: Anwendung konfigurieren

Okta-Feld	Wert
App-Integrationsname	Zenovay
Grant-Typ	Authorization Code
Sign-in Redirect URIs	https://auth.zenovay.com/api/sso/oauth/callback

Schritt 3: Benutzer zuweisen

1. Gehen Sie zum Tab Zuweisungen
2. Weisen Sie Benutzer oder Gruppen zu
3. Speichern

Schritt 4: Anmeldedaten abrufen

Notieren Sie vom Tab Allgemein:

• Client ID
• Client Secret

Schritt 5: Issuer- und Metadata-URLs abrufen

1. Gehen Sie zu Sicherheit → API in der Okta Admin Console
2. Suchen Sie nach Ihrem Autorisierungsserver (normalerweise „default")
3. Die Issuer URI sieht etwa so aus: https://ihre-org.okta.com/oauth2/default
4. Die entsprechende Metadata URL ist die Issuer URI plus /.well-known/openid-configuration, zum Beispiel: https://ihre-org.okta.com/oauth2/default/.well-known/openid-configuration

Schritt 6: In Zenovay konfigurieren

1. Gehen Sie zu Einstellungen → Sicherheit → SSO
2. Klicken Sie auf Anbieter hinzufügen und wählen Sie OpenID Connect
3. Geben Sie ein:
   • Provider-Name: z. B. „Okta"
   • Client ID: aus Schritt 4
   • Client Secret: aus Schritt 4
   • Issuer: die Issuer URI aus Schritt 5
   • Metadata URL: die Discovery URL aus Schritt 5
4. Klicken Sie auf Erstellen
5. Fügen Sie Ihre E-Mail-Domain hinzu und verifizieren Sie diese
6. Testen Sie die Verbindung

Auth0-Einrichtung

Schritt 1: Anwendung erstellen

1. Gehen Sie zum Auth0 Dashboard
2. Gehen Sie zu Applications → Create Application
3. Wählen Sie Regular Web Applications
4. Klicken Sie auf Create

Schritt 2: Einstellungen konfigurieren

Im Tab Settings:

Auth0-Feld	Wert
Allowed Callback URLs	https://auth.zenovay.com/api/sso/oauth/callback

Klicken Sie auf Save Changes.

Schritt 3: Anmeldedaten abrufen

Notieren Sie vom Tab Settings:

• Domain (z. B. ihr-mandant.us.auth0.com)
• Client ID
• Client Secret

Schritt 4: In Zenovay konfigurieren

1. Gehen Sie zu Einstellungen → Sicherheit → SSO
2. Klicken Sie auf Anbieter hinzufügen und wählen Sie OpenID Connect
3. Geben Sie ein:
   • Provider-Name: z. B. „Auth0"
   • Client ID: aus Schritt 3
   • Client Secret: aus Schritt 3
   • Issuer: https://ihr-mandant.us.auth0.com/ (mit abschließendem Schrägstrich)
   • Metadata URL: https://ihr-mandant.us.auth0.com/.well-known/openid-configuration
4. Klicken Sie auf Erstellen
5. Fügen Sie Ihre E-Mail-Domain hinzu und verifizieren Sie diese
6. Testen Sie die Verbindung

Google Workspace

Wenn Sie speziell OIDC mit Google benötigen, können Sie OAuth-Anmeldedaten in der Google Cloud Console erstellen:

1. Gehen Sie zur Google Cloud Console → APIs & Services → Credentials
2. Klicken Sie auf Create Credentials → OAuth client ID
3. Wählen Sie Web application und geben Sie https://auth.zenovay.com/api/sso/oauth/callback als Redirect URI ein
4. Notieren Sie die Client ID und das Client Secret
5. Geben Sie in Zenovay einen OpenID Connect-Anbieter mit Issuer https://accounts.google.com und Metadata URL https://accounts.google.com/.well-known/openid-configuration ein

Benutzerdefinierter OIDC-Anbieter

Wenn Ihr Identitätsanbieter OpenID Connect Discovery unterstützt:

1. Gehen Sie zu Einstellungen → Sicherheit → SSO
2. Klicken Sie auf Anbieter hinzufügen und wählen Sie OpenID Connect
3. Geben Sie ein:
   • Provider-Name: Ihr Provider-Name
   • Client ID: von Ihrem IdP
   • Client Secret: von Ihrem IdP
   • Issuer: Ihre IdP-Issuer-URL (z. B. https://ihr-idp.com)
   • Metadata URL: Ihr IdP-Discovery-Dokument, normalerweise die Issuer-URL plus /.well-known/openid-configuration
4. Klicken Sie auf Erstellen

Zenovay liest Ihren IdP's Authorization-, Token-, Userinfo- und JWKS-Endpunkte aus dem Metadaten-Dokument, sodass Sie diese nicht einzeln eingeben müssen.

Benutzerdefinierter OAuth 2.0-Anbieter

Wenn Ihr Identitätsanbieter OIDC Discovery nicht unterstützt, verwenden Sie OAuth 2.0 mit manueller Endpunkt-Konfiguration:

1. Gehen Sie zu Einstellungen → Sicherheit → SSO
2. Klicken Sie auf Anbieter hinzufügen und wählen Sie OAuth 2.0
3. Geben Sie ein:
   • Provider-Name: Ihr Provider-Name
   • Client ID: von Ihrem IdP
   • Client Secret: von Ihrem IdP
   • Authorization URL: Ihr IdP's Authorization-Endpunkt
   • Token URL: Ihr IdP's Token-Endpunkt
   • Userinfo URL: Ihr IdP's User Info-Endpunkt
4. Klicken Sie auf Erstellen

Setup-Fertigstellung

Domain verifizieren

Nach dem Speichern Ihres SSO-Anbieters verknüpfen Sie die E-Mail-Domänen, mit denen sich Ihr Team anmeldet, damit Zenovay weiß, dass diese über SSO weitergeleitet werden:

1. Im Abschnitt Domain verification geben Sie Ihre E-Mail-Domain ein (z. B. unternehmen.com) und klicken Sie auf Domain verifizieren
2. Zenovay gibt einen DNS TXT-Record (Host und Wert) zurück — fügen Sie ihn bei Ihrem DNS-Anbieter hinzu
3. Klicken Sie auf DNS überprüfen, sobald sich der Record ausgebreitet hat
4. Sobald verifiziert, werden Benutzer mit dieser E-Mail-Domain zu SSO weitergeleitet

Verbindung testen

Sie können eine schnelle Überprüfung vornehmen, bevor Sie den Anbieter aktivieren:

1. Öffnen Sie das Aktionsmenü des Anbieters (die ⋯-Schaltfläche in der Anbieterzeile)
2. Klicken Sie auf Verbindung testen
3. Ein Erfolgs-Toast bestätigt, dass Zenovay Ihren IdP mit den konfigurierten Anmeldedaten erreichen kann

Sie können auch den End-to-End-Flow manuell bestätigen:

1. Öffnen Sie ein Inkognito-/privates Browserfenster
2. Gehen Sie zu auth.zenovay.com
3. Wählen Sie Mit SSO anmelden und geben Sie eine E-Mail-Adresse Ihrer verifizierten Domain ein
4. Authentifizieren Sie sich bei Ihrem IdP
5. Überprüfen Sie, dass Sie zum Zenovay-Dashboard zurückkehren

SSO aktivieren und erzwingen

1. Schalten Sie auf der Anbieterzeile den Toggle ein, um den Anbieter zu aktivieren
2. Um SSO für alle Benutzer im Arbeitsbereich zu erzwingen, öffnen Sie das Aktionsmenü des Anbieters (⋯) und wählen Sie SSO erzwingen, dann bestätigen Sie

Benutzerattribut-Zuordnung

Standard-Claims

OIDC Claim	Zenovay-Feld
email	E-Mail-Adresse
given_name	Vorname
family_name	Nachname
sub	Eindeutiger Bezeichner

Just-In-Time-Bereitstellung

Neue Benutzer werden bei ihrer ersten erfolgreichen SSO-Anmeldung automatisch erstellt:

• Automatische Kontoerstellung aus der verifizierten E-Mail-Domain
• Keine Einladung erforderlich

Sicherheitsfunktionen

Zenovay wendet automatisch diese Sicherheitsmaßnahmen für OAuth/OIDC an:

• PKCE (Proof Key for Code Exchange) — schützt den Autorisierungscode-Austausch
• State-Parameter — verhindert CSRF-Angriffe
• Nonce-Validierung (OIDC) — verhindert Token-Replay-Angriffe
• ID-Token-Verifizierung (OIDC) — validiert Tokens mit dem JWKS-Endpunkt des IdP

Fehlerbehebung

Häufige Fehler

Fehler	Ursache	Lösung
Invalid redirect_uri	URL-Abweichung	Stellen Sie sicher, dass die Redirect URI exakt https://auth.zenovay.com/api/sso/oauth/callback lautet
Invalid client_id	Falsche Anmeldedaten	Überprüfen Sie die Client ID in Ihrem IdP-Dashboard
Invalid grant	Code abgelaufen	Versuchen Sie es erneut — Autorisierungscodes haben eine kurze Lebensdauer
Token verification failed	Signaturfehler	Überprüfen Sie, dass der JWKS-Endpunkt erreichbar ist
State parameter mismatch	Sitzungsproblem	Löschen Sie die Cookies und versuchen Sie es in einem Inkognito-Fenster
OIDC discovery failed	Metadaten-URL-Problem	Öffnen Sie {metadata-url} in Ihrem Browser und bestätigen Sie, dass es das .well-known/openid-configuration-Dokument zurückgibt

Zertifikatsprobleme

Wenn JWKS fehlschlägt:

• Überprüfen Sie, dass die JWKS-URL erreichbar ist
• Stellen Sie sicher, dass das SSL-Zertifikat gültig ist
• Überprüfen Sie auf Firewall-Blockierungen

Sicherheitsüberlegungen

Geheimnis-Verwaltung

• Speichern Sie das Client Secret sicher
• Rotieren Sie Geheimnisse vor deren Ablauf
• Geben Sie Geheimnisse niemals in Client-Code preis

Scope-Einschränkungen

Fordern Sie minimale Scopes an:

• Nur openid, email, profile
• Fordern Sie keinen unnötigen Zugriff an

Redirect URI-Validierung

• Verwenden Sie exakte Übereinstimmungsvalidierung in Ihrem IdP
• Verwenden Sie keine Wildcards
• HTTPS erforderlich

Nächste Schritte

• MFA für alle Benutzer erzwingen
• Audit-Protokollierung konfigurieren
• Benutzerdefinierte Passwortrichtlinien