Setting Up Roles and Permissions in Keycloak Roles and permissions in Keycloak define what users and applications are allowed to do. Roles can be assigned to users, groups, or clients, and are embedded into access tokens to enforce authorization. This guide explains how to define and manage roles via the Admin Console, REST API, and CLI, with best practices and common issues. Creating Roles via Keycloak Admin Console This is the easiest way to create and manage roles visually. Access the Admin Console Log in to: http:///admin/ Choose the appropriate realm. Create Realm Roles Go to Roles > Add Role Enter:   Role Name : e.g., admin , viewer , editor Description : Optional but recommended   Click Save Create Client Roles Go to Clients > [client-name] > Roles > Create Role Fill in the Role Name and optional Description Save the role Assign Roles to Users Go to Users > [username] > Role Mappings In Available Roles , choose from:   Realm roles (top-left dropdown) Client roles (select client under “Client Roles”)   Click Add selected Creating Roles via Keycloak REST API Get Access Token curl -X POST "https:///realms/master/protocol/openid-connect/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "username=admin" \ -d "password=admin-password" \ -d "grant_type=password" \ -d "client_id=admin-cli" Save the access_token . Create Realm Role curl -X POST "https:///admin/realms//roles" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "name": "viewer", "description": "Read-only access" }' Create Client Role curl -X POST "https:///admin/realms//clients//roles" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "name": "api-user", "description": "API access for clients" }' To get the client ID: curl -H "Authorization: Bearer " \ "https:///admin/realms//clients" Creating Roles via Docker CLI  Access the Container docker exec -it keycloak bash Create Roles via CLI /opt/keycloak/bin/kcadm.sh config credentials \ --server http://localhost:8080 --realm master \ --user admin --password admin /opt/keycloak/bin/kcadm.sh create roles -r \ -s name=auditor -s description="Can view reports" To create client roles: /opt/keycloak/bin/kcadm.sh create clients//roles -r \ -s name=external-api -s description="Role for external apps" Required Permissions for Managing Roles To manage roles, users need: manage-realm role for realm roles manage-clients role for client-specific roles To assign via Admin Console: Users > [admin-user] > Role Mappings > Realm Roles > Add 'manage-realm' or 'manage-clients' Best Practices for Roles and Permissions Use Fine-Grained Role Names: Use names like invoice_viewer , invoice_editor , or admin_dashboard for clarity. Use Groups to Assign Roles in Bulk: Create groups such as managers , sales , or auditors , then assign roles to groups. Map Roles to Access Tokens: Use Client > Mappers to include role names in the access_token or id_token . Prefer Client Roles for Application Permissions: Client roles are scoped to individual apps and help separate responsibilities. Use Composite Roles Sparingly: Composite roles combine multiple roles into one but may add complexity if overused. Common Issues and Troubleshooting Issue Possible Cause Solution Role doesn’t appear in token Missing protocol mapper Add a role mapper in Client > Mappers User not authorized despite role assignment Role not assigned to the correct client/realm Verify if the role is client-scoped or realm-wide 403 Forbidden despite valid login Role not embedded in access token Ensure token includes required roles via protocol mappers REST API: 409 Conflict when creating role Role with same name already exists Use a unique name or update existing role Cannot assign role to user User lacks manage-users privilege Ensure admin has role assignment rights