Authentication & IAM migration

Authentication is the single largest break in the 5.1 → 5.9 upgrade. The model changes in three coordinated areas: service-account client naming, two-realm architecture, and JWT token validation. 5.1.x customers absorb the full transition during the upgrade.

Hard prerequisite for booting any 5.9.x service. All FlowX services validate access tokens against the new Keycloak two-realm architecture and reject the legacy opaque-token + per-service realm configuration. Plan this section before the upgrade window. Services will not start with 5.1.x auth env vars left in place.

What changed at the platform level

Concern	5.1.x	5.9.x
Token validation	Opaque-token introspection against Keycloak	JWT public-key validation (`SECURITY_TYPE: jwt-public-key`)
Service-account client naming	Per-service ad-hoc names	Standardized `flowx-{service-name}-sa` pattern
Realm architecture	Single Keycloak realm	Two realms — user realm + dedicated service-accounts realm
User realm name	`flowx` (or custom)	Your organization ID — the UUID provided by FlowX during organization registration
Service-accounts realm UUID	n/a	`00000002-0002-4002-8002-000000000002`
`flowx-platform-authorize` client	Used for legacy token introspection	Removed — no longer needed
SMTP	Optional	Required in Keycloak for password reset and user invitations

Service-account client renames

Every FlowX service authenticates to Keycloak through a service-account client. On 5.9.x these clients all follow the flowx-{service-name}-sa pattern, in the dedicated service-accounts realm (00000002-0002-4002-8002-000000000002). On a 5.1 → 5.9 upgrade, the authorization-system service migrates the existing flowx realm — renaming it to your organization ID — and provisions the new service-accounts realm at first boot, including the clients below. The list is provided as a verification reference and as the source list for the Manual Keycloak Configuration path.

Client ID	Used by
`flowx-admin-sa`	admin
`flowx-process-engine-sa`	process-engine
`flowx-integration-designer-sa`	integration-designer
`flowx-authorization-system-sa`	authorization-system
`flowx-runtime-manager-sa`	runtime-manager
`flowx-scheduler-core-sa`	scheduler-core
`flowx-task-management-plugin-sa`	task-management-plugin
`flowx-organization-manager-sa`	organization-manager
`flowx-email-gateway-sa`	email-gateway
`flowx-license-sa`	license
`flowx-webhook-gateway-sa`	webhook-gateway
`flowx-file-gateway-sa`	file-gateway
`flowx-anonymous-sa`	admin, application-manager, authorization-system, document-plugin, email-gateway, events-gateway, file-gateway, integration-designer, license, mock-server, nosql-db-runner, organization-manager, process-engine, scheduler-core, task-management-plugin, webhook-gateway — for inter-service calls on anonymous (unauthenticated) runtime flows

flowx-anonymous-sa uses a dedicated, low-privilege realm role. Unlike the other service-account clients above, this one is not assigned SA_FLOWX. The migration creates a new SA_FLOWX_ANONYMOUS realm role in the service-accounts realm and assigns it only that role. This caps the blast radius if the token leaks: an attacker can only invoke endpoints reachable to an anonymous internet visitor on processes or UI flows that explicitly opted into the Anonymous runtime role.

Manual Keycloak Configuration path. If your environment does not allow FlowX to administer Keycloak directly (for example, restricted enterprise deployments), follow the Manual Keycloak Configuration recipe. On this path the realm rename is your responsibility: the user realm’s Realm name must equal your organization ID, because services resolve the organization from the token issuer URI (<auth-server>/realms/<organization-id>). See Manual Keycloak configuration for the complete realm, client, and mapper setup.

End-user group membership from Keycloak or an external IDP. This page covers authentication only. If your 5.1.x setup sources end-user group membership from Keycloak groups or a federated IDP — rather than administering it in FlowX after the upgrade — that membership reaches runtime authorization through the attributes.runtimeGroups token claim, which needs a mapper that is not provisioned automatically. See Runtime authorization migration → keeping group membership in Keycloak and the Runtime groups attribute mapper setup steps.

Remove legacy authentication env vars

Strip the following from every service’s Helm values / env files. These belong to the opaque-token introspection model and will prevent services from starting on 5.9.x.

