OIDC-Anbieter-Einrichtung

info

OpenID Connect (OIDC) ist ein Authentifizierungsprotokoll, das es Benutzern ermöglicht, sich mit ihren vorhandenen Konten von Anbietern wie Google, Microsoft oder Ihrem Unternehmens-Identitätsanbieter anzumelden. Es ermöglicht Single Sign-On (SSO) für eine nahtlose und sichere Authentifizierung.

This guide walks you through configuring OIDC (OpenID Connect) providers for SSO authentication in the Unraid API using the WebGUI.

🚀 Schnellstart

Zu den OIDC-Einstellungen gelangen

1. Navigieren Sie zur WebGUI Ihres Unraid-Servers.
2. Gehen Sie zu Einstellungen → Verwaltungszugriff → API → OIDC
3. Sie sehen Registerkarten für verschiedene Anbieter - klicken Sie auf die +-Schaltfläche, um einen neuen Anbieter hinzuzufügen.

Überblick über die OIDC-Anbieteroberfläche

Login page showing traditional login form with SSO options - "Login With Unraid.net" and "Sign in with Google" buttons

Login-Seite zeigt traditionelles Login-Formular mit SSO-Optionen - "Mit Unraid.net anmelden" und "Mit Google anmelden" Schaltflächen

• Anbieter-Registerkarten: Jeder konfigurierte Anbieter (Unraid.net, Google usw.) erscheint als Registerkarte.
• Anbieter hinzufügen Schaltfläche: Klicken Sie auf die + Schaltfläche, um neue Anbieter hinzuzufügen.
• Autorisierungsmodus Dropdown: Umschalten zwischen "einfachen" und "erweiterten" Modi.
• Einfache Autorisierungssektion: Konfigurieren Sie erlaubte E-Mail-Domains und spezifische Adressen.
• Element hinzufügen Schaltflächen: Klicken Sie, um mehrere Autorisierungsregeln hinzuzufügen.

Autorisierungsmodi verstehen

Die Oberfläche bietet zwei Autorisierungsmodi:

Einfacher Modus (Empfohlen)

Wann sollte der einfache Modus verwendet werden:

• Spezielle E-Mail-Domains zulassen (z.B. @company.com).
• Spezielle E-Mail-Adressen zulassen.
• Festlegen, wer mit minimalem Setup auf Ihren Unraid-Server zugreifen kann.

Wann sollte der einfache Modus verwendet werden:

• Sie möchten alle Benutzer von Ihrer Unternehmensdomain zulassen.
• Sie haben eine kleine Liste spezifischer Benutzer.
• Sie sind neu in der OIDC-Konfiguration.

Erweiterter Modus

Der erweiterte Modus bietet granulare Kontrolle mit regelbasierten Ansprüchen.

• Komplexe Autorisierungsregeln basierend auf JWT-Ansprüchen erstellen.

• Operatoren wie gleich, enthält, endetMit, beginntMit verwenden.

• Mehrere Bedingungen mit ODER/UND Logik kombinieren.

• Wählen, ob IRGENDEINE Regel bestehen muss (ODER-Modus) oder ALLE Regeln bestehen müssen (UND-Modus).

  Wann sollte der erweiterte Modus verwendet werden:

• Sie müssen Gruppenmitgliedschaften überprüfen.

• Mehrfache Ansprüche verifizieren wollen (z.B. E-Mail-Domain UND verifizierter Status).

• Sie haben komplexe Autorisierungsanforderungen.

• Benötigen eine feingranulare Kontrolle darüber, wie Regeln bewertet werden.

Erweiterter Modus

Der erweiterte Modus bietet granulare Kontrolle mit regelbasierten Ansprüchen.

Beispiele für den einfachen Modus

Unternehmensdomain zulassen

Im einfachen Autorisierungsmodus:

• Spezifische E-Mail-Adressen: Einzelne E-Mails hinzufügen
• Klicken Sie auf Element hinzufügen, um mehrere Adressen hinzuzufügen.

Spezielle Benutzer zulassen

• Spezifische E-Mail-Adressen: Einzelne E-Mails hinzufügen.
• Klicken Sie auf Element hinzufügen, um mehrere Adressen hinzuzufügen.

Beispiele für den erweiterten Modus

Autorisierungsregelmodus

Wenn mehrere Regeln verwendet werden, können Sie wählen, wie sie bewertet werden:

• ODER-Modus (Standard): Benutzer wird autorisiert, wenn IRGENDEINE Regel besteht.

• UND-Modus: Benutzer wird nur autorisiert, wenn ALLE Regeln bestehen.

  E-Mail-Domain mit Verifizierung (UND-Modus)

  Um sowohl E-Mail-Domain als auch Verifizierung zu verlangen:

