Zum Hauptinhalt springen

OpenID Connect

In diesem Abschnitt wird beschrieben, wie Sie die OpenID Connect (OIDC)-Authentifizierung in Sync-in konfigurieren.

Sync-in implementiert den Autorisierungscode-Ablauf gemäß den OAuth 2.0-Empfehlungen für Webanwendungen.

Die Konfiguration befindet sich in environment.yaml, siehe OIDC-Abschnitt.

Voraussetzungen​

Bevor Sie OIDC in Sync-in aktivieren, muss ein OAuth/OIDC-Client in Ihrem Identitätsanbieter (IdP) erstellt werden.
Die Bezeichnungen können je nach Anbieter variieren, die Logik ist jedoch ähnlich.

Erstellen Sie eine Anwendung (Client)​

  • Der Anbieter-Typ muss OpenID Connect sein.
  • Der Client-Typ muss Confidential sein.
  • Der Anwendungstyp muss Web sein.
  • Der Grant-Typ muss Authorization Code sein.

Dieses Setup stellt die Client-ID (clientId) und das zugehörige Geheimnis (clientSecret) bereit, die Sie in die Konfiguration kopieren müssen.

Konfigurieren Sie Umleitungs-URIs​

Umleitungs-URIs müssen im IdP deklariert werden.
Sie ermöglichen es dem IdP, den Benutzer nach erfolgreicher Authentifizierung zurück zu Sync-in umzuleiten.

Anmeldung über einen Webbrowser​

Deklarieren Sie für die Web-UI-Authentifizierung den folgenden URI:

  • https://DOMAIN:PORT/api/auth/oidc/callback
Info

Diese URI entspricht dem Konfigurationsparameter redirectUri.
Sie muss mit /api/auth/oidc/callback enden.

Anmeldung über Desktop-Anwendungen​

Desktop-Anwendungen verwenden den Standardbrowser des Systems, um die Authentifizierung durchzuführen.
Nach der Anmeldung leitet der Browser den Benutzer zu einem lokalen URI weiter, um das Authentifizierungsergebnis zurück an die Anwendung zu übergeben.

Um dies zu ermöglichen, deklarieren Sie die folgenden lokalen URIs:

  • http://127.0.0.1:49152/oidc/callback
  • http://127.0.0.1:49153/oidc/callback
  • http://127.0.0.1:49154/oidc/callback

Dieser Ansatz verbessert die Kompatibilität mit IdPs und entspricht Authentifizierungsmechanismen, die bereits in Unternehmensumgebungen eingesetzt werden (SSO, MFA, Sicherheitsrichtlinien usw.).

Info

Bei Verwendung von OIDC wird erwartet, dass MFA vom Identitätsanbieter durchgesetzt wird. Sync-in fügt nach dem OIDC-Callback keine lokale 2FA-Abfrage hinzu. Sync-in 2FA bleibt während einer OIDC-Sitzung über das Benutzerprofil konfigurierbar; bei den Abläufen zum Aktivieren, Zurücksetzen und Deaktivieren wird das lokale Sync-in-Passwort überprüft.

Konfiguration​

Minimalbeispiel:

auth:
  provider: oidc
  oidc:
    issuerUrl: 'https://auth.example.com/realms/my-realm'
    clientId: 'OIDCClientId'
    clientSecret: 'OIDCClientSecret'
    redirectUri: 'https://sync-in.domain.com/api/auth/oidc/callback'

⚠️ redirectUri muss genau mit dem im IdP deklarierten URI übereinstimmen.

Authentifizierungsablauf​

Auf dem Sync-in-Anmeldebildschirm stehen zwei Authentifizierungsmethoden zur Verfügung.

Lokale Authentifizierung​

  • Gastkonten, Administratorkonten und Konten mit Anwendungskennwörtern können sich mit ihrem Login und Passwort anmelden.
  • Für diesen Anmeldepfad gilt die lokale 2FA von Sync-in, wenn sie für den Benutzer aktiviert ist.
  • Andere Benutzer können ihr lokales Passwort nur verwenden, wenn:
    • options.enablePasswordAuth aktiviert ist;
    • sie ihr lokales Sync-in-Passwort kennen.
  • Diese Konfiguration erhält den administrativen Notfallzugriff, ohne die OIDC-Authentifizierung zu deaktivieren.

Damit dieser Notfallzugriff nutzbar ist, sollte für Administratorkonten ein lokales Sync-in-Passwort konfiguriert und verfügbar gehalten werden.

Standardmäßig ist die lokale Passwortauthentifizierung für OIDC-Standardbenutzer deaktiviert. Aktivieren Sie options.enablePasswordAuth nur, wenn Sie diesen Fallback bewusst zulassen möchten.

Über OIDC erstellte Benutzer beginnen mit einem internen Zufallskennwort. Sie können in ihrem Profil ein bekanntes lokales Passwort festlegen, während sie über OIDC authentifiziert werden. Dieses Passwort kann dann für die lokale Passwortauthentifizierung verwendet werden, wenn sie aktiviert ist, sowie für den Step-up per Passwort-Fallback, wenn kein TOTP-Geheimnis aktiv ist. Es ist außerdem erforderlich, Sync-in 2FA über eine OIDC-Browsersitzung zu aktivieren, zurückzusetzen oder zu deaktivieren.

Anwendungskennwörter​

Das Generieren und Widerrufen von Anwendungskennwörtern erfordert den üblichen Sync-in-Step-up: TOTP, wenn aktiviert, andernfalls lokale Kennwortbestätigung.

