In 5.1.x, runtime roles were assigned to end users at the organization level and granted access across every project that listed that role. 5.9.x ships a rewritten runtime authorization model: role assignments are project-version-scoped, end-user groups move out of Keycloak into FlowX-managed records, and sharing is configured per environment via the Solutions → Share modal. This page covers the migration concepts. For day-to-day operation of the new model, see the Runtime authorization setup guide.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.
Mental model: what changed
| Concern | 5.1.x | 5.9.x |
|---|---|---|
| Where runtime roles are assigned | Directly to users at organization level | To users in the context of a project, via the Solutions → Share modal |
| Cross-project effect | One role grants access on every project that lists it | Role grants access only on the solutions it has been explicitly shared on |
| End-user groups | Managed in Keycloak | Managed in FlowX, assigned to roles on each solution |
| Authentication of end users | Keycloak | Keycloak (unchanged) |
| Authorization decisions | Keycloak-issued roles consulted at request time | FlowX-managed runtime authorization service tuned for the volume of runtime permission checks |
| Designer-time permissions | SpiceDB | SpiceDB (unchanged — separate engine) |
Why two engines? SpiceDB stays as the design-time permission engine for Designer access. Runtime authorization is a separate custom service because the volume of runtime permission evaluations made SpiceDB latency unacceptable. Both coexist and don’t interact at runtime.
What migrates automatically
The 5.9.x Liquibase migrations handle the bulk of the role + group transition for you:Existing role-on-user assignments preserved
If your 5.1.x users have runtime roles assigned directly, those assignments continue to work after the upgrade. New solutions and new role assignments use the project-scoped model going forward.
Default `User` role on every UI Flow
5.9.x gates access per UI Flow with an explicit role allow-list. UI Flows carried over from 5.1.x automatically receive the project-level
User role on upgrade so existing end users do not lose access. Review and tighten the role list per UI Flow as part of the post-upgrade pass.What does not migrate (and must be redone per environment)
Plan your post-upgrade pass, and every future promotion, around:- Pick the Active Policy for each project. The Share modal only lists roles available in the build set as Active Policy.
- Re-create end-user group assignments per environment.
- Re-issue invitations through Keycloak SMTP for new end users that were created in FlowX as part of the migration.
UI Flow permissions
5.9.x adds an allow-list of roles on every UI Flow. After the upgrade:Audit the default assignment
Every UI Flow carried over from 5.1.x now lists the project-level
User role. This preserves access for existing end users but is broader than most production deployments want.Tighten per UI Flow
Open each UI Flow in the Designer and reduce the role list to the minimum that needs interactive access. Components inside UI Flows can also be hidden or disabled per role. Use this for finer-grained restrictions inside flows that several roles can still launch.
Designer-user bypass
A user with Designer access to a project can run that project at runtime without being assigned a runtime role on it.- Auto-grants view, execute, and self-assign on every swimlane in the project.
- Lets a project’s designers test their own work without being filed into the runtime role catalog.
- Designer users cannot test scenarios “as another runtime role.” To verify role-specific behavior, create a test end-user, assign the role through the Share modal, and sign in as that user.
designerUser Keycloak user attribute (boolean) auto-managed at organization provisioning. If your environment uses a federated IDP for designer accounts, you may need to add this attribute via an IDP mapper. See Configuring an IAM solution → Designer user attribute.
What stays in Keycloak vs FlowX
| Concern | System of record |
|---|---|
| Authentication, password policy, MFA | Keycloak |
| User attributes used by business filters | Keycloak |
| Federation with external IDPs | Keycloak |
| Runtime role catalog | FlowX |
| End-user groups | FlowX |
| Project-scoped role assignment (sharing) | FlowX |
Active policy: convert role overrides to group overrides
5.9.0 removes the Role override type from active policy. Existing role overrides survive the upgrade visually — they appear in the overrides table with a DEPRECATED marker — but they are excluded from runtime resolution. If your 5.1.x setup relied on role overrides to serve a specific build or branch to a subset of end users, redo that targeting with group overrides before promoting the upgrade to production.List the role overrides you had in 5.1.x
For each project, open Runtime Settings → Active Policy and note the role, policy type (Latest on Branch or Build), branch/build, and priority of every role override you relied on.
Identify the matching runtime group
In 5.9.x, end-user access is configured via runtime groups in the Solutions → Share modal. For each former role override, identify the runtime group whose members should receive the same build or branch. Where you previously targeted a role used by multiple groups, decide whether one group override is enough or whether you need a per-group entry.
Create the group overrides
In Runtime Settings → Active Policy, click Add, choose Group, pick the runtime group, set the policy and branch/build, and assign a unique priority. Priority is mandatory for group overrides and decides which one wins when a user belongs to several matching groups. Username overrides always take precedence over group overrides.
Post-upgrade checklist
End-user groups visible under Organization Settings → Access Management → End-User Groups match the groups you had in Keycloak.
Every UI Flow’s role allow-list reviewed and tightened from the default
User assignment.For each project, the Active Policy build is the one you want sharing assigned against.
Active policy role overrides from 5.1.x replaced with equivalent group overrides; deprecated role rows deleted.
Sharing assignments rebuilt per environment. Confirm at least one end user can access each solution as expected.
Related resources
Runtime authorization setup guide
Project-scoped roles, the Share modal, end-user groups, and IDP federation in day-to-day operation.
End-user access management
Org-level end-user, role, and group management.
Authentication & IAM migration
Previous step. The Keycloak transition this rewrite depends on.
License and organization configuration
Next step.
ORGANIZATION_ID Liquibase parameter, the new license service, and the env vars that replace the legacy Configure Environment Info UI.