Environment Variable	Affected services
`SPRING_SECURITY_OAUTH2_RESOURCESERVER_OPAQUETOKEN_INTROSPECTIONURI`	14 services
`SPRING_SECURITY_OAUTH2_RESOURCESERVER_OPAQUETOKEN_CLIENTID`	14 services
`SPRING_SECURITY_OAUTH2_RESOURCESERVER_OPAQUETOKEN_CLIENTSECRET`	14 services
`SECURITY_OAUTH2_REALM`	14 services
`SECURITY_OAUTH2_CLIENT_CLIENTID`	14 services
`SECURITY_OAUTH2_CLIENT_CLIENTSECRET`	14 services
`SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_CLIENTID`	8 services
`SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_CLIENTSECRET`	8 services

flowx-platform-authorize Keycloak client. This client was used for legacy authorization paths and is no longer referenced anywhere in 5.9.x. Delete it from your Keycloak configuration after the upgrade completes.

New required env vars

Add the following across all services. Defaults shown are the canonical 5.9.x defaults. Override only when your environment requires a different value.

On every service (19 of 19)

Environment Variable	Description	Default Value
`SECURITY_TYPE`	Token validation mechanism. Replaces opaque-token introspection.	`jwt-public-key`
`SECURITY_OAUTH2_SAREALM`	Realm UUID for service-to-service authentication.	`00000002-0002-4002-8002-000000000002`
`FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL`	URL of the organization-manager service.	`-` (set per deployment)

Set SECURITY_TYPE explicitly on every service — do not rely on a chart default. JWT validation only activates when SECURITY_TYPE is set to jwt-public-key. The legacy opaque-token mode runs under SECURITY_TYPE: oauth2. If your Helm values, or a wrapper chart layered on top of the FlowX chart, leave SECURITY_TYPE unset, services keep validating tokens with opaque-token introspection and authentication fails against the 5.9.x two-realm setup. Set jwt-public-key on all 19 services as part of the upgrade.

ORGANIZATION_ID is not required on every service. Only on the 9 services that backfill organization_id columns via Liquibase (application-manager, authorization-system, cms-core, document-plugin, integration-designer, notification-plugin, organization-manager, process-engine, scheduler-core). The license service consumes the same UUID through a separate env var, FLOWX_LICENSE_ORGANIZATIONID. See Organization & deployment configuration for the exact behavior across fresh-install vs upgrade scenarios.

On the 8 services that initiate service-to-service calls

These services have a MAINIDENTITY client registration that follows the new service-account naming convention.

Environment Variable	New Default
`SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID`	`flowx-${spring.application.name}-sa`
`SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET`	`-` (Keycloak-issued)
`SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI`	Now references `${security.oauth2.sa-realm}` instead of `${security.oauth2.realm}`

On `authorization-system` (master-realm administration)

By default, the authorization-system performs realm migrations on startup and needs master-realm admin credentials. This behavior is controlled by SECURITY_KEYCLOAKADMINENABLED, which defaults to true (FlowX administers Keycloak).

Environment Variable	Description	Default Value
`SECURITY_KEYCLOAKADMINENABLED`	Whether FlowX has Keycloak admin access and manages realms itself. Set to `false` if your environment does not grant FlowX admin access — the `SECURITY_MASTERREALM_*` variables below are then not required.	`true`
`SECURITY_MASTERREALM_ADMIN_CLIENTID`	Master-realm admin client.	`admin-cli`
`SECURITY_MASTERREALM_NAME`	Master realm name.	`master`
`SECURITY_MASTERREALM_ADMIN_USERNAME`	Master-realm admin username.	`-`
`SECURITY_MASTERREALM_ADMIN_PASSWORD`	Master-realm admin password. Store in a Secret.	`-`

The admin user supplied here must hold the Admin role on the master realm with permission to create realms — the migrations provision a new user realm and a service-accounts realm at first boot, and they also create clients, users, and service accounts in those realms.

When SECURITY_KEYCLOAKADMINENABLED=false, FlowX does not manage Keycloak realms and the SECURITY_MASTERREALM_* credentials are not needed. Use the Manual Keycloak Configuration path to create the realms and service accounts yourself. The same flag governs the data-sync master-realm credentials below.

Service-account client secrets for the service-accounts realm must also be supplied as Liquibase parameters on authorization-system. One per service, via SPRING_LIQUIBASE_PARAMETERS_SECRETS_SERVICE_ACCOUNTS_FLOWX_*_SA (13 secrets in total, matching the service-account clients listed above).

