Keycloak → Ranger Role Sync
This page covers how Keycloak realm role membership is mirrored into Apache Ranger, enabling Ranger policies to reference roles rather than individual users.
Why This Exists
Ranger enforces data access policies against the username passed by Trino at query time. Policies that grant access to individual usernames do not scale — adding a new user means updating every policy they need.
Ranger supports role-based policies. By syncing Keycloak realm roles into Ranger roles, a single policy can grant access to a role (e.g. kc_realm_data_analyst) and any Keycloak user assigned that role inherits access automatically.
How It Works
A CronJob deployed in the ranger namespace runs every 15 minutes using client_credentials against the Keycloak admin API.
Role Naming Convention
Every Keycloak realm role is mirrored into Ranger using the pattern:
kc_realm_{role_name}
For example, a realm role named data_analyst becomes kc_realm_data_analyst in Ranger. This applies to any realm role — both platform-defined defaults and custom roles added to the realm.
The kc_realm_ prefix is fixed — it identifies all Ranger roles managed by this sync and prevents the sync from touching manually-created Ranger roles.
The following roles are skipped and never synced to Ranger:
- Workspace-scoped roles — names containing
/(e.g.w-abc123/data_analyst) - Internal Keycloak roles —
offline_access,uma_authorization,default-roles-*
OAuth Client & Keycloak Permissions
The CronJob authenticates as a dedicated Keycloak service account ({workspace_id}-ranger-role-sync) provisioned as part of the Ranger bundle. The service account requires two realm-management client roles to call the Keycloak admin API:
| Client | Role | Purpose |
|---|---|---|
realm-management | view-realm | List realm roles |
realm-management | view-users | List users in a role |
These are assigned automatically when the ranger_role_sync_oauth_client bundle resource is provisioned via service_account_client_roles.
Deployment
The sync is deployed as part of the Ranger bundle (aws/ranger) in the role-sync resource group:
| Resource | Type | Purpose |
|---|---|---|
ranger_role_sync_oauth_client | oauth-client | Service account with realm-management roles |
ranger_role_sync_secret | k8s-manifest | K8s Secret holding all OIDC + Ranger env vars |
ranger_role_sync | k8s-manifest | CronJob running workspace-python-utility |
The cron schedule defaults to */15 * * * * and can be overridden via the ranger_role_sync_cron_schedule bundle input.
Troubleshooting
403 on Keycloak admin API
The service account is missing view-realm or view-users from realm-management. Re-provision the ranger_role_sync_oauth_client resource or manually assign the roles in Keycloak → Clients → {workspace_id}-ranger-role-sync → Service account roles.
404 on role users endpoint
The role name contains a / and is not being skipped. This happens if workspace-scoped realm roles exist in the realm. The sync script filters these out — verify you are running workspace-python-utility:0.0.4 or later.
Users not appearing in Ranger policies
- Check the CronJob ran:
kubectl get jobs -n ranger -l app.kubernetes.io/name=ranger-role-sync-job - Check logs:
kubectl logs -n ranger -l app.kubernetes.io/name=ranger-role-sync - Confirm the user is assigned the realm role in Keycloak: Keycloak UI → Users →
{user}→ Role mappings → Realm roles. - Confirm the
kc_realm_{role}role exists in Ranger: Ranger UI → Settings → Roles.
Go Deeper
- SQL Auth — Superset, Trino & Ranger — how Ranger policies are evaluated at query time
- Token Exchange and Data Access — the broader identity flow
- Data Access Management — managing Ranger policies in the UI