RBAC & permissions

Authorization on the DataFlow AI Platform is governed by a hierarchical role-based access-control (RBAC) model. The catch: there are three different role vocabularies — Keycloak realm roles, the backend DataFlowRole hierarchy, and the frontend personas — that must be reconciled by hard-coded mapping tables. This page documents all three, the full permission matrices, how enforcement works, and the known gaps.

Three role vocabularies

A single human user is described by three different role names depending on which layer you are looking at. Understanding the mapping between them is essential to reasoning about access.

1. Keycloak realm roles

The dataflow realm ships six realm roles: org_admin, workspace_admin, developer, analyst, operator, and viewer. org_admin is a composite role that includes the other five.

2. Backend DataFlowRole hierarchy

RBACService.DataFlowRole defines five ordered roles, each with a numeric level:

ADMIN(100) > ENGINEER(75) > ANALYST(50) > STEWARD(40) > VIEWER(25)

A role grants any permission whose requiredRole.level is less than or equal to the user's role level (RBACService.hasPermission).

3. Frontend personas

The SPA models four personas (PersonaId): admin, engineer, analyst, and steward. Each persona maps to a fixed set of permissions and a list of allowed route prefixes.

Mapping tables

Keycloak groups → realm roles

The realm export maps four corporate-style groups onto realm roles:

KeycloakJwtConverter and RBACService additionally know about PLK-BI-Stewards and PLK-BI-Viewers, but those groups are not present in the shipped realm export.

Seeded users

All four seeded users have empty credentials and requiredActions: [UPDATE_PASSWORD].

Any raw role → DataFlowRole

The gateway maps every raw role string it sees — realm roles, client roles, group names, and group paths — onto a single DataFlowRole (RBACService.mapSingleRole / KeycloakJwtConverter). The highest mapped role wins; the default is VIEWER.

KeycloakJwtConverter.extractAuthorities converts the resolved role into Spring ROLE_* authorities. If a JWT has no mappable roles, the authority set is empty and the request is rejected by @PreAuthorize — a deliberate anti-privilege-escalation choice. The org_admin / developer / operator mappings were added late to fix users who were otherwise silently downgraded to ANALYST or VIEWER.

Backend permission matrix

RBACService defines a catalogue of 30 permissions, each tagged with a requiredRole. Because the model is hierarchical, a role receives a permission when its level is ≥ the permission's required-role level.

Permissions by domain

Roles × permissions (hierarchical)

✔ = granted. Levels: ADMIN 100, ENGINEER 75, ANALYST 50, STEWARD 40, VIEWER 25.

Workspace-aware checks

RBACService also exposes workspace-scoped checks layered on top of the permission checks:

• canAccessWorkspace — ADMIN sees all workspaces; the default workspace is open to everyone; any other workspace requires membership.
• canModifyPipeline, canDeletePipeline, canRunPipeline — each evaluates the relevant permission and the workspace check.

Frontend permission matrix

