> ## Documentation Index
> Fetch the complete documentation index at: https://docs.varios-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Keycloak einrichten

> Anmeldung, Gruppen, Administratorrollen und Benutzersynchronisation für VARIOS AI mit Keycloak konfigurieren

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

<Info>
  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.
</Info>

## Voraussetzungen

* Keycloak ist installiert und in Betrieb. Wie Sie Keycloak installieren, beschreiben die [Getting-Started-Anleitungen von Keycloak](https://www.keycloak.org/guides#getting-started).
* 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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Token-Laufzeit erhöhen">
    Setzen Sie unter **Realm settings → Tokens** den Wert **Access Token Lifespan** auf `8 Hours` und klicken Sie auf **Save**.
  </Step>
</Steps>

## Client anlegen

<Steps>
  <Step title="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.
  </Step>

  <Step title="Funktionen aktivieren">
    Aktivieren Sie unter **Capability config** die Optionen **Client authentication** und **Service accounts roles**.
  </Step>

  <Step title="URLs eintragen">
    Tragen Sie unter **Login settings** die Adresse Ihrer VARIOS-AI-Installation ein, nicht die von Keycloak:

    | Feld                                | Wert                         |
    | ----------------------------------- | ---------------------------- |
    | **Root URL**                        | `https://<PROJECT_DOMAIN>`   |
    | **Home URL**                        | `https://<PROJECT_DOMAIN>`   |
    | **Valid redirect URIs**             | `https://<PROJECT_DOMAIN>/*` |
    | **Valid post logout redirect URIs** | `https://<PROJECT_DOMAIN>/*` |
    | **Web origins**                     | `https://<PROJECT_DOMAIN>`   |

    Klicken Sie auf **Save**.

    <Info>
      **Web origins** erwartet einen Origin ohne Pfad, also ohne `/*` am Ende.
    </Info>
  </Step>

  <Step title="Client-Secret kopieren">
    Öffnen Sie im Client den Reiter **Credentials** und kopieren Sie das **Client Secret**. Tragen Sie es als `OIDC_CLIENT_SECRET` ein.
  </Step>

  <Step title="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`

    <Info>
      Über den Service Account liest VARIOS AI Benutzer, Gruppen und Gruppenmitgliedschaften aus dem Realm. Ohne diese Rollen schlägt die Benutzersynchronisation fehl.
    </Info>
  </Step>
</Steps>

## Benutzer anbinden

Benutzer können aus einem bestehenden Verzeichnis übernommen oder direkt in Keycloak angelegt werden.

<Tabs>
  <Tab title="LDAP oder Active Directory">
    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.

    <Steps>
      <Step title="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**.

        <Warning>
          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.
        </Warning>
      </Step>

      <Step title="Suche festlegen">
        Legen Sie unter **LDAP searching and updating** fest, welche Benutzer übernommen werden:

        | Feld                                                                     | Wert                                                                               |
        | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
        | **Edit mode**                                                            | `READ_ONLY`, Keycloak schreibt nicht in das Verzeichnis zurück                     |
        | **Users DN**                                                             | Container bzw. OU, in der die Benutzer liegen; eine Gruppe ist hier nicht zulässig |
        | **Username LDAP attribute**                                              | z. B. `sAMAccountName` oder `cn`                                                   |
        | **RDN LDAP attribute**, **UUID LDAP attribute**, **User object classes** | gemäß Ihrem Verzeichnisschema                                                      |
        | **User LDAP filter**                                                     | optional, begrenzt den Import auf die festgelegten Benutzer                        |
        | **Search scope**                                                         | `Subtree`, wenn Benutzer in untergeordneten OUs liegen                             |

        <Warning>
          **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**.
        </Warning>
      </Step>

      <Step title="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.

        <Note>
          Dieser Abgleich synchronisiert nur von LDAP nach Keycloak. Die Übernahme von Keycloak nach VARIOS AI ist ein eigener Vorgang, siehe [Benutzer und Gruppen synchronisieren](#benutzer-und-gruppen-synchronisieren).
        </Note>
      </Step>

      <Step title="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](#gruppen-in-varios-ai). Öffnen Sie im LDAP-Provider den Reiter **Mappers** und fügen Sie einen Mapper vom Typ `group-ldap-mapper` hinzu:

        | Feld                                     | Wert                                                                                |
        | ---------------------------------------- | ----------------------------------------------------------------------------------- |
        | **LDAP Groups DN**                       | Container bzw. OU, in der die Gruppen liegen                                        |
        | **LDAP filter**                          | optional, begrenzt den Import auf die für VARIOS AI vorgesehenen Gruppen            |
        | **Group name LDAP attribute**            | meist `cn`                                                                          |
        | **Membership LDAP attribute**            | z. B. `member`, `memberOf` oder `memberUid`                                         |
        | **Membership attribute type**            | `DN` oder `UID`                                                                     |
        | **Member-Of LDAP attribute**             | meist `memberOf`                                                                    |
        | **Preserve group inheritance**           | deaktivieren, damit alle Gruppen auf der obersten Ebene angelegt werden             |
        | **Drop non-existing groups during sync** | aktivieren, damit im Verzeichnis gelöschte Gruppen auch in Keycloak entfernt werden |

        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.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Lokale Benutzer">
    Lokale Keycloak-Benutzer eignen sich für Tests und kleine Umgebungen ohne Verzeichnisdienst.

    <Steps>
      <Step title="Gruppen anlegen">
        Legen Sie unter **Groups → Create group** die Gruppen an, über die Sie in VARIOS AI Assistenten, KI-Modelle und Konnektoren zuweisen, sowie die Gruppen für die Administratorrollen, siehe [Gruppen in VARIOS AI](#gruppen-in-varios-ai).
      </Step>

      <Step title="Benutzer anlegen">
        Öffnen Sie **Users → Add user** und tragen Sie **Username**, **Email**, **First name** und **Last name** ein. Ordnen Sie den Benutzer über **Join groups** den passenden Gruppen zu und klicken Sie auf **Create**.
      </Step>

      <Step title="Startpasswort setzen">
        Öffnen Sie im Benutzer den Reiter **Credentials**, klicken Sie auf **Set password** und lassen Sie **Temporary** aktiviert. Der Benutzer muss das Passwort bei der ersten Anmeldung ändern.
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Warning>
  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.
</Warning>

## 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](/de/extended-support/admin/groups) 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.

<Note>
  VARIOS AI übernimmt nur Gruppen der obersten Ebene und nur direkte Mitgliedschaften. Untergruppen und darüber vererbte Mitgliedschaften werden nicht berücksichtigt.
</Note>

### Administratorrollen zuordnen

Tragen Sie in der `.env` je Rolle den Namen der zugehörigen Gruppe ein:

| Rolle                    | Variable                      | Beispiel          |
| ------------------------ | ----------------------------- | ----------------- |
| Administrator            | `ADMIN_GROUP_NAME`            | `Admin`           |
| Superadministrator       | `SUPERADMIN_GROUP_NAME`       | `SuperAdmin`      |
| Compliance-Administrator | `COMPLIANCE_ADMIN_GROUP_NAME` | `ComplianceAdmin` |

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

```bash theme={null}
OIDC_PROVIDER=keycloak
OIDC_AUTHORITY=https://<KEYCLOAK_HOST>/realms/<REALM>
OIDC_CONFIGURATION_URL=https://<KEYCLOAK_HOST>/realms/<REALM>/.well-known/openid-configuration
OIDC_CLIENT_ID=<Client ID>
OIDC_CLIENT_SECRET=<Client Secret>
OIDC_LOGOUT_URL=
OIDC_SCOPE=openid profile offline_access
OIDC_USER_IDENTIFIER=preferred_username
OIDC_ROLES_CLAIM=roles
SCIM_DIRECTION=pull
SCIM_MANDANT=<REALM>
SCIM_TOKEN=
SCIM_TENANT_ID=
SCIM_OBJECT_ID=
KEYCLOAK_REALM_BASE_URL=https://<KEYCLOAK_HOST>/realms/<REALM>
KEYCLOAK_ADMIN_REALM_BASE_URL=https://<KEYCLOAK_HOST>/admin/realms/<REALM>
ADMIN_GROUP_NAME=Admin
SUPERADMIN_GROUP_NAME=SuperAdmin
COMPLIANCE_ADMIN_GROUP_NAME=ComplianceAdmin
```

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:

```bash theme={null}
docker compose exec -u www-data php /data/flow usersync:sync --force
```

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