Hinweise zur Migration | X4Documentation

Mit Version 7.5.0 führt X4 BPMS eine überarbeitete Authentifizierungsarchitektur ein, die vollständig auf OpenID Connect (OIDC) basiert. Bestehende Installationen, die noch keycloak_conf.json verwenden, müssen manuell migriert werden.

Was hat sich geändert?

Bereich	bis X4 BPMS 7.4.x	ab X4 BPMS 7.5.0
Konfiguration	`keycloak_conf.json`	`authentication_config.xml`, `tokenhandler_config.xml`
Authentifizierungsablauf	Keycloak-spezifisch	OIDC-standardkonform
Unterstützte Identity Provider	Keycloak (fest integriert)	Alle OIDC-konformen IdPs
Resource Owner Password Flow	Unterstützt (veraltet)	Entfernt
Token-Handling in Web Apps	Access Token in Session	Cookie-basierte Authentifizierung
`.wsinc` / `.wac`: Realm/Client-Overrides	Verwendet	Veraltet, ersetzt durch `Auth Config Name`
Keycloak im Lieferumfang	Ja	Nein, Keycloak muss separat eingerichtet werden.

Hinweis:

Die Datei keycloak_conf.json wird nicht mehr zur Authentifizierung verwendet.

Die Datei wird nur noch für den Keycloak Management Adapter ausgewertet (falls aktiviert)
Die Datei hat keine Auswirkung mehr auf allgemeine Login-Mechanismen.
Es erfolgt keine automatische Migration.

Empfehlung bei Migration von X4 BPMS 7.4.x

Backup erstellen
- X4-Server-Konfiguration sichern
- Keycloak-Instanz exportieren (inkl. Realm)
X4 auf Version 7.5.0 aktualisieren
OIDC-Konfiguration manuell übertragen
- Neue Datei authentication_config.xml anlegen
- OIDC-Verbindung mit X4OidcConfig definieren
- Optionale Parameter wie EnableBasicAuth und ReturnChallengeOnFailedAuth konfigurieren
Token-Handling konfigurieren
- Datei tokenhandler_config.xml anlegen
- Pfade wie /X4/WebApp/* und /X4/X4Api/* zuweisen
.wsinc/.wac anpassen
- Realm, ClientId, ClientSecret nicht mehr verwenden

Empfehlung bei Neuinstallationen ab X4 BPMS 7.5.0

Verwenden Sie ein leeres Keycloak-System.
Importieren Sie das empfohlene Realm wie unter Keycloak-Integration mit OIDC für X4 Designer und X4 Server beschrieben.
Konfigurieren Sie Ihre OIDC-Verbindung ausschließlich über authentication_config.xml

Empfehlungen für das Setup

Szenario	Empfehlung
Neuinstallation (ab X4 BPMS 7.5.0)	Leeren Keycloak verwenden oder Identity Provider nach Wahl anbinden.
Migration von X4 BPMS 7.4.x oder älter	Keine automatische Migration möglich. Konfiguration manuell in die neuen XML-Dateien übertragen.
Nutzung mehrerer Identity Provider	Zusätzliche `X4OidcConfig`-Blöcke in `authentication_config.xml` anlegen und gezielt über Auth Config Name verwenden.