> ## 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 & IAM migration
> Keycloak two-realm architecture, service-account renames, opaque-token removal, and the new env vars required on 5.9.x.
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 |
| 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 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` | application-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](/5.9/setup-guides/access-management/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 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 |
### 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 Variable | Affected services | Replaced by |
| ------------------------ | ----------------- | ---------------------------------------------------------------- |
| `FLOWX_CLIENT_NAME` | admin | Registered organization code (`DEFAULT_ORGANIZATION_NAME`) |
| `FLOWX_ENVIRONMENT_NAME` | admin | Captured 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 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_ORGANIZATION_ID`. See [Organization & deployment configuration](./organization-deployment#organization_id--where-it-is-actually-required) 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_SERVER_URL` | 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_CLIENT_ID` | 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.
***
## 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).
***
## Related resources
Full Keycloak realm, client, and mapper setup, including the Manual Keycloak Configuration recipe.
How authentication and authorization fit together in 5.9.x.
Next step. The runtime authorization rewrite that depends on this auth foundation.
`ORGANIZATION_ID` propagation and the new `license` service.