Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 37 ยท Realms, Users and Roles

Realm Roles, Client Roles and Composite Roles in Keycloak

Learn Keycloak role-based access control: realm roles, client roles, composite and default roles, role mapping, how roles appear in tokens and how an API checks them.

Roles are the simplest and most widely used form of authorization in Keycloak. A role is a label such as admin or invoice-approver that you attach to users; your applications look for the label in the token and decide what to allow. Used well, roles keep authorization rules out of the identity data and in the application where they belong.

Realm roles and client roles

  • Realm roles are global to the realm. Use them for broad concepts shared by many applications: employee, customer, platform-admin.
  • Client roles belong to one client and are namespaced by it. Use them for application-specific permissions: invoices: approve, invoices: read. Two clients can both have a role named admin without collision.

Create a realm role in Realm roles > Create role. Create a client role in Clients > (client) > Roles > Create role. Roles have a name and a description; give them stable, lower-case names, because applications will hard-code them.

A practical convention: the realm roles describe who the person is; client roles describe what they may do in one application.

Assigning roles

A role can reach a user in four ways:

  1. Directly: Users > (user) > Role mapping > Assign role. The dialog lets you filter by realm roles or client roles.
  2. Through a group: roles mapped to a group apply to all members (see Groups and User Attributes).
  3. Through a composite role: a role that includes other roles.
  4. By default: the realm's default roles.

Prefer groups for people-based assignment and direct mapping only for exceptions. Role mapping through groups scales: one change updates every member.

Composite roles

A composite role is a role whose members are other roles. Open a role, switch on Associated roles, and add realm or client roles to it. Assigning the composite grants every associated role, recursively.

flowchart TD
  admin --> manager
  admin --> auditor
  manager --> support
  support --> read["invoices: read"]
  manager --> approve["invoices: approve"]

admin includes manager and auditor; manager includes support and the approve role.

Use composites to build job functions out of fine-grained permission roles. Avoid very deep or circular chains, which become hard to reason about; Keycloak prevents cycles on save.

Default roles

Every realm has a composite role named default-roles-{realm}, automatically given to new users. Out of the box it includes offline_access, uma_authorization and the account client's view-profile and manage-account. You can add roles to it (for example customer), and existing users are not changed retroactively except when they inherit the composite. Remove roles you do not want everyone to have; the less a default role grants, the safer your realm.

Roles in tokens

The roles client scope contains mappers that write roles into the access token:

JSON
{
  "realm_access": { "roles": ["customer", "offline_access", "uma_authorization"] },
  "resource_access": {
    "invoice-app": { "roles": ["approve"] },
    "account": { "roles": ["manage-account", "view-profile"] }
  }
}
  • realm_access.roles holds realm roles.
  • resource_access.{client}.roles holds client roles, for each client the token has any role for.

By default only roles relevant to the token's audience appear, and the optional Full scope allowed switch (client > Client scopes > client-dedicated scope > Scope tab) controls whether all of the user's roles go into the token. Turning it off and selecting specific roles is the least-privilege configuration: a token for the invoice-app carries only what that app needs. The scoping behavior is detailed in Scopes and Protocol Mappers.

Checking roles in an API

The API reads the verified token and tests the roles. With a framework adapter the check is one line; in plain terms:

JavaScript
function hasRole(claims, role, client) {
  const roles = client
    ? claims.resource_access?.[client]?.roles
    : claims.realm_access?.roles;
  return Array.isArray(roles) && roles.includes(role);
}

Always verify the token's signature, issuer and audience before trusting any claim (see Tokens and JWT Claims). Roles in an unverified token are only a suggestion.

Resolve roles like Keycloak (stand-in)

This runnable stand-in resolves composite roles and builds the two role claims, including the least-privilege "scope" filter. It is a teaching model.

Node.js Stand-in: composites and role claims

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The second call shows least privilege: the token for another API does not mention invoice-app roles at all.

An authorization guard (stand-in)

Finally, a middleware-style check that uses those claims and returns the right status code: 401 without a valid identity, 403 without the role.

Node.js Stand-in: role guard with 401 and 403

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Naming and design tips

  • Name roles after capabilities or job functions, not people: invoice-approver, not johns-role.
  • Keep a short list in each client; if a client has dozens of roles you probably need Authorization Services (chapter 6).
  • Document each role in its description field; auditors read it.
  • Do not encode data into role names (region-eu-admin, region-us-admin, ...): use attributes or groups for dimensions.
  • Remember that roles in a token are a snapshot; removing a role takes effect when the token expires or is refreshed, so keep access tokens short.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where do client roles appear in an access token?

    Realm roles go into realm_access; client roles are grouped by client ID under resource_access.
  2. 2. What does a composite role do?

    Associated roles are included recursively, which lets you build job functions from permissions.
  3. 3. Why turn off Full scope allowed for a client?

    With full scope off, role scope mappings restrict which roles can enter tokens issued to the client.
  4. 4. A request arrives with a valid token but without the required role. Which status should the API return?

    The identity is known (valid token) but lacks permission, so 403.

Summary

  • Realm roles are realm-wide; client roles belong to one client and are namespaced by it.
  • Assign roles through groups where possible; use direct mapping for exceptions.
  • Composite roles bundle other roles; default-roles-{realm} is given to every new user.
  • Tokens carry realm_access and resource_access; turn off full scope for least privilege.
  • APIs must verify the token first, then check roles and return 401 or 403 correctly.

Next: Groups and User Attributes