Missing SA secrets fail silently. If SECURITY_MASTERREALM_ADMIN_PASSWORD is missing, the service refuses to start. Easy to diagnose. If individual SPRING_LIQUIBASE_PARAMETERS_SECRETS_SERVICE_ACCOUNTS_FLOWX_*_SA values are missing, the realm-migration changeset logs an error but the service starts; the SA realm ends up half-populated, and service-to-service authentication breaks at runtime. Verify all 13 secrets are set before booting 5.9.x.

On `data-sync` (runtime authorization migration)

The runtime-authorization migration step in data-sync connects directly to Keycloak to refresh runtime user/group/role assignments. Configure the same master-realm admin credentials on data-sync:

Environment Variable	Description	Default Value
`FLOWX_OPENID_PROVIDER`	Identity provider type.	`keycloak`
`FLOWX_OPENID_SERVERURL`	Keycloak base URL — same as `SECURITY_OAUTH2_PUBLIC_SERVER_URL`.	`-`
`FLOWX_OPENID_USER`	Master-realm admin username — same as `SECURITY_MASTERREALM_ADMIN_USERNAME`.	`admin`
`FLOWX_OPENID_PASSWORD`	Master-realm admin password — same as `SECURITY_MASTERREALM_ADMIN_PASSWORD`.	`-`
`FLOWX_OPENID_CLIENTID`	Master-realm admin client — same as `SECURITY_MASTERREALM_ADMIN_CLIENTID`.	`admin-cli`

These reuse the master-realm admin you set on authorization-system. They are required for the runtime-authorization migration to complete; without them, data-sync cannot refresh runtime role assignments and post-migration login validation fails.

Configure SMTP in Keycloak

On 5.9.x, Keycloak is the system of record for password resets and user invitations. Configure an SMTP server on each Keycloak realm that will issue invitations. At minimum the user realm. Without SMTP, invitations and password-reset flows fail silently. See your Keycloak documentation for the realm-level SMTP settings (host, port, encryption, sender address, credentials). FlowX-issued invitation emails are templated by Keycloak.

On self-hosted deployments this SMTP configuration is yours to set directly in Keycloak — it is not provisioned for you. See Email (SMTP) configuration for the field-by-field steps.

What happens to existing tokens and sessions

Existing user sessions are invalidated by the realm transition. Users must sign in again after the upgrade.
Existing service-account tokens are invalidated. The new flowx-{service}-sa clients re-establish service-to-service authentication on first request.
Existing API tokens issued to integration partners must be re-issued from the new service-accounts realm.

Plan the upgrade window with a clean post-upgrade login + re-issue pass.

Verify the configuration

After services boot on 5.9.x, confirm:

The two Keycloak realms exist. User realm (named with your organization ID) + service-accounts realm (00000002-0002-4002-8002-000000000002).

Every service-account client listed above exists in the service-accounts realm and has client credentials configured.

All services started cleanly. Service logs show JWT validation rather than opaque-token introspection. Search for jwt-public-key in startup logs.

Test user sign-in completes end to end against the user realm.

Test password-reset email arrives (validates Keycloak SMTP).

Configuring an IAM solution

Full Keycloak realm, client, and mapper setup, including the Manual Keycloak Configuration recipe.

Access Management overview

How authentication and authorization fit together in 5.9.x.

Runtime authorization migration

Next step. The runtime authorization rewrite that depends on this auth foundation.

Organization & deployment configuration

ORGANIZATION_ID propagation and the new license service.

​What changed at the platform level

​Service-account client renames

​Remove legacy authentication env vars

​New required env vars

​On every service (19 of 19)

​On the 8 services that initiate service-to-service calls

​On authorization-system (master-realm administration)

​On data-sync (runtime authorization migration)

​Configure SMTP in Keycloak

​What happens to existing tokens and sessions

​Verify the configuration

​Related resources

Configuring an IAM solution

Access Management overview

Runtime authorization migration

Organization & deployment configuration

What changed at the platform level

Service-account client renames

Remove legacy authentication env vars

New required env vars

On every service (19 of 19)

On the 8 services that initiate service-to-service calls

On `authorization-system` (master-realm administration)

On `data-sync` (runtime authorization migration)

Configure SMTP in Keycloak

What happens to existing tokens and sessions

Verify the configuration

Related resources