Zum Hauptinhalt springen

OIDC-Anbieter-Einrichtung

What Was ist OIDC?

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

Diese Anleitung führt Sie durch die Konfiguration von OIDC (OpenID Connect)-Anbietern für die SSO-Authentifizierung in der Unraid-API über die Weboberfläche.

🚀 Schnellstart​

Zu den OIDC-Einstellungen gelangen
  1. Navigieren Sie zur Weboberfläche 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-Seite mit SSO-Optionen Login-Seite zeigt traditionelles Login-Formular mit SSO-Optionen - "Mit Unraid.net anmelden" und "Mit Google anmelden" Schaltflächen

Die Oberfläche umfasst:

  • 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)​

Der einfache Modus ist der einfachste Weg, die Autorisierung zu konfigurieren. Sie können:

  • 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

Autorisierungsregeln​

Konfiguration von Autorisierungsregeln Erweiterte Autorisierungsregeln zeigen die JWT-Anspruchskonfiguration mit E-Mail endetMit-Operator für domänenbasierten Zugriffskontrolle

Beispiele für den einfachen Modus​

Unternehmensdomain zulassen​

Im einfachen Autorisierungsmodus:

  • Erlaubte E-Mail-Domains: Geben Sie company.com ein
  • Dies erlaubt jedem mit einer @company.com-E-Mail

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​

  • Entwickler-Sandbox aktivieren: Umschalten, um die GraphQL-Sandbox unter /graphql zu aktivieren
  • Die Schnittstelle verwendet ein dunkles Thema für bessere Sichtbarkeit
  • Feldvalidierungsanzeigen helfen, die korrekte Konfiguration sicherzustellen

Erforderliche Redirect-URI​

Important Konfiguration

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).

Format der Herausgeber-URL​

Das Feld Herausgeber-URL akzeptiert beide Formate, aber Basis-URL wird für die Sicherheit dringend empfohlen:

  • Basis-URL (empfohlen): https://accounts.google.com
  • Volle Entdeckungs-URL: https://accounts.google.com/.well-known/openid-configuration

⚠️ 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.

Beispiele für korrekte Basis-URLs:

  • Google: https://accounts.google.com
  • Microsoft/Azure: https://login.microsoftonline.com/IHR_TENANT_ID/v2.0
  • Keycloak: https://keycloak.example.com/realms/IHR_REALM
  • Authelia: https://auth.ihredomain.com

✅ Konfiguration testen​

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

  1. Speichern Sie Ihre Anbieter-Konfiguration
  2. Melden Sie sich ab (falls angemeldet)
  3. Navigieren Sie zur Anmeldeseite
  4. Ihre konfigurierte Anbieterschaltfläche sollte angezeigt werden
  5. Klicken Sie, um den Anmeldevorgang zu testen

🔧 Fehlerbehebung​

Häufige Probleme​

Fehler "Anbieter nicht gefunden"​

  • Stellen Sie sicher, dass die Herausgeber-URL korrekt ist
  • Überprüfen Sie, ob der Anbieter die OIDC-Erkennung unterstützt (/.well-known/openid-configuration)

"Autorisierung fehlgeschlagen"​

  • Im einfachen Modus: Überprüfen, ob E-Mail-Domains korrekt eingegeben sind (ohne @)
  • Im erweiterten Modus:
    • Überprüfen Sie, ob Anspruchsnamen exakt dem entsprechen, was Ihr Anbieter sendet
    • Prüfen, ob der Autorisierungsregelmodus korrekt eingestellt ist (ODER vs UND)
    • Stellen Sie sicher, dass alle erforderlichen Ansprüche im Token vorhanden sind
  • Aktivieren Sie das Debug-Logging, um tatsächliche Ansprüche und Regelbewertungen anzuzeigen

"Ungültige Redirect-URI"​

  • Stellen Sie sicher, dass die Redirect-URI in Ihrem Anbieter exakt übereinstimmt
  • Geben Sie den korrekten Port an, wenn eine nicht standardmäßige Konfiguration verwendet wird
  • Überprüfen Sie, ob das Protokoll der Redirect-URI mit der Konfiguration Ihres Servers (HTTP oder HTTPS) übereinstimmt

