Zum Inhalt

SSO-Einrichtung

Single Sign-On für die Plattform

Die Plattform unterstützt drei SSO-Anmeldeverfahren, die alle nach dem Deployment über das Customer Portal (Einstellungen → SSO) eingerichtet werden:

Typ Anmeldeweg Einsatz
Microsoft Entra ID (azure-ad) Button „Mit Microsoft anmelden" (OIDC) Microsoft-365-/Azure-Tenants
Generisches OIDC (oidc) Social-Login-Button (OIDC) Keycloak, Authentik, Google Workspace u. a.
LDAP / Active Directory (ldap) Login-Formular mit Domänen-Konto On-Premises Windows AD / LDAP

Nur ein aktiver SSO-Provider

Es kann jeweils nur ein SSO-Provider gleichzeitig aktiv sein. Beim Aktivieren eines neuen Providers (z. B. LDAP) wird ein zuvor aktiver Entra-ID-/OIDC-Provider automatisch deaktiviert. Ein LDAP-Anmeldeformular und ein OIDC-Button lassen sich nicht sinnvoll parallel betreiben.

Microsoft Entra ID / Azure AD (OIDC)

Voraussetzungen

  • Azure AD Tenant mit Admin-Zugang
  • Benutzer im Azure AD angelegt

Schritt 1: App-Registrierung in Azure AD

  1. Azure Portal → Azure Active Directory → App-Registrierungen → Neue Registrierung
  2. Name: Inovetra AI Platform
  3. Redirect URI: https://<domain>/api/customer/auth/azure/callback
  4. Unter Zertifikate & Geheimnisse → Neues Client-Secret erstellen → Wert kopieren
  5. Notieren: Tenant ID, Client ID, Client Secret

Schritt 2: SSO im Customer Portal aktivieren

  1. Customer Portal → Einstellungen → SSO
  2. Azure AD Tenant ID, Client ID und Client Secret eintragen
  3. Speichern → Plattform wird automatisch neu konfiguriert

Schritt 3: Testen

  • Im Browser: https://<domain>/ → Login → "Mit Microsoft anmelden" Option sollte erscheinen
  • Test mit einem Azure AD Benutzer durchführen

Fehlerbehebung (Entra ID / OIDC)

Problem Lösung
"Redirect URI mismatch" URI in Azure AD prüfen — muss exakt https://<domain>/api/customer/auth/azure/callback sein
Kein Microsoft-Login-Button SSO-Konfiguration im Customer Portal prüfen, Pods müssen nach Änderung neustarten
"AADSTS50011" Redirect URI in Azure AD stimmt nicht überein

Client Secret Ablaufdatum

Das Client Secret hat ein Ablaufdatum in Azure AD. Vor Ablauf erneuern und im Customer Portal aktualisieren.

LDAP / Active Directory

Anmeldung mit dem Domänen-Konto

Bei LDAP/AD melden sich Benutzer nicht über einen Social-Login-Button an, sondern direkt über das normale Login-Formular mit ihrem Domänen-Konto (E-Mail bzw. Benutzername + Windows-Passwort). LibreChat authentifiziert über passport-ldapauth direkt gegen den Domain Controller.

Voraussetzungen

  • Domain Controller erreichbar: Der DC muss aus der Plattform-/Cluster-Umgebung erreichbar sein — sowohl für den Verbindungstest aus der Customer API als auch für den eigentlichen Login aus dem LibreChat-/Chat-Pod. Erforderlich sind je nach Schema die Ports 389 (LDAP) bzw. 636 (LDAPS).
  • FQDN in der LDAP-URL: Bei ldaps:// oder StartTLS mit Zertifikatsprüfung muss die LDAP-URL den FQDN des Domain Controllers enthalten (z. B. ldaps://dc01.firma.local:636), keine IP-Adresse — der Hostname wird gegen die SANs des Server-Zertifikats geprüft.
  • Such-Basis (Base DN): z. B. OU=Users,DC=firma,DC=local — der Container, unterhalb dessen die Benutzerkonten gesucht werden.
  • Service-Konto (empfohlen): Ein dediziertes AD-Konto für den Bind (z. B. CN=svc-librechat,OU=Service,DC=firma,DC=local). Ein anonymer Bind ist von Active Directory in der Regel nicht erlaubt.
  • Login-Formular aktiv: librechat.allowEmailLogin muss true sein (Standard in den Helm-Values), damit das Anmeldeformular und damit der LDAP-Login überhaupt angezeigt wird.

Schritt 1: Provider im Customer Portal anlegen

  1. Customer Portal → Einstellungen → SSO → Provider hinzufügen
  2. Als Typ „LDAP / Active Directory" auswählen
  3. Felder ausfüllen:
