Skip to main content
VARIOS AI meldet Nutzer über OpenID Connect an. Diese Seite beschreibt die Einrichtung eines Realms und eines Clients in Keycloak, die Anbindung von Benutzern aus LDAP bzw. Active Directory oder als lokale Keycloak-Benutzer sowie die zugehörigen Werte für die .env.
Diese Anleitung beschreibt eine bewährte Konfiguration (Best Practice). Passen Sie die Schritte bei Bedarf an Ihre Umgebung an. Unabhängig vom gewählten Weg müssen die Service-Account-Rollen, die Werte in der .env und die Gruppenstruktur den Anforderungen auf dieser Seite entsprechen.

​
Voraussetzungen

  • Keycloak ist installiert und in Betrieb. Wie Sie Keycloak installieren, beschreiben die Getting-Started-Anleitungen von Keycloak.
  • Sie können sich an der Keycloak-Admin-Konsole anmelden und haben die Berechtigung, einen Realm und einen Client anzulegen und zu konfigurieren.
  • VARIOS AI erreicht Keycloak unter dessen Domain per HTTPS, standardmäßig über TCP-Port 443. Der Domainname muss aus der Laufzeitumgebung von VARIOS AI auflösbar sein; bei einem abweichenden HTTPS-Port muss dieser erreichbar sein.
  • Die Domain der VARIOS-AI-Installation ist bekannt. Für eine Anbindung an LDAP oder Active Directory benötigen Sie außerdem die mit der zuständigen Person abgestimmten Verbindungs- und Suchdaten.
Ersetzen Sie in allen Schritten <PROJECT_DOMAIN> durch die Domain Ihrer VARIOS-AI-Installation (z. B. varios.example.com), <KEYCLOAK_HOST> durch die Domain Ihrer Keycloak-Instanz (z. B. keycloak.example.com) und <REALM> durch den Namen des Realms.

​
Realm anlegen

1

Realm erstellen

Wählen Sie in der Admin-Konsole über die Realm-Auswahl Create realm. Tragen Sie unter Realm name einen eindeutigen Namen ein, z. B. varios-ai, und klicken Sie auf Create. Der Realmname ist Bestandteil aller URLs, die Sie später in die .env eintragen.
2

Login-Einstellungen festlegen

Optional: Vergeben Sie unter Realm settings → General einen Display name, wenn auf der Anmeldeseite statt „Keycloak“ der Name Ihrer Organisation oder „VARIOS AI“ erscheinen soll.Aktivieren Sie unter Realm settings → Login die Option Remember me. Aktivieren Sie Email as username, wenn sich Nutzer mit ihrer E-Mail-Adresse statt mit ihrem Benutzernamen anmelden sollen.
3

Token-Laufzeit erhöhen

Setzen Sie unter Realm settings → Tokens den Wert Access Token Lifespan auf 8 Hours und klicken Sie auf Save.

​
Client anlegen

1

Client erstellen

Öffnen Sie Clients → Create client. Wählen Sie als Client type OpenID Connect und vergeben Sie eine Client ID, etwa variosai. Die Client ID tragen Sie als OIDC_CLIENT_ID ein; sie ist nicht identisch mit dem Realmnamen.
2

Funktionen aktivieren

Aktivieren Sie unter Capability config die Optionen Client authentication und Service accounts roles.
3

URLs eintragen