The frontend permission catalogue (frontend/src/types/permissions.ts) defines 28 permissions as domain:action strings spanning pipeline, quality, governance, lineage, code, admin, system, and catalog domains. (The file's header comment says "26"; the actual list is 28.) Permissions are assigned per persona via personaPermissions, and the model is described as backed server-side by the metadata-service PolicyEngine.kt.

Persona × permissions

✔ = granted. The admin persona holds all 28 permissions.

Note how the frontend steward persona holds rich governance:*, quality:*, lineage:edit, and catalog:* permissions — exactly the authority the backend hierarchy denies a STEWARD (level 40). This divergence is one of the known gaps.

How enforcement works

Authorization is enforced in two layers: the gateway checks token validity and role presence; each service applies fine-grained method-level and workspace/ownership checks.

 Request ──▶ API Gateway ──▶ Downstream service ──▶ @PreAuthorize ──▶ workspace check
              │                  │                       │
              │ token valid?     │ JWT re-validated      │ method-level
              │ role present?    │ X-User-* → context    │ role/permission
              ▼                  ▼                       ▼
        coarse HTTP rule    SecurityContext        fine-grained grant

Gateway-level rules

When dev-permit-reads=false, the gateway's reactive SecurityConfig applies coarse method-based rules to /api/v1/**:

When dev-permit-reads=true, all GETs plus the copilot / ai / catalog-ask / search POSTs become permitAll.

Service-level @PreAuthorize

Downstream services run @EnableMethodSecurity(prePostEnabled = true), so controllers carry @PreAuthorize annotations. Because KeycloakJwtConverter produces real ROLE_* authorities, hasRole / hasAnyRole evaluate genuine Keycloak roles. A representative sample of observed guards:

Frontend route guards

Frontend RBAC is UX only — the SPA is a public client and real enforcement is always server-side. Still, the frontend prevents users from navigating to pages they cannot use:

• ProtectedRoute shows a spinner while isLoading, redirects to /login if !isAuthenticated, then calls canAccess(effectivePersona, pathname) and renders AccessDenied on failure. effectivePersona is the persona store in dev mode, otherwise user.persona.

• Route-prefix RBAC — data/permissions.ts defines personaRoutes; canAccess matches an allowed prefix exactly or as prefix + '/'. This map is locked by permissions-rbac.test.ts (65 assertions).
• PermissionGate is a component-level gate built on the usePermission / usePermissions / useAnyPermission hooks, supporting single or multiple permissions with requireAll and an optional fallback.
• useAuth().hasRole(role) checks realmRoles; useAuth().hasPermission(perm) checks the persona-derived permissions array.

Allowed route prefixes per persona

Known risks & gaps

The research flagged several authorization-correctness issues worth tracking.

Mismatched @PreAuthorize roles

Several controllers guard endpoints with role names that a real Keycloak token can never carry. KeycloakJwtConverter only ever emits the five canonical authorities ROLE_ADMIN, ROLE_ENGINEER, ROLE_ANALYST, ROLE_STEWARD, and ROLE_VIEWER. Guards such as:

• hasRole('DATA_STEWARD') and hasRole('DATA_ENGINEER') — QuarantineController
• hasRole('PLATFORM_OPS') — SearchController reindex
• hasAnyRole('governance-admin','data-steward') — TagController

...would never match a genuine user. Those endpoints are effectively inaccessible to real users — they only become reachable in dev-permit-reads mode, where the anonymous user is granted a broad role set that happens to include ROLE_DATA_STEWARD / ROLE_DATA_ENGINEER. This is a real authorization-correctness defect.

STEWARD hierarchy inversion

As noted above, STEWARD (level 40) ranks below ANALYST (level 50) in the backend hierarchy, so a STEWARD inherits only VIEWER-level permissions from RBACService — while the frontend persona model grants the steward broad governance, quality, lineage, and catalog rights. The two models disagree on how powerful a steward is, and STEWARD authority on the backend depends entirely on explicit @PreAuthorize lists rather than the hierarchy.

The dev-permit-reads escape hatch

dataflow.gateway.dev-permit-reads (default false) is a powerful switch. When true it permits all GETs unauthenticated and grants the downstream anonymous user a wide role set (ROLE_ADMIN, ROLE_DPO, ROLE_COMPLIANCE_OFFICER, ROLE_AUDITOR, ROLE_STEWARD, ROLE_OPS, ROLE_ENGINEER, ROLE_USER, ROLE_DATA_ENGINEER, ROLE_DATA_STEWARD). It must be false in production, and no environment guard was found that enforces this.

Other observations

• Role-vocabulary fragmentation — three role systems reconciled only by hard-coded mapping tables in RBACService, KeycloakJwtConverter, and keycloak.ts. The org_admin / developer mappings were a late bug fix.
• Doc drift — the admin guide describes a MANAGER role and a dataflow-ui client that exist in neither the code nor the realm export.

Summary

For the authentication side of the picture — how an identity is established before any of these checks run — see Authentication & SSO.