Feld Beschreibung Beispiel
LDAP-Server URL Schema ldap://host:389 (unverschlüsselt) oder ldaps://host:636 (TLS) ldaps://dc01.firma.local:636
Such-Basis (Base DN) Pflichtfeld — Suchbasis für Benutzerkonten OU=Users,DC=firma,DC=local
Bind-DN (Service-Konto) Optional; leer = anonymer Bind (von AD meist nicht erlaubt) CN=svc-librechat,OU=Service,DC=firma,DC=local
Bind-Passwort Passwort des Service-Kontos. Beim Bearbeiten leer lassen = aktuelles Passwort behalten ••••••••
Such-Filter Optional; Standard mail={{username}}. Für Anmeldung per AD-Benutzername z. B. sAMAccountName={{username}} sAMAccountName={{username}}
CA-Zertifikat (PEM) Ab Chart 0.82.0. PEM-Zertifikat der ausstellenden CA für ldaps:///StartTLS. Wird als Kubernetes-Secret inovetra-ldap-ca gespeichert, im Chat-Pod nach /etc/ldap-ca/ca.crt gemountet und über LDAP_CA_CERT_PATH aktiviert -----BEGIN CERTIFICATE-----…
Berechtigte AD-Gruppe (DN) Ab Chart 0.82.0. Optional — wenn gesetzt, dürfen sich nur direkte Mitglieder dieser Gruppe anmelden CN=Inovetra-Chat-Users,CN=Users,DC=firma,DC=local
  1. Optionen je nach Umgebung setzen:
Option Wirkung
Anmeldung per Benutzername statt E-Mail-Adresse Benutzer melden sich mit dem AD-Benutzernamen (sAMAccountName) statt der E-Mail-Adresse an. Such-Filter entsprechend setzen.
StartTLS verwenden Hebt eine unverschlüsselte ldap://-Verbindung per StartTLS auf TLS an.
TLS-Zertifikat nicht prüfen Deaktiviert die Zertifikatsprüfung — gedacht für interne oder selbstsignierte Firmen-Zertifikate, deren Stammzertifikat im Cluster nicht hinterlegt ist.

„TLS-Zertifikat nicht prüfen" allein ist wirkungslos

LibreChat aktiviert seine LDAP-TLS-Optionen (einschließlich rejectUnauthorized) nur, wenn LDAP_CA_CERT_PATH gesetzt ist — also nur, wenn ein CA-Zertifikat (PEM) hinterlegt wurde. Bei internen oder selbstsignierten Zertifikaten daher immer das CA-Zertifikat im Provider-Formular eintragen; die Checkbox allein ändert am TLS-Verhalten nichts.

Schritt 2: Verbindung testen

Über den Verbindungstest-Button wird ein echter LDAP-Bind gegen den Domain Controller ausgeführt (nicht nur ein Discovery-Fetch wie bei OIDC). Ist ein CA-Zertifikat hinterlegt, prüft der Test die TLS-Verbindung mit verpflichtender Zertifikatsvalidierung gegen genau diese CA — inklusive Hostname-Abgleich gegen die SANs des Server-Zertifikats (daher den FQDN in der URL verwenden). Schlägt der Test fehl, sind die Verbindungs- oder Bind-Daten zu prüfen, bevor der Provider aktiviert wird.

Schritt 3: Provider aktivieren

Nach dem Speichern und Aktivieren werden am Chat-Deployment die LDAP_*-Umgebungsvariablen gesetzt (das Bind-Passwort stammt aus einem Kubernetes-Secret) und das Deployment wird neu gestartet. Anschließend zeigt das Login-Formular die Anmeldung mit dem Domänen-Konto an. Ab Chart 0.82.0 gilt zusätzlich:

  • CA-Zertifikat: Ist ein CA-Zertifikat hinterlegt, wird es als Secret inovetra-ldap-ca in den Chat-Pod nach /etc/ldap-ca/ca.crt gemountet und LDAP_CA_CERT_PATH gesetzt.
  • AD-Gruppe: Ist eine berechtigte AD-Gruppe (DN) gesetzt, komponiert die Plattform den Such-Filter als (&(<Benutzer-Klausel>)(memberOf=<Gruppen-DN>)). Die Benutzer-Klausel ist der explizit gesetzte Such-Filter oder — je nach Option „Anmeldung per Benutzername" — sAMAccountName={{username}} bzw. mail={{username}}. Es zählt nur die direkte Gruppenmitgliedschaft (keine verschachtelten Gruppen).
  • Anzeigename: LDAP_FULL_NAME=displayName wird immer gesetzt — der Chat begrüßt Benutzer mit ihrem echten Namen statt mit dem Konto-Kürzel.

