X4 Produktdokumentation
X4 Produktdokumentation
Breadcrumbs

Keycloak-Integration mit OIDC für X4 Designer und X4 Server


Der X4 Designer benötigt Zugriff auf ein Token, ohne ein Client-Secret zu verwenden. Deshalb muss ein separater öffentlicher Client in Keycloak angelegt werden. Der bestehende X4 Client ist ein privater Client und daher nicht für diesen Anwendungsfall geeignet.

X4Realm einrichten

Wählen Sie eine der folgenden Varianten zum Einrichten des Keycloak-Realms.

Hinweis:

Wählen Sie Variante A, wenn Sie eine leere Keycloak-Instanz haben. Wählen Sie Variante B, wenn Sie Ihre Keycloak-Instanz angepasst haben oder wenn Ihnen das Importieren von Daten zu umständlich erscheint. Fahren Sie anschließend mit Verbindung im X4 Designer herstellen fort.

Variante A: Import des vordefinierten Realms (empfohlen für neue Installationen)

  1. Starten Sie Ihre aktuelle Keycloak-Instanz.

  2. Löschen Sie ggf. einen bereits bestehenden Realm mit dem Namen X4Realm.

Wenn Sie den Realm nicht löschen möchten, verwenden Sie Variante B.

  1. Stoppen Sie Keycloak (optional zur Sicherheit).

  2. Starten Sie Keycloak neu.

  3. Melden Sie sich in der Administrationskonsole an.

    image-20250625-115505.png

  4. Wählen Sie Create realm, und laden Sie die Datei X4Realm-realm.json im Bereich Resource file hoch.

  5. Wählen Sie Create aus.

    → Nach dem Import ist der Client X4Designer im neuen Realm X4Realm verfügbar.

Beispielbenutzer (demo) importieren

  1. Navigieren Sie zu X4Realm > Realm settings.

  2. Wählen Sie oben rechts in der Dropdown-Liste Action den Eintrag Partial import aus.

    image-20250625-120055.png

  3. Laden Sie die Datei X4Realm-users-0.json hoch.

  4. Wählen Sie in der Dropdown-Liste If a resource already exists, specify what should be done: den Eintrag Overwrite, wenn der Benutzer bereits existiert.

  5. Wählen Sie Import aus.

→ Der Benutzer demo ist nun mit den erforderlichen Rollen verfügbar.

Variante B: Manueller Client-Eintrag (für bestehende oder angepasste Realms)

  1. Navigieren Sie im bestehenden Realm (z. B. X4Realm) zu Clients.

  2. Wählen Sie Create client aus, um einen Client mit folgenden Einstellungen zu erstellen:

    image-20250625-120331.png

    • General settings:
      Client ID: X4Designer

    • Capability config:
      Client authentication: deaktiviert
      Authentication flow: Standard flow

    • Login settings:
      Valid redirect URIs: x4designer://redirect

  3. Wählen Sie Save aus.

Verbindung im X4 Designer herstellen

  1. Wählen Sie im X4 Designer image-20250625-120537.png > Manage Connections (oder File > Manage Connections) aus.
    ⇾ Das Dialogfenster X4 Preferences wird geöffnet.

  2. Erweitern Sie auf der linken Seite den Eintrag X4 Designer, und wählen Sie Connection aus, um die Verbindungseinstellungen aufzurufen.

    image-20251212-123757.png

  3. Wählen Sie in der Dropdown-Liste Authentication den Eintrag OIDC aus.

  4. Nehmen Sie im Bereich Login Properties folgende Einstellungen vor:

Einstellung

Wert

OIDC URL

http://localhost:8085/auth/realms/X4Realm

Client ID

X4Designer

Alternativ ist weiterhin eine Authentifizierung über Basic Authentication möglich. Dazu wählen Sie in der Dropdown-Liste Authentication den Eintrag Basic aus.

X4 Server mit Keycloak verbinden

Damit sich der X4 Server gegenüber Keycloak authentifizieren kann, müssen folgende Konfigurationsdateien im Ordner configurations des Servers vorhanden sein:

Stellen Sie sicher, dass diese Dateien korrekt konfiguriert und im richtigen Verzeichnis abgelegt sind.