Admin roles (RBAC)¶

Scope exactly what each administrator can see and do with fine-grained, role-based access control.

What it is¶

Not every administrator should hold the keys to everything. HelixIAM's admin RBAC grants admin permissions to the realm's roles — so who can administer what is driven by the same roles you already assign to users. A help-desk operator role might reset credentials but never touch signing keys; a realm-owner role manages its own realm but not the platform.

Grants are drawn from a fixed catalogue of discrete permissions, each gating a class of administrative action (managing users, editing realm settings, managing clients, viewing events, and so on). The realm-admin permission is the super-grant. Assign the smallest set that lets an admin do their job — least privilege by construction.

Every realm is seeded with sensible defaults: the admin role holds realm-admin; the auditor role holds the read-only view-* permissions; the default user role holds none.

In the console¶

Open Manage → Users & access → Admin roles.
Pick a realm role and tick the admin permissions it should grant.
Save — the grants take effect on the next request from anyone holding that role.

Admins see only the screens and actions their role's permissions allow; everything else is hidden or denied.

How to design roles¶

Start from the permission catalogue and group by job function (operator, realm owner, auditor, security).
Separate read from write where the catalogue allows it — the seeded auditor role (view-only) is the canonical example. The split isn't total: view-identity-providers only covers trusted lists, so identity-provider configs and secrets still need manage-identity-providers even to read.
Keep highly privileged permissions (realm-admin, manage-realm, manage-events) on a small number of tightly held roles.
Pair RBAC with the audit log so every administrative write is attributable to a named admin.

Over the API¶

Admin RBAC lives under /admin/realms/{realm}/admin-roles. It edits the permission grants on existing realm roles — there is no separate admin-role object to create or delete. The examples below assume you have set $HELIX_URL / $REALM and logged in — see Authenticating to the API.

List roles and their grants¶

Each entry is a realm role plus the admin permissions it currently holds:

curl -s -b cookies.txt "$HELIX_URL/admin/realms/$REALM/admin-roles"

[
  { "realmId": "acme", "roleId": "8d3a79d3-40e4-4497-8543-234685e689a8", "roleName": "admin",   "permissions": ["realm-admin"] },
  { "realmId": "acme", "roleId": "9ec2e116-e56b-458d-b11d-1efbfd1c492a", "roleName": "user",    "permissions": [] },
  { "realmId": "acme", "roleId": "6c898aa8-98dc-4597-87be-9352dd5f21da", "roleName": "auditor", "permissions": ["view-clients","view-events","view-identity-providers","view-users"] }
]

Read the permission catalogue¶

The catalogue is fixed; permissions values in a grant must be keys from this list:

curl -s -b cookies.txt "$HELIX_URL/admin/realms/$REALM/admin-roles/permissions"

[
  { "key": "realm-admin",               "label": "Full realm administration" },
  { "key": "view-users",                "label": "View users" },
  { "key": "manage-users",              "label": "Manage users" },
  { "key": "view-clients",              "label": "View clients / applications" },
  { "key": "manage-clients",            "label": "Manage clients / applications" },
  { "key": "manage-roles",              "label": "Manage realm & client roles" },
  { "key": "view-identity-providers",   "label": "View identity providers & federation" },
  { "key": "manage-identity-providers", "label": "Manage identity providers & federation" },
  { "key": "manage-authorization",      "label": "Manage authorization (flows, scopes, claims, authz services)" },
  { "key": "manage-organizations",      "label": "Manage organizations & groups" },
  { "key": "manage-realm",              "label": "Manage realm settings, notifications & provisioning" },
  { "key": "view-events",               "label": "View events & sessions" },
  { "key": "manage-events",             "label": "Manage events config & revoke sessions" },
  { "key": "reveal-bsn",                "label": "Reveal citizen service numbers (BSN)" },
  { "key": "manage-credential-issuance", "label": "Manage credential issuance (templates, offers, issued credentials)" }
]

The BSN is masked unless you hold reveal-bsn. User lists and details show a citizen service number as *****1234; revealing the full number (POST /admin/realms/{realm}/users/{userId}/bsn/reveal) needs reveal-bsn (or realm-admin) and is audited. Which applications receive the BSN is a realm-admin decision — see DigiD.

Credential issuance. manage-credential-issuance covers credential issuance templates, offers and issued credentials (revoke, suspend). Issuer key writes, the issuer settings and a template's BSN grant still need realm-admin. Writing a verified-claims policy or verification API settings also needs realm-admin.

Realm signing keys need realm-admin. Whoever can import or activate a realm signing key can issue any token of the realm, including tokens for an admin service account. So every write under /admin/realms/{realm}/keys (import, CSR, certificate upload, activate, rotate, retire), and changing the realm's signing settings (PUT /admin/realms/{realm}/settings/signing), requires realm-admin; manage-realm can still read both. The console hides the key actions from admins without realm-admin.

