What is a Client Role in Keycloak?

In Keycloak, clients represent applications or services (like APIs, admin dashboards, or web apps) that want to use Keycloak for authentication and authorization.

Each client can have its own set of roles, called Client Roles.
These roles define permissions or capabilities specific to that application.

Difference Between Realm Roles and Client Roles

Think of realm roles as company-wide positions, and client roles as department-specific roles.

How Client Roles Work

Each client can define its own roles in Keycloak → Clients → [Your Client] → Roles.
When a user logs in, Keycloak issues a token (like an ID token or access token) that includes those client roles, which the client app can then use for authorization checks.

For example:

• realm: mycompany
• client: dashboard-app
• client role: admin, editor, viewer

When ashwani@example.com logs in:

• If he’s assigned admin for dashboard-app, the JWT token will contain: "resource_access": { "dashboard-app": { "roles": ["admin"] } }

Common Client Roles and Their Purpose

Below is a list of commonly used client roles (you may find them in different contexts depending on the application’s purpose):

1. admin

• Purpose: Full control over the client application.
• Usage Example: Can manage users, settings, configurations.
• Used In: Admin panels, CMS dashboards, API management portals.

2. manager

• Purpose: Manage sections or subsets of resources.
• Usage Example: Can approve/reject user requests, manage teams but not system-wide settings.
• Used In: Organization-level apps or project managers in SaaS dashboards.

3. user

• Purpose: Basic role for authenticated users.
• Usage Example: Default role given upon signup or login.
• Used In: End-user portals, customer dashboards, employee login systems.

4. viewer / read-only

• Purpose: Can view data but cannot modify anything.
• Usage Example: Monitoring dashboards, analytics viewers.
• Used In: Business intelligence tools, reports section.

5. editor

• Purpose: Can modify or create resources but cannot manage system settings.
• Usage Example: Content creators, blog managers, or task updaters.
• Used In: CMS or internal apps for content editing.

6. auditor

• Purpose: View logs, reports, and audit trails for compliance.
• Usage Example: Security or compliance officers.
• Used In: Financial systems, SRE dashboards, logging tools.

7. service-account

• Purpose: Used by other services (not human users) to access APIs with specific privileges.
• Usage Example: API-to-API communication.
• Used In: Microservice architectures, automation scripts.

8. api-client

• Purpose: Restricts access to API endpoints.
• Usage Example: Users or systems that consume REST/GraphQL APIs.
• Used In: Public APIs, mobile backend APIs.

9. developer

• Purpose: Can deploy, test, and debug client-specific features.
• Usage Example: Developers managing staging or dev environments.
• Used In: Dev portals, staging tools, developer sandboxes.

10. super-admin

• Purpose: Has access to all clients within the realm.
• Usage Example: Platform-level administrators.
• Used In: SaaS multi-tenant admin dashboards, platform management UIs.

11. guest

• Purpose: Temporary or limited access user.
• Usage Example: Trial users, temporary link-based access.
• Used In: Freemium applications, shared links.

12. support

• Purpose: Helpdesk or support role with limited administrative rights.
• Usage Example: Can view and fix user issues but not change configurations.
• Used In: Customer support consoles.

13. billing-admin

• Purpose: Access to billing and subscription management features.
• Usage Example: Can view or modify payment methods and invoices.
• Used In: SaaS apps with subscription tiers.

Assigning Client Roles

Client roles can be assigned:

1. Directly to a user
2. To a group (users inherit the roles)
3. Through a composite realm role
4. Or even to another client’s service account

You can view this under:

Users → [username] → Role Mappings → Client Roles → [select client]

Example Token Structure with Client Roles

{
  "realm_access": {
    "roles": ["offline_access", "uma_authorization"]
  },
  "resource_access": {
    "account": {
      "roles": ["manage-account", "view-profile"]
    },
    "dashboard-app": {
      "roles": ["admin", "editor"]
    },
    "api-gateway": {
      "roles": ["api-client"]
    }
  }
}

Best Practices for Client Roles

Summary