Notes on migration | X4Documentation

With version 7.5.0, X4 BPMS introduces a revised authentication architecture based entirely on OpenID Connect (OIDC). Existing installations that still use keycloak_conf.json must be migrated manually.

What has changed?

Area	until X4 BPMS 7.4.x	from X4 BPMS 7.5.0
Configuration	`keycloak_conf.json`	`authentication_config.xml`, `tokenhandler_config.xml`
Authentication flow	Keycloak-specific	OIDC-compliant
Supported identity providers	Keycloak (fully integrated)	All OIDC-compliant IdPs
Ressource Owner Password Flow	Supported (deprecated)	Removed
Token handling in Web Apps	Access token in session	Cookie-based authentication
`.wsinc` / `.wac`: Realm/client overrides	Used	Deprecated, replaced with `Auth Config Name`
Keycloak included in delivery	Yes	No, Keycloak must be set up separately.

Note:

The keycloak_conf.json file is no longer used for authentication.

The file is only evaluated for the Keycloak Management Adapter (if enabled)
The file no longer affects general login mechanisms.
There is no automatic migration.

Recommendation when migrating from X4 BPMS 7.4.x.

Create a backup
- Backup the X4 Server configuration
- Export a Keycloak instance (including Realm)
Update X4 to version 7.5.0
Manually transfer the OIDC configuration
- Create new file authentication_config.xml
- Define the OIDC connection with X4OidcConfig
- Configure optional parameters such as EnableBasicAuth and ReturnChallengeOnFailedAuth
Configure token handling
- Create new file tokenhandler_config.xml
- Assign paths such as /X4/WebApp/* and /X4/X4Api/*
Customize .wsinc/.wac
- Do not use Realm , ClientId , ClientSecret anymore

Recommendation for new installations starting with X4 BPMS 7.5.0

Use an empty Keycloak system.
Import the recommended realm as described in Keycloak Integration with OIDC for X4 Designer and X4 Server.
Configure your OIDC connection only through authentication_config.xml.

Setup recommendations

Scenario	Recommendation
New installation (from X4 BPMS 7.5.0)	Use an empty Keycloak or attach an identity provider of your choice.
Migration from X4 BPMS 7.4.x or earlier	Automatic migration is not possible. Manually transfer the configuration to the new XML files.
Use of multiple identity providers	Create additional `X4OidcConfig` blocks in `authentication_config.xml` and use them specifically via Auth Config Name.