Skip to content

Roles

Roles are named permissions you assign to users and groups to drive authorization decisions in your applications.

What it is

HelixIAM supports two kinds of roles:

  • Realm roles — defined at the realm level and meaningful across the whole realm.
  • Client roles — defined on a specific OIDC client and scoped to that application.

Roles can be assigned directly to users or to groups. Users gain a role either by direct assignment or by being a member of a group that holds it (see Groups). Effective roles surface in issued tokens according to the client's scopes & claims configuration.

Reserved names

Role names starting with FACTOR_ (any case) are reserved for Spring Security's sign-in factors (FACTOR_PASSWORD marks every password login). The admin API and realm import refuse them for realm, client, service-account and agent roles (400), and an existing role with that prefix grants nothing and never appears in a token. Names starting with admin_ are reserved too.

Tip

Use realm roles for broad, cross-application capabilities (e.g. admin, support) and client roles for application-specific permissions (e.g. an app's editor or viewer). Assign roles to groups rather than individuals to keep access manageable.

Watch: create a role and assign it

29 seconds, no sound. Create a realm role, choose the admin permissions it grants, then assign it to a user. Recorded on the current release.

In the console

Realm roles live under Manage → Realm roles; client roles are managed from their owning OIDC client. Each realm is bootstrapped with system admin, user, and auditor roles.

  1. Open Manage → Realm roles, then click Create role and name the realm role.
  2. For a client role, open the OIDC client instead and add a role scoped to that application.
  3. Assign a role to a user from the user's Role mappings tab, or to a group from the group's Role mappings list so every member inherits it.
  4. Click a role to open its Permissions modal. It shows the admin permissions the role grants, and you can change them there. The role's row menu also has Set as default role and Delete role.
  5. The Roles screen does not list who holds a role. To see assignments, open a user's Role mappings tab or a group's Role mappings list.

Warning

Removing a role that applications check for authorization can immediately revoke access for every user and group that held it. Check the Role mappings of your users and groups before deleting a role. System roles cannot be deleted.

Over the API

Realm roles live under /admin/realms/{realm}/roles. The examples below assume you have set $HELIX_URL / $REALM and logged in — see Authenticating to the API.

List roles

Each realm ships with three system roles (system: true); defaultRole marks the role auto-granted to new users.

curl -s -b cookies.txt "$HELIX_URL/admin/realms/$REALM/roles"
[
  { "realmId": "acme", "roleId": "8d3a79d3-40e4-4497-8543-234685e689a8", "name": "admin",   "system": true,  "defaultRole": false },
  { "realmId": "acme", "roleId": "9ec2e116-e56b-458d-b11d-1efbfd1c492a", "name": "user",    "system": true,  "defaultRole": true  },
  { "realmId": "acme", "roleId": "6c898aa8-98dc-4597-87be-9352dd5f21da", "name": "auditor", "system": true,  "defaultRole": false }
]

Create a realm role

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

curl -s -b cookies.txt \
  -H "Content-Type: application/json" \
  -H "X-XSRF-TOKEN: $CSRF" \
  -d '{"name":"billing-admin","description":"Manage billing"}' \
  "$HELIX_URL/admin/realms/$REALM/roles"
{
  "realmId": "acme",
  "roleId": "14a78f34-...",
  "name": "billing-admin",
  "system": false,
  "defaultRole": false
}

Delete a role

Use the returned roleId:

# Delete — returns 204 No Content (system roles cannot be deleted)
curl -s -b cookies.txt -X DELETE -H "X-XSRF-TOKEN: $CSRF" \
  "$HELIX_URL/admin/realms/$REALM/roles/14a78f34-..."

Full endpoint set

Method & path (under /admin/realms/{realm}) Purpose
GET /roles · POST /roles List / create realm roles
DELETE /roles/{roleId} Delete a realm role
PUT /roles/{roleId}/default Set the realm's default role
GET · POST /users/{userId}/roles · DELETE .../roles/{roleId} User role mappings
GET /groups/{groupId}/roles · PUT · DELETE .../roles/{roleId} Group role mappings

Client roles are managed under the owning client. See the API reference.

See also