Anmeldeschaltfläche nicht sichtbar​

  • Überprüfen Sie, ob mindestens eine Autorisierungsregel konfiguriert ist
  • Stellen Sie sicher, dass der Anbieter aktiviert/gespeichert ist

Debug-Modus​

Um Probleme zu beheben:

  1. Aktivieren Sie das Debug-Logging:
LOG_LEVEL=debug unraid-api start --debug
  1. Protokolle überprüfen auf:
  • Erhaltene Ansprüche vom Anbieter
  • Berechtigungsrichtlinienbewertung
  • Token-Validierungsfehler

🔐 Sicherheits-Best-Practices​

  1. Einfache Methode für die Autorisierung verwenden - Verhindert zu einladende Konfigurationen und reduziert Fehlkonfigurationsrisiken
  2. Sei spezifisch bei der Autorisierung - Verwende keine allzu breiten Regeln
  3. Geheimnisse regelmäßig rotieren - Aktualisiere die Client-Geheimnisse regelmäßig
  4. Gründlich testen - Verifizieren, dass nur beabsichtigte Benutzer Zugang haben

💡 Brauchst du Hilfe?​

  • Überprüfen Sie die OIDC-Dokumentation des Anbieters
  • Überprüfen Sie die Unraid-API-Protokolle auf detaillierte Fehlermeldungen
  • Stellen Sie sicher, dass Ihr Anbieter den OIDC-Standard unterstützt.
  • Überprüfen Sie die Netzwerkverbindung zwischen Unraid und dem Anbieter

🏢 Anbieter-spezifische Einrichtung​

Unraid.net Anbieter​

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

Konfiguration:

  • Issuer URL: Vorkonfiguriert (eingebauter Anbieter)
  • Client-ID/Secret: Vorkonfiguriert (eingebauter Anbieter)
  • Redirect-URI: http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback
Redirect URI-Protokoll

Passen Sie das Protokoll an Ihre Serverkonfiguration an: Verwenden Sie http://, wenn Sie auf Ihren Unraid-Server ohne SSL/TLS zugreifen (typisch 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.

Konfigurieren Sie Berechtigungsrichtlinien mit einfacher Methode (erlaubte E-Mail-Domains/Adressen) oder erweiterter Methode für komplexe Anforderungen.

Google​

📋 Einrichtungs-Schritte

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:

  • Issuer URL: https://accounts.google.com
  • Client-ID/Secret: Von Ihren OAuth 2.0-Client-Anmeldedaten
  • Erforderliche Scopes: openid, profile, email
  • Redirect-URI: http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback
Google Domain-Anforderungen

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
  • 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 die erweiterte Methode mit dem hd-Anspruch, um den Zugang auf die Domain Ihrer Organisation zu beschränken.

Authelia​

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:

  • Issuer URL: https://auth.yourdomain.com
  • Client-ID: unraid-api (oder wie in Authelia konfiguriert)
  • Client-Secret: Ihr ungehashtes Geheimnis
  • Erforderliche Scopes: openid, profile, email, groups
  • Redirect-URI: http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback

Verwenden Sie die erweiterte Methode mit dem groups-Anspruch für eine gruppenbasierte Autorisierung.

Microsoft/Azure AD​

Registrieren Sie eine neue App im Azure Portal unter Azure Active Directory → App-Registrierungen. Notieren Sie sich die Anwendungs-ID, erstellen Sie ein Client-Geheimnis und notieren Sie sich Ihre Mandanten-ID.

Konfiguration:

  • Issuer URL: https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0
  • Client-ID: Ihre Anwendungs-(Client)ID
  • Client-Secret: Generiertes Client-Geheimnis
  • 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.

Keycloak​

Erstellen Sie einen neuen vertraulichen Client in der Keycloak-Admin-Konsole mit dem openid-connect-Protokoll und kopieren Sie das Client-Geheimnis aus dem Anmeldedaten-Tab.

Konfiguration:

  • Issuer URL: https://keycloak.example.com/realms/YOUR_REALM
  • 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

Für rollenbasierte Autorisierung verwenden Sie die erweiterte Methode mit dem realm_access.roles- oder resource_access-Anspruch.

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.

Okta​

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 mit E-Mail-Domains oder erweiterten Ansprüchen konfiguriert werden.