In the previous article, we got to know Keycloak, an open source project for identity and access management developed by the RedHat Community. We went through how to install it, boot it and how to access the Keycloak Admin Console for the first time.

Continuing from where we left, in this new article I'd like to talk about how to configure Keycloak so that we can later use it for managing authentication and authorization for web applications and services. We'll learn how to create a new realm, define roles and add users.

Throughout this series, we're going to see more features and details about Keycloak, but I suggest you check the helpful and detailed official documentation for any doubt or curiosity.

1. Access Control, Authentication and Authorization

Managing authentication and authorization is an essential task in every well-designed web application or service. Keycloak makes it very easy and practical, letting us focus on the application business logic rather than on the implementation of security features.

Before going on, I think it is worth recalling and agreeing on the definition of some fundamental security terms. Rather than dwell on the topic here, I have written a dedicated article about access control and its main properties: identification, authentication and authorization. If you're interested in the topic, I suggest you read it before moving to the next section.

2. Create a New Realm

At the end of the previous article, we got to access the Keycloak Admin Console with our admin user by visiting: http://localhost:8180/auth/admin/. After logging in, we are inside the Master realm.

What is a realm? It's a domain in which we apply specific security policies. The Master realm is the parent of any realm we could create. We want to create a new realm, which will be a new security domain specifically for our web applications or services.

Throughout this series of articles, we're going to build and secure applications and services for a Public Library. That will be our realm, where we're going to define and enforce our security policies.

On the top left of the Admin Console, let's click the little arrow next to Master. It'll appear a drop-down menu where Keycloak shows all our realms and allow us to select any of them. Let's click Add realm.

Keycloak screen to add a new realm
Master realm - Keycloak Admin Console

On the new screen, we need to enter a name for the new realm (public-library) and confirm the operation by clicking the Create button.

Keycloak screen to create a new realm
Add realm - Keycloak Admin Console

That's it. We have created a new realm. For the moment, we can keep all the default configurations.

3. Define Roles for Users

In the web application that we're going to build in the next article, there will be resources accessible according to two different security policies. We want to define a role for each of the two security policies inside Keycloak: a Member role for the members of the library and a Librarian role for the administrative staff.

To create a new role, we need to select Roles from the menu on the left, then on the far right of the screen click Add role. These will be realm-level roles. We could also create roles for a specific client application.

Keycloak screen for security roles
Roles - Keycloak Admin Console

Now we can insert a name for the new role and an optional description. When done, let's click Save.

Keycloak screen to add a new user role
Add role - Keycloak Admin Console

We want a Librarian to have both administrative and normal privileges. It's possible to turn the Librarian role into a composite role and automatically include the Member role when a Librarian role is assigned, so to grant it both kinds of privileges.

We can do that by going into the Roles area, selecting the Librarian role and toggling the Composite Roles option. In the new section appearing below the general fields, let's choose the Member role from the Available Roles and add it to the Librarian role by clicking Add selected.

Keycloak screen for configuring composite role
Librarian role - Keycloak Admin Console

In this way, a user with a Librarian security role will have both administrative and normal privileges.

When building the web application, we're going to define access policies for each resource. Then Keycloak will help us with authorization, checking if the currently logged user has the proper role needed to access a specific resource.

4. Add Users

After having defined a new realm and two roles, we can finally add our first users. We're going to create a Librarian account for Irma and a Member account for Sheldon.

To create a new user, we need to go to the Users page and click Add user on the far right of the screen.

Keycloak screen for Users
Users - Keycloak Admin Console

Let's fill the form in as we like (only the Username field is required). Then we can click Save.

Keycloak screen to add user
Add user Irma - Keycloak Admin Console
Keycloak screen to add user
Add user Sheldon - Keycloak Admin Console

To assign a role and a password to a user, we need to go to the Users page and click on the user to whom we want to assign a role. If no user is shown, then we need to click View all users near the search box.

Let's go to the Credentials tab and insert a new password. For this series of tutorials, we don't want to require the user to change the password on their first login, so let's toggle the Temporary option to Off. After that, we need to click Reset password.

In a production environment, it's always a good idea enabling this option when we define a password on behalf of some user.

Keycloak screen to manage passwords and credentials for users
Manage user credentials - Keycloak Admin Console

Finally, let's go to the Role Mappings tab, select one of the Available Roles and click Add selected.

Keycloak screen for Role Mappings
User Role Mappings - Keycloak Admin Console

We can also set some role as default so that each new user will automatically have it. To set Member as default role, for example, we can go to Roles > Default Roles and select a new default role from the Available Roles list just like we did in the previous step.

Keycloak screen for default roles
Default Roles - Keycloak Admin Console

Now each new user will have a Member role by default.

5. User Account Service

All users have access to the built-in user account service, where they can manage their own account.

The user account service for the Public Library realm we previously created can be found at http://localhost:8180/auth/realms/public-library/account/. We need to make sure to sign out of the Admin Console first.

In the login form, let's insert the username and password of one of the users we created in the previous step.

The form to fill in to log into the Keycloak user service
Login - Keycloak User Service

This service allows the user to choose a new password, enable the multi-factor authentication, review the session logs and check to which applications they have access.

The page to manage a user account in Keycloak
Manage Account - Keycloak User Service


In this post, we went through some basic Keycloak configurations. We learned how to create a new realm, how to create roles and define the default ones, how to add new users and assign them a password and a role.

Then we quickly looked at the Keycloak User Service, which each user can use to manage their account.

In the next article, we're going to talk about the different authentication options, the SSO protocols and also introduce the Keycloak client applications.

Last update: 16/05/2020

Keycloak Series

Keycloak with Spring Series