Tragen Sie unter Login settings die Adresse Ihrer VARIOS-AI-Installation ein, nicht die von Keycloak:Klicken Sie auf Save.
Web origins erwartet einen Origin ohne Pfad, also ohne /* am Ende.
4

Client-Secret kopieren

Öffnen Sie im Client den Reiter Credentials und kopieren Sie das Client Secret. Tragen Sie es als OIDC_CLIENT_SECRET ein.
5

Service-Account-Rollen zuweisen

Öffnen Sie im Client den Reiter Service accounts roles und klicken Sie auf Assign role. Stellen Sie den Filter auf Filter by clients um und weisen Sie die folgenden Rollen des Clients realm-management zu:
  • view-users
  • view-groups
  • query-users
  • query-groups
Über den Service Account liest VARIOS AI Benutzer, Gruppen und Gruppenmitgliedschaften aus dem Realm. Ohne diese Rollen schlägt die Benutzersynchronisation fehl.

​
Benutzer anbinden

Benutzer können aus einem bestehenden Verzeichnis übernommen oder direkt in Keycloak angelegt werden.
Keycloak liest Benutzer und Gruppen aus Ihrem Verzeichnis und stellt sie VARIOS AI bereit. Alle Verzeichniswerte hängen von Ihrem Schema ab.Klären Sie vor dem ersten Import mit der für das Verzeichnis zuständigen Person: Verbindungsadresse und Zertifikat bzw. CA, Bind-Konto, Basis-DNs für Benutzer und Gruppen, Suchbereich, gegebenenfalls Benutzer- und Gruppenfilter sowie die verwendeten Attribute für Benutzernamen, eindeutige Kennungen und Gruppenmitgliedschaften. Legen Sie gemeinsam fest, welche Benutzer und Gruppen für VARIOS AI vorgesehen sind. Nicht standardmäßige Verzeichnisschemata erfordern gegebenenfalls fachliche Unterstützung.
1

LDAP-Provider anlegen

Öffnen Sie User federation und fügen Sie einen LDAP-Provider hinzu. Vergeben Sie einen UI display name und wählen Sie den Vendor, z. B. Active Directory. Tragen Sie die Connection URL Ihres Verzeichnisses ein, als Bind DN eine Leseidentität (Bind-DN oder UPN) und unter Bind credentials deren Passwort. Prüfen Sie die Angaben mit Test connection und Test authentication.
Verwenden Sie ausschließlich eine verschlüsselte Verbindung: ldaps:// oder ldap:// mit aktivierter Option Enable StartTLS. Deaktivieren Sie bei StartTLS Connection pooling. Der Hostname in der Connection URL muss zum Zertifikat des Verzeichnisservers passen. Ist das Zertifikat von einer internen CA signiert, muss Keycloak dieser CA vertrauen. Prüfen Sie bei Zertifikatsfehlern Hostname, Zertifikatskette und Truststore, bevor Sie fortfahren.
2

Suche festlegen

Legen Sie unter LDAP searching and updating fest, welche Benutzer übernommen werden:
Users DN ist ein Suchcontainer, keine AD-Gruppe. Ist die Basis zu weit gefasst und kein passender User LDAP filter gesetzt, werden mehr Benutzer als beabsichtigt nach Keycloak und anschließend nach VARIOS AI übernommen. Prüfen Sie den Umfang im Hinblick auf Berechtigungen und Lizenzplanung, bevor Sie Sync all users ausführen, und berücksichtigen Sie dabei auch den Search scope.
3

Synchronisation einrichten

Aktivieren Sie unter Synchronization settings die Option Periodic changed users sync, legen Sie das Intervall passend zur gewünschten Aktualität fest, z. B. 86400 Sekunden für eine tägliche Synchronisation, und speichern Sie. Führen Sie anschließend über Action → Sync all users den ersten Import aus. Prüfen Sie unter Users Anzahl und Identität der übernommenen Benutzer und korrigieren Sie Basis-DN bzw. Filter, wenn Benutzer fehlen oder zu viele importiert wurden.
Dieser Abgleich synchronisiert nur von LDAP nach Keycloak. Die Übernahme von Keycloak nach VARIOS AI ist ein eigener Vorgang, siehe Benutzer und Gruppen synchronisieren.
4

Gruppen-Mapper anlegen

Über den Gruppen-Mapper übernimmt Keycloak die Gruppen aus Ihrem Verzeichnis, die VARIOS AI für Zuweisungen und Rollen benötigt, siehe Gruppen in VARIOS AI. Öffnen Sie im LDAP-Provider den Reiter Mappers und fügen Sie einen Mapper vom Typ group-ldap-mapper hinzu:Speichern Sie den Mapper und führen Sie über Action → Sync LDAP groups to Keycloak den Gruppenimport aus. Prüfen Sie unter Groups, ob nur die vorgesehenen Gruppen mit den erwarteten Mitgliedern vorhanden sind. Sind nach Sync all users keine Gruppen sichtbar, lösen Sie den Gruppenimport über den Mapper gesondert aus.
VARIOS AI übernimmt nur Benutzer, bei denen Email, First name und Last name gefüllt sind. Benutzer ohne diese Angaben werden bei der Synchronisation übersprungen.

​
Gruppen in VARIOS AI

VARIOS AI übernimmt die Gruppen aus Keycloak mit ihren Mitgliedern. Die Gruppen werden in VARIOS AI für zwei Zwecke verwendet:
  • Zugriff auf Ressourcen: Unter Gruppen weisen Sie den Gruppen Assistenten, KI-Modelle und Konnektoren zu und legen Budgets fest.
  • Administratorrollen: Mitglieder bestimmter Gruppen erhalten die Administratorrollen in VARIOS AI.
Legen Sie in Keycloak nur die Gruppen an bzw. übernehmen Sie aus Ihrem Verzeichnis nur die Gruppen, die Sie benötigen, um in VARIOS AI Zugriffe zu steuern, zum Beispiel Abteilungen oder Projektteams.
VARIOS AI übernimmt nur Gruppen der obersten Ebene und nur direkte Mitgliedschaften. Untergruppen und darüber vererbte Mitgliedschaften werden nicht berücksichtigt.

​
Administratorrollen zuordnen

Tragen Sie in der .env je Rolle den Namen der zugehörigen Gruppe ein: Der Gruppenname muss exakt übereinstimmen, einschließlich Groß- und Kleinschreibung. Je Variable ist genau ein Gruppenname möglich. Bestehende Gruppen aus Ihrem Verzeichnis müssen nicht umbenannt werden; tragen Sie deren Namen in die Variablen ein.

​
Werte für die .env

Verwenden Sie für SCIM_MANDANT den Realmnamen. OIDC_LOGOUT_URL, SCIM_TOKEN, SCIM_TENANT_ID und SCIM_OBJECT_ID werden für Keycloak nicht benötigt und bleiben leer. Entfernen Sie die Variablen nicht vollständig aus der .env, sonst gibt Docker Compose beim Start Warnungen aus.

​
Benutzer und Gruppen synchronisieren

VARIOS AI liest Benutzer, Gruppen und Gruppenmitgliedschaften über den Service Account des Clients aus Keycloak. Dieser Abgleich ist unabhängig von der Synchronisation zwischen LDAP und Keycloak. Das Intervall legen Sie unter Admin-Menü → Einstellungen → Allgemein im Feld Benutzer-Synchronisation Pull-Intervall (Minuten) fest; standardmäßig beträgt es fünf Minuten. In Keycloak gelöschte Benutzer und Gruppen werden dabei auch in VARIOS AI entfernt. Die Administratorrollen werden bei der Anmeldung anhand der synchronisierten Gruppenmitgliedschaften gesetzt. Wird ein Benutzer neu in eine Administratorgruppe aufgenommen, erhält er die Rolle nach der nächsten Synchronisation und einer erneuten Anmeldung. Um die Synchronisation sofort auszulösen, klicken Sie unter Admin-Menü → Einstellungen → Allgemein auf Jetzt synchronisieren. Alternativ führen Sie auf dem Server aus:
Ohne --force wird die Synchronisation übersprungen, wenn die letzte innerhalb des eingestellten Intervalls lief.

​
Prüfung

  • Ein Benutzer aus dem Realm kann sich an VARIOS AI anmelden.
  • Ein Benutzer aus der Gruppe für SUPERADMIN_GROUP_NAME sieht das Menü Administration.
  • Unter Administration → Benutzer und Gruppen erscheinen die synchronisierten Einträge.
  • Ein Benutzer sieht die Assistenten, Modelle und Konnektoren, die seinen Gruppen zugewiesen sind.
  • Bei einer LDAP-Anbindung stimmen Anzahl und Identität der synchronisierten Benutzer und Gruppen mit der vorab festgelegten Auswahl überein.
  • Eine geänderte Gruppenmitgliedschaft kommt in Keycloak und anschließend in VARIOS AI an und wirkt nach einer erneuten Anmeldung.
  • Ein im Verzeichnis bzw. in Keycloak entfernter Testbenutzer wird auch in VARIOS AI entfernt.
Schlägt die Anmeldung fehl, prüfen Sie zuerst die Valid redirect URIs und das Client-Secret. Fehlen Benutzer, prüfen Sie Email, First name und Last name sowie die Service-Account-Rollen. Fehlen Administratorrechte, prüfen Sie die exakte Schreibweise der Gruppennamen in der .env.