No admin can grant permissions they do not hold. Assigning or removing a role — to a user, a group, a group's members, a service account, through realm import or SCIM — needs the role's admin permissions to be your own. The admin role (and any role granting realm-admin) needs realm-admin. Changing a role's admin permissions needs realm-admin. A role with admin permissions cannot be the realm's default role, and the default role cannot be given admin permissions; a realm that already has such a default role is reported at start-up and new users no longer get it.

You cannot act on an admin more privileged than you. Impersonating a user, resetting their password or credentials, changing their profile, e-mail, username, required actions or status, erasing or deleting them — and revealing, setting or rotating a client's secret, changing its authentication, keys, redirect URIs or grant types, or deleting it — needs the target's admin permissions (a client's: its service account's) to be your own. Revoking a user's sessions stays allowed. Revealing a client secret needs manage-clients. Logins through an external identity provider are never linked automatically (by e-mail) to an administrator: the administrator links the identity from the account console while signed in. Binding a workload-identity issuer or an agent to a client counts as acting on that client. On the built-in sign-in clients (helix-console, helix-cli), every change except the name, description and "always display in console" — including their roles and mappers — needs realm-admin. When permissions are compared, manage-users, manage-clients, manage-identity-providers and manage-events include their view- counterparts.

What administrators sign in through is protected. Changing or deleting an identity provider that administrators are linked to needs their admin permissions, and so does changing a trusted list that their wallet providers use. An administrator signs in through a federated link only when it is trusted. Trusted links are those that existed before 1.0.0-rc.12 (reported at start-up), the sign-in that created their account, a link they made from the account console (Connected accounts → Link, after signing in again), wallet linking, or a link a realm admin confirmed. A link made by matching a verified e-mail address never signs in an administrator. Under Users → (user) → Linked identities, a realm admin can confirm a link or revoke trust in it. The following need realm-admin:

creating a client named helix-console or helix-cli;
changing the flow, subject claim or enabled flag of their Application, or deleting it;
the realm's browser flow and the flows bound to the sign-in clients;
messaging providers and message templates;
the MFA policy, magic links and the subject claim;
the realm settings other than the display name, the legacy branding fields and self-registration.

Registering a push device for a user needs that user's admin permissions. Deleting a role or a group, or moving a group under another parent, needs the admin permissions it grants. The same permission is a route requirement too: for example, manage-clients can list clients. helix-cli is created in every realm. On every start, a helix-cli that allows more than the built-in client is corrected: non-loopback redirect URIs, extra grant types, a secret, or a confidential setting. A correction is logged and audited as SIGN_IN_CLIENT_RECONCILED; narrower choices are kept.

Unknown admin routes fail closed. An /admin route the permission catalogue does not name requires realm-admin. Admin paths are matched on the decoded path, and a percent-encoded character in the realm id or the route name (for example k%65ys instead of keys) is refused with 400.

view-identity-providers unlocks read-only access to trusted lists (GET /admin/realms/{realm}/trusted-lists) — so an auditor can see which EU trusted lists a realm trusts and their health, without being able to change anything. It does not unlock identity-provider configuration or secrets: reading or writing an identity provider, its verifier keys, or its wallet connection still requires manage-identity-providers, same as before.

Set a role's grants¶

PUT /admin-roles/{roleId} replaces the permission set for that role. Use the roleId from the list above:

# Refresh CSRF after any GET, then PUT (see the auth guide for the helper)
curl -s -b cookies.txt -c cookies.txt "$HELIX_URL/admin/realms/$REALM/admin-roles" >/dev/null
CSRF=$(awk '($6=="__Host-XSRF-TOKEN"||$6=="XSRF-TOKEN")&&$7~/^r1\./{t=$7} END{print t}' cookies.txt)

# Grant the auditor role read access to users, clients, events and federation (replaces its current grants)
curl -s -b cookies.txt -X PUT \
  -H "Content-Type: application/json" \
  -H "X-XSRF-TOKEN: $CSRF" \
  -d '{"permissions":["view-users","view-clients","view-events","view-identity-providers"]}' \
  "$HELIX_URL/admin/realms/$REALM/admin-roles/6c898aa8-98dc-4597-87be-9352dd5f21da"

Full endpoint set¶

Method & path (under `/admin/realms/{realm}`)	Purpose
`GET /admin-roles`	List realm roles with their admin-permission grants
`GET /admin-roles/permissions`	Read the fixed permission catalogue
`PUT /admin-roles/{roleId}`	Replace the admin permissions granted to a role

Realm roles themselves are created and deleted under /roles — see Roles.