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¶
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.
- Open Manage → Realm roles, then click Create role and name the realm role.
- For a client role, open the OIDC client instead and add a role scoped to that application.
- 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.
- 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.
- 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.
[
{ "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.