Understanding Realms, Clients, and Roles in Keycloak

Introduction

Keycloak is a powerful open-source identity and access management platform. It allows developers to easily add authentication and authorization to their applications. One of the key concepts in Keycloak is Realms, Clients, and Roles. Understanding these elements is essential for effectively using Keycloak.

In this article, we'll explore these core concepts and how they work together to create a comprehensive identity management solution. We'll also look at practical examples to help you understand how to implement these concepts in your own projects.

Realms: Isolated Authentication Spaces

A Realm in Keycloak represents an isolated space where users, applications, roles, and groups are managed. Each Realm has its own configurations and data. This allows for the creation of multiple independent authentication and authorization zones on a single Keycloak server.

When you first install Keycloak, it creates a default "master" realm. This special realm is used to manage the Keycloak server itself and create other realms. For your applications, it's recommended to create separate realms rather than using the master realm.

Common Uses for Realms

Separation of development, testing, and production environments
Managing identity for multiple organizations within a single Keycloak instance
Creating isolated authentication zones for different applications or services
Implementing multi-tenancy in SaaS applications

Each realm operates independently with its own set of users, clients, roles, and groups. This isolation ensures that authentication and authorization policies can be tailored to specific needs without affecting other realms.

Clients: Applications and Services

Clients in Keycloak represent applications and services that can use Keycloak for user authentication and authorization. Clients can be web applications, mobile applications, services, and other types of applications. Clients can use various protocols, such as OpenID Connect and SAML, to interact with Keycloak.

When configuring a client, you need to specify several important parameters:

Client ID

A unique identifier for the client within the realm. This is used by the application when it requests authentication from Keycloak.

Client Protocol

The protocol used for authentication, typically OpenID Connect or SAML 2.0, depending on your application's requirements.

Access Type

Determines how the client authenticates with Keycloak. Options include "public" for client-side applications, "confidential" for server-side applications, and "bearer-only" for services.

Valid Redirect URIs

The URLs where Keycloak can redirect users after authentication. This is a security feature to prevent unauthorized redirects.

Clients can also have their own roles, which are specific to that client and can be assigned to users. This allows for fine-grained access control within each application.

Roles: Managing Access Control

Roles in Keycloak are used to manage access to resources. Roles can be assigned to users or groups of users. They allow controlling what actions users can perform in applications.

There are two types of roles in Keycloak:

Realm Roles

Global roles that are available throughout the realm. These roles can be used by any client within the realm and are useful for defining common access levels across multiple applications.

Client Roles

Roles that are specific to a particular client. These roles are only relevant within the context of that client and allow for more granular access control within a specific application.

Roles can be organized hierarchically using composite roles. A composite role is a role that contains other roles. When a user is assigned a composite role, they automatically receive all the contained roles as well. This simplifies role management in complex systems.

Example Usage: Corporate Portal

Let's consider an example of using Keycloak to manage access to a corporate portal. This example will demonstrate how realms, clients, and roles work together in a practical scenario.

Step 1: Start Keycloak

To start the service, you can use Docker:

docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:25.0.2 start-dev

This command starts Keycloak on port 8080 with the admin username and password both set to "admin". Access the admin console at http://localhost:8080 and log in with these credentials.

Step 2: Create a Realm

Create a realm called "CompanyPortal" to serve as an isolated space for managing users and access on our portal:

Click on the dropdown in the top-left corner (showing "Master")
Select "Create Realm"
Enter "CompanyPortal" as the name
Click "Create"

Step 3: Register Clients

In the left sidebar, click on "Clients"
Click "Create client"
For the web application:
- Client ID: WebApp
- Client Protocol: openid-connect
- Valid Redirect URIs: http://localhost:3000/* (or the actual URL of your web application)
Repeat the process for the mobile application with appropriate settings

Step 4: Set Up Roles

Create roles "Admin" and "User" for access control:

In the left sidebar, click on "Realm roles"
Click "Create role"
Enter "Admin" as the name and provide a description
Click "Save"
Repeat the process to create the "User" role

Step 5: Assign Roles to Users

After creating users, assign the appropriate roles to ensure correct access to various functions:

In the left sidebar, click on "Users"
Find and click on a user
Go to the "Role mapping" tab
Click "Assign role"
Select the appropriate role(s) and click "Assign"

With this setup, users can now authenticate to the corporate portal using Keycloak. The system will enforce access control based on the assigned roles, ensuring that users can only access the resources they are authorized to use.

Conclusion

Keycloak provides flexible and powerful identity and access management capabilities. Understanding Realms, Clients, and Roles is fundamental to effectively setting up and using Keycloak. These concepts allow for the creation of a secure and scalable authentication and authorization infrastructure for various types of applications and services.

By properly configuring realms, you can create isolated authentication spaces for different environments or organizations. Clients represent your applications and services, allowing them to integrate with Keycloak for authentication. Roles provide the foundation for access control, ensuring that users can only access the resources they are authorized to use.

For further study of Keycloak, it is recommended to review the official documentation and try setting up Keycloak for your applications, following examples and best practices.