OpenID Connect (OIDC)-Authentifizierung​

  • Der Benutzer startet die Anmeldung über die OIDC-Schaltfläche.
  • Er wird zur Authentifizierung an den IdP weitergeleitet.
  • Bei Bedarf wird MFA in diesem Schritt vom Identitätsanbieter erzwungen.
  • Nach der Validierung wird der Benutzer automatisch zurück zu Sync-in weitergeleitet.
  • Sync-in ruft Benutzerinformationen ab und synchronisiert das lokale Konto.
  • Wenn kein lokales Konto vorhanden ist und autoCreateUser aktiviert ist, wird ein lokales Konto mit einem zufälligen Passwort erstellt.
  • Die Administratorrolle wird automatisch angewendet, sofern konfiguriert.
  • Das Speicherkontingent wird aus options.storageQuotaClaim synchronisiert, wenn das OIDC-Profil einen gültigen Wert in Byte bereitstellt. Ein fehlender Claim-Wert oder ein Claim-Wert von 0 legt unbegrenzten Speicherplatz fest.

Das OIDC-Profil muss eine E-Mail-Adresse enthalten. Neue Konten initialisieren ihren lokalen Login über preferred_username und dann über den lokalen E-Mail-Teil, wenn preferred_username nicht vorhanden ist. Der Login wird einmal vergeben und bei späteren OIDC-Logins nicht umbenannt.

Kontobindung und Synchronisierung​

Sync-in verwendet den validierten ID-Token-Claim sub als stabile externe Identität und speichert ihn im lokalen Benutzerkonto. Während der Anmeldung werden Konten in dieser Reihenfolge aufgelöst:

  1. Sync-in vergleicht die gespeicherte externe Identität mit dem ID-Token-Claim sub.
  2. Nur bei bestehenden Konten ohne externe Identität greift Sync-in auf die E-Mail-Adresse zurück.
  3. Nach dem ersten erfolgreichen Kompatibilitätsabgleich speichert Sync-in den unveränderten Wert sub in diesem Konto.
  4. Wenn keine Übereinstimmung vorliegt und autoCreateUser aktiviert ist, erstellt Sync-in ein neues lokales Konto.

Sobald ein Konto gebunden ist, unterbrechen E-Mail-Änderungen beim IdP die Anmeldung nicht mehr, da Sync-in den Benutzer anhand von sub auflöst. Wenn der abgeleitete Login bei der automatischen Kontoerstellung bereits vergeben ist, hängt Sync-in ein deterministisches, aus sub abgeleitetes Suffix an; der Rohwert sub wird im Login nicht offengelegt.

Bestehende Benutzer können ihre E-Mail-Adresse, ihren Vornamen, ihren Nachnamen, ihre Rolle, ihr Speicherkontingent und ihren Avatar über OIDC synchronisieren lassen. Der lokale Login, das Passwort und die Berechtigungen werden nach der Kontoerstellung nicht synchronisiert.

Administratorrollen​

Wenn options.adminRoleOrGroup festgelegt ist, prüft Sync-in, ob dieser Wert in den vom IdP zurückgegebenen Claims groups oder roles vorhanden ist. Die Administratorrolle wird gewährt, wenn eine Übereinstimmung gefunden wird.

Wenn options.adminRoleOrGroup nicht festgelegt ist, behalten vorhandene Administratorkonten ihre Rolle und können nicht über OIDC herabgestuft werden.

Verfügbarkeit und Fehler​

Konfigurationsfehler oder IdP-Zugriffsfehler führen dazu, dass die Authentifizierung fehlschlägt.
Wenn der IdP nicht verfügbar ist, bleibt nur die lokale Authentifizierung möglich (siehe Authentifizierungsablauf).

Sicherheit​

Sync-in verwendet automatisch den Mechanismus PKCE (Proof Key for Code Exchange), wenn er vom Identitätsanbieter unterstützt und in der Konfiguration über den Parameter security.supportPKCE aktiviert wird (standardmäßig aktiviert).

PKCE stärkt den Autorisierungscode-Fluss durch die Hinzufügung eines kryptografischen Nachweises während des Autorisierungscode-Austauschs und verbessert so die Sicherheit für Web- und native Clients.

Diese Implementierung entspricht den aktuellen OAuth-Sicherheitsempfehlungen.

Info

Die PKCE-Unterstützung verhindert möglicherweise die Authentifizierung bei bestimmten Identitätsanbietern wie PocketID. In diesem Fall kann sie deaktiviert werden.

Die Option security.tokenEndpointAuthMethod unterstützt client_secret_basic und client_secret_post. Verwenden Sie den von Ihrem IdP erwarteten Wert. client_secret_basic ist die Standardeinstellung für vertrauliche Webclients. Das Feld clientSecret ist in der Sync-in-Konfiguration erforderlich.

OIDC-Erkennung und Token-Anfragen erfordern standardmäßig HTTPS. Die Option security.allowInsecureRequests sollte nur für lokale Entwicklung oder vertrauenswürdige Legacy-Anbieter aktiviert werden.

Die Option security.requireVerifiedEmail ist standardmäßig aktiviert. Sync-in verlangt, dass der UserInfo-Claim email_verified vor der Kontoverknüpfung oder Profilsynchronisierung genau true ist. Deaktivieren Sie die Option nur, wenn Ihr IdP keinen zuverlässigen Claim für verifizierte E-Mail-Adressen bereitstellt.

Wenn options.autoSyncAvatar aktiviert ist, kann Sync-in den Benutzeravatar aus dem OIDC-Claim picture synchronisieren. Avatar-Downloads aus privaten oder internen IP-Bereichen bleiben blockiert, sofern security.allowPrivateIpAvatarDownload nicht ausdrücklich aktiviert ist.