Hands‑On Keycloak: Install, Explore Realms & Users with Docker

In the previous post we briefly introduced Keycloak and received good feedback, so this article dives deeper to give a hands‑on experience and gradually break down its design ideas and concepts.

Overall Approach

Since Keycloak provides a Spring Security adapter, we first clarify Keycloak's core concepts before exploring its integration with Spring Security.

Installing Keycloak

The Keycloak version used in this article is 14.0.0 .

To save time, we install Keycloak using Docker:

docker run -d -p 8011:8080 --name keycloak-server -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin jboss/keycloak

After the container starts, open http://localhost:8011/auth/admin and log in with username admin and password admin. You can switch the UI to Chinese as shown in the image below.

Explore the menus to get a feel for the overall layout.

Realm

If you are familiar with the Shiro security framework, the concept of a realm will be familiar: it is a space that manages users and applications, providing logical isolation between different tenants.

By default, Keycloak provides a Master realm, which does not manage specific applications or users but is used to manage the lifecycle of other realms.

Log in to the Master realm and create a custom realm named felord.cn.

User

A User represents an account that can log in to applications. Users belong to a realm; we will create a user in the custom realm felord.cn following these steps:

Navigate to Management → Users and click Add User .

Enter a unique username.

Enable ON for Email Verified and save.

In the Credentials tab, set a temporary password (or disable the temporary switch for a permanent password) and click Set Password .

Log out the admin user and log in to http://localhost:8011/auth/realms/felord.cn/account with the newly created user felord in the felord.cn realm.

Did you notice the pattern of the login URL?

At this point you have manually created a realm and a user. In the next article we will automate this process with code and protect a Spring Boot application using Keycloak.

Keycloak Core Concepts

The following concepts are essential when using Keycloak:

authentication

The process of identifying and verifying a user – proving “you are who you say you are”.

authorization

The process of granting a user access rights – defining “what you can do”.

credentials

Proof of identity such as passwords, OTPs, certificates, or fingerprints.

roles

RBAC roles that indicate a user's identity type.

user role mapping

Mapping between users and their assigned roles; a user can have multiple roles and a role can belong to multiple users.

composite roles

Roles that inherit permissions from other roles; if role B is a child of role A, possessing role A also grants the permissions of role B.

groups

Collections of users; assigning roles to a group automatically grants those roles to all members.

clients

Applications or services that request authentication from Keycloak; any entity registered on Keycloak that needs protection is a client.

client adapters

Keycloak adapters for various platforms (e.g., Java, Python) that enable applications to integrate with Keycloak, such as the Spring Boot adapter.

identity provider

External services that authenticate users (IDP). Keycloak itself acts as an IDP, similar to Spring Security’s AuthenticationProvider interface.

More concepts will be added later; digest what you have learned first.

Summary

This article provides a practical introduction to Keycloak 14.0.0, sets up a Docker‑based development environment, and summarizes key concepts like realms, users, authentication, authorization, roles, groups, clients, and identity providers. In the next post we will protect a Spring Boot application with Keycloak.