1. Setzen Sie Autorisierungsregelmodus auf UND.
2. Zwei Regeln hinzufügen:
   • Regel 1:
     • Anspruch: email
     • Operator: endsWith
     • Wert: @company.com
   • Regel 2:
     • Anspruch: email_verified
     • Operator: equals
     • Wert: true

Dies stellt sicher, dass Benutzer sowohl über eine Unternehmens-E-Mail als auch eine verifizierte E-Mail-Adresse verfügen müssen.

Gruppenbasierter Zugriff (ODER-Modus)

Um den Zugriff auf mehrere Gruppen zu erlauben:

1. Setzen Sie Autorisierungsregelmodus auf ODER (Standard).
2. Fügen Sie Regeln für jede Gruppe hinzu:
   • Anspruch: groups
   • Operator: contains
   • Wert: admins Oder eine andere Regel hinzufügen:
   • Anspruch: groups
   • Operator: contains
   • Wert: developers

Benutzer in der admins ODER developers Gruppe werden autorisiert.

Mehrere Domains

• Anspruch: email
• Operator: endsWith
• Werte: Mehrere Domains hinzufügen (z.B. company.com, subsidiary.com)

Komplexe Autorisierung (UND-Modus)

Für strenge Sicherheit, die mehrere Bedingungen erfordert:

1. Setzen Sie Autorisierungsregelmodus auf UND.
2. Fügen Sie mehrere Regeln hinzu, die ALLE bestehen müssen:
   • E-Mail muss von der Unternehmensdomain stammen
   • E-Mail muss verifiziert sein
   • Benutzer muss in einer spezifischen Gruppe sein
   • Konto muss 2FA aktiviert haben (wenn Anspruch verfügbar)

Details zur Konfigurationsoberfläche

Anbieter-Registerkarten

• Jeder konfigurierte Anbieter erscheint als Registerkarte oben.

• Klicken Sie auf eine Registerkarte, um zwischen Anbieter-Konfigurationen zu wechseln.

• Mit der + Schaltfläche rechts wird ein neuer Anbieter hinzugefügt.

  Autorisierungsmodus Dropdown

• Einfach: Am besten für E-Mail-basierte Autorisierung (empfohlen für die meisten Benutzer).

• Erweitert: Für komplexe, anspruchsbasierte Regeln mit JWT-Ansprüchen.

  Einfache Autorisierungsfelder

  Wenn der "einfache" Modus ausgewählt ist, sehen Sie:

  • Erlaubte E-Mail-Domains: Geben Sie Domains ohne @ ein (z.B. company.com).
    • Hilfstext: "Benutzer mit E-Mails, die in diesen Domains enden, können sich einloggen"
  • Spezifische E-Mail-Adressen: Fügen Sie einzelne E-Mail-Adressen hinzu.
    • Hilfstext: "Nur diese exakten E-Mail-Adressen können sich einloggen"
  • Element hinzufügen-Schaltflächen, um mehrere Einträge hinzuzufügen.

  Erweiterte Autorisierungsfelder

  Wenn der "erweiterte" Modus ausgewählt ist, sehen Sie:

  • Autorisierungsregelmodus: Wählen ODER (jede Regel besteht) oder UND (alle Regeln müssen bestehen).
  • Autorisierungsregeln: Fügen Sie mehrere anspruchsbasierte Regeln hinzu.
  • Für jede Regel:
    • Anspruch: Der JWT-Anspruch, der überprüft werden soll.
    • Operator: Wie verglichen werden soll (equals, contains, endsWith, startsWith).
    • Wert: Gegen was abgeglichen werden soll.

  Zusätzliche Schnittstellenelemente

• Enable Developer Sandbox: Toggle to enable GraphQL sandbox at /graphql.

• Die Schnittstelle verwendet ein dunkles Thema für bessere Sichtbarkeit.

• Feldvalidierungsanzeigen helfen, die korrekte Konfiguration sicherzustellen.

Erforderliche Redirect-URI

vorsicht

Alle Anbieter müssen mit diesem genauen Redirect-URI-Format konfiguriert werden.

http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback

Hinweis

Ersetzen Sie YOUR_UNRAID_IP durch Ihre tatsächliche Server-IP-Adresse (z.B. 192.168.1.100 oder tower.local).

✅ Konfiguration testen

Unraid-Login-Seite, die sowohl die traditionelle Benutzername/Passwort-Authentifizierung als auch SSO-Optionen mit angepassten Anbieterschaltflächen anzeigt

• Speichern Sie Ihre Anbieter-Konfiguration
• Melden Sie sich ab (falls angemeldet)

Sicherheitshinweis: Verwenden Sie immer das Basis-URL-Format, wenn möglich. Das System fügt automatisch /.well-known/openid-configuration zur OIDC-Erkennung hinzu. Die direkte Verwendung der vollständigen Erkennungs-URL deaktiviert wichtige Überprüfungen des Ausstellungsortes und wird von der OpenID Connect-Spezifikation nicht empfohlen.

