Keycloak Basic Configuration for Authentication and Authorisation

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

Continuing from where I left, in this new article I’d like to talk about how to configure Keycloak so that you can later use it for managing authentication and authorisation for a web application as well as for a web service. I’ll show you how to create a new realm, define roles and add users.

Throughout this series, you’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.

Access Control, Authentication and Authorisation

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

Before going on, it is worth briefly recalling the definition of some fundamental security properties (from NIST glossary):

  • Access Control: “the process of granting or denying specific requests to: 1) obtain and use information and related information processing services; and 2) enter specific physical facilities (e.g., federal buildings, military establishments, border crossing entrances)”.
  • Authentication: “verifying the identity of a user, process, or device, often as a prerequisite to allowing access to resources in an information system”.
  • Authorisation: “access privileges granted to a user, program, or process or the act of granting those privileges”.

A typical error is considering authorisation and access control as synonyms when the second one is included in the first one. If you are interested in exploring this difference, you can read this article by ICANN.

Create a New Realm

If you followed my previous post, you’d be able to access the Keycloak Admin Console with your admin account by visiting the following URL: http://localhost:8180/auth/admin/. By default, you’ll be inside the Master realm.

But what is a realm? It’s just a domain in which you apply specific security policies. The Master realm is the parent of any realm you could create. For my purpose, I want to create a new realm, which will be a new security domain specifically for my web application or service.

On the top left of the Admin Console, click the little arrow next to Master. It’ll appear a drop-down menu where Keycloak shows all your realms and let you select any of them. Click Add realm.

Keycloak screen to add a new realm
Keycloak Admin Console

On the new screen just enter a name for the new realm (e.g. Demo) and confirm the operation by clicking the Create button.

Keycloak screen to create a new realm
Keycloak Add realm Page

That’s it. You have just created a new realm. For the moment you can keep all the default configurations.

Define Roles for Users

In the web application that I’m going to build in the next article, there will be resources accessible according to two different security policies. Here I want to define a role for each of the two security policies inside Keycloak: a User role with normal privileges and an Admin role with administrative privileges.

To create a new role select Roles from the menu on the left, then on the far right of the screen click Add role.

Keycloak screen for security roles
Keycloak Roles Page

Here you can insert a name for the new role and an optional description. When done, click Save.

Keycloak screen to add a new security role
Keycloak Add Role Page

I want an Admin to have both administrative and normal privileges. It’s possible to turn the Admin role into a composite role and automatically include the User role when an Admin role is assigned, so to grant it both kinds of privileges.

You can do that by going into the Roles area, selecting the Admin role and toggling the Composite Roles option. In the new section appearing below the general fields, select the User role from the Available Roles and add it to the Admin role by clicking Add selected.

Keycloak screen for configuring admin role
Keycloak Page for the Admin Role

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

When you build the web application, you’ll define access policies for each resource. Then Keycloak will help you with authorisation, checking if the currently logged user has the proper role needed to access a specific resource.

Add Users

After having defined a new realm and two roles, you can finally add your first users. I’m going to create an Admin account for Amy Farah Fowler and a User account for Sheldon Cooper.

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

Keycloak screen for Users
Keycloak Users Page

Fill in the form as you like (only the Username field is required). Then click Save.

Keycloak screen to add user
Keycloak Add user Page for Amy
Keycloak screen to add user
Keycloak Add user Page for Sheldon

To assign a role and a password to a user, go to the Users page and click on the user to whom you want to assign a role. If you can’t see any user, click View all users near the search box.

Go to the Credentials tab and insert a new password. For this series of tutorials, I don’t want to require the user to change the password on their first login, so I’ll toggle the Temporary option to Off. After that, click Reset password.

In a production environment, it would be a good idea enabling this option when you define a password on behalf of some user.

Keycloak screen to manage passwords and credentials for users
Credentials – Keycloak User Page

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

Keycloak screen for Role Mappings
Role Mappings – Keycloak User Page

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

Keycloak screen for default roles
Default Roles – Keycloak Roles Page

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

Conclusion

In this post, I explained some basic Keycloak configurations. You 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.

In the next article, I’m going to start coding my Spring Boot web application and secure it with Keycloak. I’ll further talk about the different authentication options and also introduce the Keycloak clients.

Keycloak Series

Leave a Reply

Your email address will not be published. Required fields are marked *