Overview

Migration guide for upgrading from FlowX.AI v5.4.0 to v5.5.0

FlowX.AI v5.5.0 introduces a critical breaking change to the default authentication mechanism across 14 of 19 platform services. Action is required before upgrading.

What’s changing

FlowX.AI v5.5.0 changes the default authentication mechanism from opaque-token introspection (oauth2) to JWT-based authentication (jwt-public-key). This affects service-to-service communication, service account configuration in Keycloak, and multiple environment variables across the platform.

Additionally, a new microservice — Organization Manager — has been introduced for organization and tenant management.

Who is affected

All deployments are affected by the authentication mechanism change. The default SECURITY_TYPE value has changed from oauth2 to jwt-public-key across 14 of 19 platform services.

If you explicitly set SECURITY_TYPE=oauth2 or rely on opaque-token introspection, you must update your configuration before upgrading.

Migration process

1. Back up your configuration

   Create backups of your current Helm values, environment configurations, and Keycloak settings before making any changes.

2. Update Keycloak service accounts

   Update your Keycloak service account client IDs to follow the new flowx-{service-name}-sa naming pattern. See Update Keycloak service accounts for the full mapping.

3. Update environment variables

   Remove deprecated variables and update changed defaults. See Update environment variables for a per-service breakdown.

4. Deploy Organization Manager

   If applicable, deploy the new Organization Manager microservice. See the Organization Manager Setup Guide for infrastructure requirements.

5. Deploy and verify

   Deploy the updated configuration and verify that all services start correctly and inter-service communication works as expected.

---

Authentication mechanism change

Overview

The default value of SECURITY_TYPE has changed from oauth2 to jwt-public-key across 14 of 19 platform services. Opaque-token introspection has been removed entirely.

A new security.oauth2.sa-realm property has been introduced to separate the service account realm from the main authentication realm. This property is used by the token URI for inter-service communication across 11 services.

Removed environment variables

The following environment variables have been removed and are no longer supported:

Environment Variable	Description	Previously Used By
SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_INTROSPECTION_URI	Opaque-token introspection endpoint	14 services
SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_ID	Client ID for opaque-token introspection	14 services
SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_SECRET	Client secret for opaque-token introspection	14 services
SECURITY_OAUTH2_REALM	OAuth2 realm name	13 services
SECURITY_OAUTH2_CLIENT_CLIENT_ID	OAuth2 client ID	13 services
SECURITY_OAUTH2_CLIENT_CLIENT_SECRET	OAuth2 client secret	13 services
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_ID	Service account admin client ID	8 services
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET	Service account admin client secret	8 services

Changed default values

Environment Variable	Old Default	New Default	Affected Services
SECURITY_TYPE	oauth2	jwt-public-key	14/19 services
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_ID	${security.oauth2.service-account.admin.client-id}	flowx-${spring.application.name}-sa	8 services
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET	${security.oauth2.service-account.admin.client-secret}	-	8 services
SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI	Uses ${security.oauth2.realm}	Uses ${security.oauth2.sa-realm}	8 services

---

Update Keycloak service accounts

Service account client IDs now follow the flowx-{service-name}-sa pattern. Update your Keycloak configuration to match:

Service	New Client ID
Admin	flowx-admin-sa
Process Engine	flowx-process-engine-sa
Integration Designer	flowx-integration-designer-sa
Authorization System	flowx-authorization-system-sa
Runtime Manager	flowx-runtime-manager-sa
Scheduler Core	flowx-scheduler-core-sa
Task Management Plugin	flowx-task-management-plugin-sa
Organization Manager	flowx-organization-manager-sa
License	flowx-license-sa
Email Gateway	flowx-email-gateway-sa

Ensure you update both the Keycloak client IDs and the corresponding environment variables in your deployment configuration. Mismatches will cause service startup failures.

---

New microservice: Organization Manager

FlowX.AI 5.5.0 introduces the Organization Manager microservice for organization and tenant management, user registration, and platform component health monitoring.

Infrastructure requirements:

• PostgreSQL
• Redis
• Kafka
• Keycloak/IAM
• SpiceDB

For full setup instructions, see the Organization Manager Setup Guide.

---

Backward compatibility

No backward compatibility for the authentication mechanism change. The opaque-token introspection mechanism has been removed entirely. You must update your configuration before or immediately after upgrading to v5.5.0.

Rollback support

If you need to rollback from v5.5.0 to v5.4.x:

1. Revert your SECURITY_TYPE and environment variables to the previous configuration
2. Restore the previous Keycloak service account client IDs
3. Re-add the removed opaque-token variables if they were in use
4. Downgrade all platform service containers to their v5.4.x versions

Ensure you have database backups before any upgrade. Schema changes introduced by Organization Manager are not automatically reversed on rollback.

---

Additional resources

Update Environment Variables

Per-service environment variable changes for v5.5.0

Deployment Guidelines v5.5.0

Component versions and deployment instructions

IAM Configuration

Keycloak setup and service account configuration

Release Notes v5.5.0

Full release notes for v5.5.0

Support

For technical support, deployment assistance, or migration questions, contact your FlowX.AI support representative.