Um den Zugriff auf mehrere Gruppen zu erlauben:

• Setzen Sie Autorisierungsregelmodus auf ODER (Standard)
• Fügen Sie Regeln für jede Gruppe hinzu:
• Keycloak: https://keycloak.example.com/realms/IHR_REALM
• Authelia: https://auth.ihredomain.com

✅ Konfiguration testen

Unraid login page displaying both traditional username/password authentication and SSO options with customized provider buttons

1. Speichern Sie Ihre Anbieter-Konfiguration.
2. Melden Sie sich ab (falls angemeldet).
3. Aktivieren Sie das Debug-Logging, um tatsächliche Ansprüche und Regelbewertungen anzuzeigen.
4. Ihre konfigurierte Anbieterschaltfläche sollte angezeigt werden.
5. Klicken Sie, um den Anmeldevorgang zu testen.

Fehlerbehebung

Häufige Probleme

"Anbieter nicht gefunden"-Fehler: Stellen Sie sicher, dass die Issuer-URL korrekt ist und dass der Anbieter OIDC-Discovery (/.well-known/openid-configuration) unterstützt.

"Autorisierung fehlgeschlagen": Prüfen Sie im einfachen Modus, ob E-Mail-Domains korrekt eingegeben wurden (ohne @). Überprüfen Sie im erweiterten Modus, ob die Claim-Namen exakt mit den vom Anbieter gesendeten übereinstimmen, ob der Autorisierungsregelmodus korrekt gesetzt ist (OR vs. AND), und stellen Sie sicher, dass alle erforderlichen Claims im Token vorhanden sind. Aktivieren Sie das Debug-Logging, um die tatsächlichen Claims und die Auswertung der Regeln zu sehen.

"Ungültige Redirect-URI": Stellen Sie sicher, dass die Redirect-URI in Ihrem Anbieter exakt übereinstimmt, fügen Sie den korrekten Port hinzu, wenn eine nicht standardmäßige Konfiguration verwendet wird, und überprüfen Sie, ob das Redirect-URI-Protokoll mit der Konfiguration Ihres Servers übereinstimmt (HTTP oder HTTPS).

Anmeldeschaltfläche nicht sichtbar: Prüfen Sie, ob mindestens eine Autorisierungsregel konfiguriert ist, und verifizieren Sie, dass der Anbieter aktiviert/gespeichert ist.

Autorisierungsmodus Dropdown

Um Probleme zu beheben:

1. Aktivieren Sie das Debug-Logging:

LOG_LEVEL=debug unraid-api start --debug

1. Erlaubte E-Mail-Domains: Geben Sie Domains ohne @ ein (z.B. company.com)

• Erhaltene Ansprüche vom Anbieter.
• Berechtigungsrichtlinienbewertung.
• Token-Validierungsfehler.

Wenn der "erweiterte" Modus ausgewählt ist, sehen Sie:

Wenn Probleme auftreten, prüfen Sie die OIDC-Dokumentation Ihres Anbieters, sehen Sie in den Unraid API-Protokollen nach detaillierten Fehlermeldungen, stellen Sie sicher, dass Ihr Anbieter die standardmäßige OIDC-Discovery unterstützt, und überprüfen Sie die Netzwerkverbindung zwischen Unraid und dem Anbieter. Weitere Hilfe finden Sie in den Unraid-Foren.

Zusätzliche Schnittstellenelemente

Unraid.net-Anbieter

Der Unraid.net-Anbieter ist vorinstalliert und vorkonfiguriert. Sie müssen nur Autorisierungsregeln in der Oberfläche konfigurieren.

Konfiguration:

• Issuer URL: https://accounts.google.com
• Client-ID/Secret: Von Ihren OAuth 2.0-Client-Anmeldedaten
• Redirect-URI: http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback

Hinweis

Passen Sie das Protokoll an Ihre Servereinrichtung an. Verwenden Sie http://, wenn Sie auf Ihren Unraid-Server ohne SSL/TLS zugreifen (typischerweise für den Zugriff im lokalen Netzwerk). Verwenden Sie https://, wenn Sie SSL/TLS auf Ihrem Server konfiguriert haben. Einige OIDC-Anbieter (wie Google) erfordern HTTPS und akzeptieren keine HTTP-Redirect-URIs.

Ersetzen Sie YOUR_UNRAID_IP durch Ihre tatsächliche Server-IP-Adresse (z.B. 192.168.1.100 oder tower.local).

Authelia

Einrichtungsschritte

Richten Sie OAuth 2.0-Anmeldedaten in der Google Cloud Console ein:

