Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

Concern5.1.x5.9.x
Token validationOpaque-token introspection against KeycloakJWT public-key validation (SECURITY_TYPE: jwt-public-key)
Service-account client namingPer-service ad-hoc namesStandardized flowx-{service-name}-sa pattern
Realm architectureSingle Keycloak realmTwo realms — user realm + dedicated service-accounts realm
Service-accounts realm UUIDn/a00000002-0002-4002-8002-000000000002
flowx-platform-authorize clientUsed for legacy token introspectionRemoved — no longer needed
SMTPOptionalRequired 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 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 IDUsed by
flowx-admin-saadmin
flowx-process-engine-saprocess-engine
flowx-integration-designer-saintegration-designer
flowx-authorization-system-saauthorization-system
flowx-runtime-manager-saruntime-manager
flowx-scheduler-core-sascheduler-core
flowx-task-management-plugin-satask-management-plugin
flowx-organization-manager-saorganization-manager
flowx-email-gateway-saemail-gateway
flowx-license-salicense
flowx-webhook-gateway-sawebhook-gateway
flowx-file-gateway-safile-gateway
flowx-anonymous-saapplication-manager, authorization-system, cms-core, document-plugin, events-gateway, integration-designer, process-engine — 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. See Configuring an IAM solution for the complete realm, client, and mapper setup.

​
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 VariableAffected services
SPRING_SECURITY_OAUTH2_RESOURCESERVER_OPAQUETOKEN_INTROSPECTIONURI14 services
SPRING_SECURITY_OAUTH2_RESOURCESERVER_OPAQUETOKEN_CLIENTID14 services
SPRING_SECURITY_OAUTH2_RESOURCESERVER_OPAQUETOKEN_CLIENTSECRET14 services
SECURITY_OAUTH2_REALM14 services
SECURITY_OAUTH2_CLIENT_CLIENTID14 services
SECURITY_OAUTH2_CLIENT_CLIENTSECRET14 services
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENTID8 services
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENTSECRET8 services

​
Deprecated env vars (still consumed for backward compatibility)

The following env vars are deprecated on 5.9.x. Their values are now populated by organization registration. Existing deployments can leave them set during the upgrade window, but plan to remove them once organization registration is complete.
Environment VariableAffected servicesReplaced by
FLOWX_CLIENT_NAMEadminRegistered organization code (DEFAULT_ORGANIZATION_NAME)
FLOWX_ENVIRONMENT_NAMEadminCaptured during organization registration; no env var equivalent
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 VariableDescriptionDefault Value
SECURITY_TYPEToken validation mechanism. Replaces opaque-token introspection.jwt-public-key
SECURITY_OAUTH2_SAREALMRealm UUID for service-to-service authentication.00000002-0002-4002-8002-000000000002
FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURLURL 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_ORGANIZATION_ID. 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 VariableNew Default
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_IDflowx-${spring.application.name}-sa
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET- (Keycloak-issued)
SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URINow 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 VariableDescriptionDefault Value
SECURITY_KEYCLOAKADMINENABLEDWhether 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_CLIENTIDMaster-realm admin client.admin-cli
SECURITY_MASTERREALM_NAMEMaster realm name.master
SECURITY_MASTERREALM_ADMIN_USERNAMEMaster-realm admin username.-
SECURITY_MASTERREALM_ADMIN_PASSWORDMaster-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 VariableDescriptionDefault Value
FLOWX_OPENID_PROVIDERIdentity provider type.keycloak
FLOWX_OPENID_SERVER_URLKeycloak base URL — same as SECURITY_OAUTH2_PUBLIC_SERVER_URL.-
FLOWX_OPENID_USERMaster-realm admin username — same as SECURITY_MASTERREALM_ADMIN_USERNAME.admin
FLOWX_OPENID_PASSWORDMaster-realm admin password — same as SECURITY_MASTERREALM_ADMIN_PASSWORD.-
FLOWX_OPENID_CLIENT_IDMaster-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.

​
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 + 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.
Last modified on June 2, 2026