> ## 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.
# Runtime authorization migration
> How runtime roles, end-user groups, and solution sharing change between FlowX.AI 5.1.x and 5.9.x, and what you need to redo per environment after the upgrade.
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](/5.9/setup-guides/access-management/runtime-authorization).
***
## Mental model: what changed
**Keycloak realm roles no longer drive runtime access.** In 5.1.x, a user's Keycloak realm roles were consulted at request time to authorize runtime access. In 5.9.x they are not — runtime authorization is decided entirely by FlowX's own model, through project-scoped role assignments made in the **Solutions → Share** modal. If your 5.1.x rollout granted end users runtime access through Keycloak roles, that access stops at the upgrade until it is reassigned in FlowX.
Keycloak still authenticates users and can still supply **group membership** — not roles — to the FlowX model through the [`attributes.runtimeGroups` claim](/5.9/setup-guides/access-management/configuring-an-iam-solution#runtime-groups-attribute-mapper). Only membership carries over; role-based authorization does not.
| 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:
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.
5.9.x gates access per UI Flow with an explicit role allow-list. On upgrade, each UI Flow's allow-list is populated from the runtime roles carried by its latest build (typically the default `User` role), so existing end users generally keep access. **Review each UI Flow** after the upgrade to confirm the resolved roles and tighten them as part of the post-upgrade pass.
End-user groups previously held in Keycloak are migrated into FlowX-managed records (org-level, named buckets of users). The migration also creates a group named **Users Group**, populated with the users who held the `FLOWX_ROLE` realm role in 5.1.x. On 5.9.0 and 5.9.1 this group was created as `User`; upgrading to 5.9.2 or later renames it to `Users Group`. Confirm the migrated group list under **Organization Settings → Access Management → End-User Groups** after the upgrade and adjust as needed.
**Migrated end users appear only after their first sign-in.** Users carried over from your 5.1.x Keycloak realm are not listed under **End-Users** until each one signs in to 5.9.x for the first time. On that first login the user is placed in the built-in **All end-users** group, which on its own grants access to no solution — they gain runtime access only once assigned a role on a solution (directly or through a runtime group). Expect the End-Users list to fill in gradually as users log in, not all at once at upgrade.
**Keeping group membership in Keycloak or an external IDP.** The migration moves the group *definitions* into FlowX, but you choose where *membership* is administered going forward. If you assign users to end-user groups directly in FlowX (Designer / Organization Settings), no Keycloak token claim is involved. If you keep membership in **native Keycloak groups or a federated IDP** — the model most 5.1.x rollouts are built on — runtime authorization reads each user's groups from the `attributes.runtimeGroups` access-token claim and matches those values against FlowX end-user group names by **exact string comparison**. No `attributes.runtimeGroups` mapper ships in the realm template; add one per organization so existing Keycloak/IDP group members keep runtime access without being reassigned in FlowX one by one. If a mapper or IDP claim references the migration-created group by its pre-5.9.2 name `User`, update the emitted value to `Users Group` when upgrading to 5.9.2 — the old name no longer matches any group. See [Runtime groups attribute mapper](/5.9/setup-guides/access-management/configuring-an-iam-solution#runtime-groups-attribute-mapper) for the setup steps.
***
## What does not migrate (and must be redone per environment)
**Sharing assignments do not export between environments.** This is intentional. When you promote a project build from one environment to another (dev → uat → prod), the Solutions → Share modal assignments are **not** carried over. Re-configure sharing per environment as part of every deployment.
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:
Every UI Flow carried over from 5.1.x lists the runtime roles resolved from its latest build (typically the default `User` role). This preserves access for existing end users but is often broader than most production deployments want.
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.
Create a test end-user assigned to a single role, sign in, and verify the UI Flow allow-list and component-level visibility behave as expected.
***
## 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.
The bypass is implemented through a `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](/5.9/setup-guides/access-management/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](/5.9/docs/platform-deep-dive/user-roles-management/business-filters) | Keycloak |
| Federation with external IDPs | Keycloak |
| Runtime role catalog | FlowX |
| End-user group definitions | FlowX |
| End-user group **membership** | FlowX, or Keycloak / a federated IDP via the [`attributes.runtimeGroups` mapper](/5.9/setup-guides/access-management/configuring-an-iam-solution#runtime-groups-attribute-mapper) |
| 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.
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.
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.
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.
Once the equivalent group overrides are in place, delete each deprecated role override row from the table. They have no runtime effect, but removing them keeps the overrides table clean and avoids confusion during audits.
Repeat this conversion per environment. Like sharing assignments, active policy overrides are not exported with the build and must be reconfigured on each environment the project is promoted to.
***
## 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
Project-scoped roles, the Share modal, end-user groups, and IDP federation in day-to-day operation.
Org-level end-user, role, and group management.
Previous step. The Keycloak transition this rewrite depends on.
Next step. `ORGANIZATION_ID` Liquibase parameter, the new `license` service, and the env vars that replace the legacy Configure Environment Info UI.
## Related topics
- [Runtime authorization](/5.9/setup-guides/access-management/runtime-authorization.md)
- [Authentication & IAM migration](/5.9/migrating-from-5.1-lts/authentication-iam.md)
- [Prerequisites & upgrade path](/5.9/migrating-from-5.1-lts/prerequisites.md)
- [Configuring an IAM solution (Keycloak)](/5.9/setup-guides/access-management/configuring-an-iam-solution.md)
- [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview.md)