1. Gehen Sie zu APIs & Dienste → Anmeldedaten.
2. Klicken Sie auf Anmeldedaten erstellen → OAuth Client-ID.
3. Wählen Sie Webanwendung als Anwendungstyp aus.
4. Fügen Sie Ihre Redirect-URI zu Autorisierte Redirect-URIs hinzu.
5. Konfigurieren Sie den OAuth-Zustimmungsbildschirm, wenn Sie dazu aufgefordert werden.

Konfiguration:

• Speichern Sie Ihre Anbieter-Konfiguration
• Melden Sie sich ab (falls angemeldet)
• Erforderliche Scopes: openid, profile, email
• Redirect-URI: http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback

warnung

Google erfordert gültige Domainnamen für OAuth-Redirect-URIs. Lokale IP-Adressen und .local-Domains werden nicht akzeptiert. Um Google OAuth mit Ihrem Unraid-Server zu verwenden, benötigen Sie:

• Option 1: Reverse Proxy - Richten Sie einen Reverse Proxy (wie NGINX Proxy Manager oder Traefik) mit einem gültigen Domainnamen ein, der auf Ihre Unraid-API zeigt.
• Option 2: Tailscale - Verwenden Sie Tailscale, um eine gültige *.ts.net-Domain zu erhalten, die Google akzeptiert. Weitere Informationen zu Tailscale finden Sie unter Remote access.
• Option 3: Dynamisches DNS - Verwenden Sie einen DDNS-Dienst, um einen öffentlichen Domainnamen für Ihren Server zu erhalten.

Vergessen Sie nicht, Ihre Redirect-URI sowohl in der Google Cloud Console als auch in Ihrer Unraid OIDC-Konfiguration zu aktualisieren, um die gültige Domain zu verwenden.

Für Google-Workspace-Domains verwenden Sie den erweiterten Modus mit dem hd-Claim, um den Zugriff auf die Domain Ihrer Organisation zu beschränken.

"Ungültige Redirect-URI"

Konfigurieren Sie den OIDC-Client in Ihrer Authelia configuration.yml mit der Client-ID unraid-api und generieren Sie ein gehashtes Geheimnis mit dem Authelia-Befehl hash-password.

Konfiguration:

• Überprüfen Sie, ob mindestens eine Autorisierungsregel konfiguriert ist
• Client-ID: unraid-api (oder wie in Keycloak konfiguriert)
• Client-Secret: Aus dem Credentials-Tab von Keycloak
• Erforderliche Scopes: openid, profile, email
• Redirect-URI: http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback

Berechtigungsrichtlinien können in der Schnittstelle mit E-Mail-Domains oder erweiterten Ansprüchen konfiguriert werden.

Authentik

Erstellen Sie einen neuen OAuth2/OpenID-Anbieter in Authentik und erstellen Sie eine Anwendung, die mit dem Anbieter verknüpft ist.

Konfiguration:

• Issuer URL: https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0
• Client-ID: Aus der Authentik-Anbieter-Konfiguration
• Client-Secret: Aus der Authentik-Anbieter-Konfiguration
• Erforderliche Scopes: openid, profile, email
• Redirect-URI: http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback

Berechtigungsrichtlinien können in der Schnittstelle konfiguriert werden.

Debug-Modus

Um Probleme zu beheben:

Konfiguration:

• Issuer URL: https://YOUR_DOMAIN.okta.com
• Client-ID: unraid-api (oder wie in Keycloak konfiguriert)
• Client-Secret: Aus der Okta-Anwendungskonfiguration
• Erforderliche Scopes: openid, profile, email
• Redirect-URI: http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback

Berechtigungsrichtlinien können in der Schnittstelle mit E-Mail-Domains oder erweiterten Ansprüchen konfiguriert werden.

Authentik

Erstellen Sie einen neuen OAuth2/OpenID-Anbieter in Authentik und erstellen Sie eine Anwendung, die mit dem Anbieter verknüpft ist.

Konfiguration:

• Issuer URL: https://authentik.example.com/application/o/<application_slug>/
• Client-ID: Aus der Authentik-Anbieter-Konfiguration
• Client-Secret: Aus der Authentik-Anbieter-Konfiguration
• Erforderliche Scopes: openid, profile, email
• Redirect-URI: http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback

Berechtigungsrichtlinien können in der Schnittstelle konfiguriert werden.

🏢 Anbieter-spezifische Einrichtung

Erstellen Sie eine neue OIDC-Webanwendung in der Okta-Admin-Konsole und weisen Sie entsprechende Benutzer oder Gruppen zu.

Konfiguration:

• Issuer URL: https://YOUR_DOMAIN.okta.com
• Client-ID: Aus der Okta-Anwendungskonfiguration
• Client-Secret: Aus der Okta-Anwendungskonfiguration
• Erforderliche Scopes: openid, profile, email
• Redirect-URI: http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback

Berechtigungsrichtlinien können in der Schnittstelle konfiguriert werden.