> ## 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

| 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)                                                         |

<Info>
  **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.
</Info>

***

## What migrates automatically

The 5.9.x Liquibase migrations handle the bulk of the role + group transition for you:

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="End-user groups created in FlowX">
    End-user groups previously held in Keycloak are migrated into FlowX-managed records (org-level, named buckets of users). Confirm the migrated group list under **Organization Settings → Access Management → End-User Groups** after the upgrade and adjust as needed.
  </Step>
</Steps>

***

## What does not migrate (and must be redone per environment)

<Warning>
  **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.
</Warning>

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:

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Test as each role">
    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.
  </Step>
</Steps>

***

## 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 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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Delete the deprecated role 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.
  </Step>
</Steps>

<Tip>
  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.
</Tip>

***

## Post-upgrade checklist

<Check>
  End-user groups visible under **Organization Settings → Access Management → End-User Groups** match the groups you had in Keycloak.
</Check>

<Check>
  Every UI Flow's role allow-list reviewed and tightened from the default `User` assignment.
</Check>

<Check>
  For each project, the **Active Policy** build is the one you want sharing assigned against.
</Check>

<Check>
  Active policy role overrides from 5.1.x replaced with equivalent group overrides; deprecated role rows deleted.
</Check>

<Check>
  Sharing assignments rebuilt per environment. Confirm at least one end user can access each solution as expected.
</Check>

***

## Related resources

<CardGroup cols={2}>
  <Card title="Runtime authorization setup guide" icon="shield-halved" href="/5.9/setup-guides/access-management/runtime-authorization">
    Project-scoped roles, the Share modal, end-user groups, and IDP federation in day-to-day operation.
  </Card>

  <Card title="End-user access management" icon="user-group" href="/5.9/setup-guides/access-management/end-user-access-management">
    Org-level end-user, role, and group management.
  </Card>

  <Card title="Authentication & IAM migration" icon="shield-keyhole" href="./authentication-iam">
    Previous step. The Keycloak transition this rewrite depends on.
  </Card>

  <Card title="License and organization configuration" icon="building-shield" href="./organization-deployment">
    Next step. `ORGANIZATION_ID` Liquibase parameter, the new `license` service, and the env vars that replace the legacy Configure Environment Info UI.
  </Card>
</CardGroup>