Ab Chart 0.82.4 gilt außerdem:

  • Kurze AD-Passwörter: Die Passwort-Richtlinie liegt vollständig beim Active Directory — auch Domänen-Passwörter mit weniger als 8 Zeichen werden akzeptiert. Vorher blockierte die clientseitige Prüfung des Login-Formulars solche Konten (lokale Mindestlänge 8 Zeichen). Lokale Chat-Anmeldungen sind bei aktivem LDAP ohnehin deaktiviert.

Nach dem Update auf 0.82.4: Provider einmal deaktivieren und reaktivieren

Ist beim Update auf Chart 0.82.4 bereits ein LDAP-Provider eingerichtet, diesen im Customer Portal einmal deaktivieren und wieder aktivieren, damit alle Verbesserungen sicher greifen.

Nur ein aktiver Provider

Wird LDAP aktiviert, deaktiviert die Plattform automatisch einen zuvor aktiven Entra-ID-/OIDC-Provider. Siehe Hinweis am Seitenanfang.

Benutzer-Import und Portal-Zugang

  • Automatischer Import: Meldet sich ein AD-Benutzer erstmals im Chat an, wird das Konto automatisch in die Benutzerverwaltung des Customer Portals importiert (Badge „LDAP / AD") — ab Chart 0.82.4 innerhalb von ca. 2 Minuten (vorher bis zu 10 Minuten). Importierte LDAP-Konten sind vorab freigegeben, da der Zugang bereits über die berechtigte AD-Gruppe gesteuert wird.
  • Portal-Anmeldung mit dem Domänen-Konto: LDAP-Benutzer melden sich auch am Customer Portal mit ihren AD-Zugangsdaten an — wahlweise mit dem AD-Kontonamen (sAMAccountName) oder der E-Mail-Adresse; es gelten dieselben Zugangsdaten wie im Chat. Der Gruppen-Filter gilt auch hier.
  • Rollen-Voraussetzung: Für das Portal ist mindestens die Rolle RAG-Manager erforderlich. Benutzer mit der Rolle „User" erhalten nach korrekter Passwortprüfung eine deutsche Fehlermeldung (nur Chat-Zugriff — mindestens RAG-Manager erforderlich); nicht freigegebene Konten sehen den Hinweis, dass das Konto auf Freigabe wartet.

Fehlerbehebung (LDAP / AD)

Problem Lösung
Bind fehlgeschlagen (Verbindungstest oder Login) Bind-DN und Bind-Passwort prüfen. Bei leerem Bind-DN versucht die Plattform einen anonymen Bind, den AD meist ablehnt → Service-Konto eintragen.
Zertifikatsfehler bei ldaps:// Internes/selbstsigniertes Zertifikat → das CA-Zertifikat (PEM) im Provider-Formular hinterlegen (ab Chart 0.82.0). „TLS-Zertifikat nicht prüfen" allein ist wirkungslos, da LibreChat seine TLS-Optionen nur mit hinterlegtem CA-Zertifikat aktiviert.
„unable to verify the first certificate" Das DC-Zertifikat stammt von einer internen CA, die dem Chat-Pod nicht bekannt ist → CA-Zertifikat (PEM) im Portal hinterlegen. Zusätzlich prüfen, ob die LDAP-URL den FQDN (nicht die IP) enthält.
„SASLprep error: ASCII control character present" Beim Kopieren ist ein unsichtbares Steuerzeichen (z. B. Tabulator) ins Bind-Passwort oder einen DN geraten. Ab Chart 0.82.0 bereinigt die Plattform Steuerzeichen automatisch; bei älteren Versionen den Wert von Hand neu eingeben.
Login trotz korrekter Zugangsdaten abgelehnt (AD-Gruppe gesetzt) Es zählt nur die direkte Mitgliedschaft in der berechtigten AD-Gruppe — verschachtelte Gruppen werden nicht aufgelöst. Gruppen-DN prüfen.
Kein Login-Formular sichtbar librechat.allowEmailLogin muss true sein, damit das Anmeldeformular (und damit der LDAP-Login) erscheint.
Domain Controller nicht erreichbar Firewall/Routing prüfen — der DC muss aus dem Cluster über Port 389 bzw. 636 erreichbar sein (Test und Login laufen aus der Cluster-Umgebung).
Benutzer wird nicht gefunden Such-Basis (Base DN) und Such-Filter prüfen. Bei Benutzername-Anmeldung Filter sAMAccountName={{username}} setzen und die Checkbox aktivieren.
Login mit kurzem AD-Passwort (unter 8 Zeichen) abgelehnt Ab Chart 0.82.4 unterstützt — die Passwort-Richtlinie liegt vollständig beim AD. Plattform aktualisieren und den LDAP-Provider einmal deaktivieren und wieder aktivieren.

Siehe auch