Keycloak for beginners: The installation

This is my very first serious article I write on a blog. So please don’t hold me back on the quality of my writing. 😉 😊 It’s been about four years since I entered the world of computer science and today I’m a computer engineer. And while I was browsing the internet looking for documentation or tools to do the tasks or assignments, I came across several very interesting tools, and among them there is keycloak. Keycloak is after Intellij and all the other jetbrains IDEs the tool I prefer in the IT world. So what is keycloak?

Presentation of keycloak

Keycloak is an open source identity server developed and maintained by Red Hat. What does it mean? Well, that keycloak is a software that allows you to centralize pretty much every aspect of identity management, including provisioning, authorization, authentication, access policy enforcement, sessions, Single Sing-On (SSO), strengthened authentication, logout, account management and recovery, and de-provisioning. All these aspects of identity management may seem obscure, but don’t worry, it’s very easy to understand and maybe I’ll do an article one day to provide more details on these concepts, but let’s move on. The real strength of keycloak, besides being open source, is that in order to provide a solution to identity management problems, it is based on protocols and standards defined as best practices in the IT world. These protocols are notably OAuth 2.0, OpenID Connect and SAML. So, since keycloak implements these different protocols, as long as your application is a client in the sense of OpenID Connect or SAML, you can easily integrate it with keycloak, and what made me fall in love 😍 with keycloak is that, keycloak has many adapters that can allow you to easily accomplish this task.

keycloak setup

To install keycloak, you need a computer, it might seem obvious, but I want to make it clear 😂 😂 😂. No but seriously here are the pre-requisites that you need to be able to use keycloak. You must have java on your computer. Any implementation of OpenJDK will do as long as its version is greater than or equal to eight. And that is all there is to it! Yes, seriously, that’s really all.

And I would say that you are all absolutely right. Indeed keycloak has to store user information somewhere,but since keycloak is based on Wildfly (an application server for javaEE apps developed by Red Hat), keycloak comes by default with a H2 relational database management system, in which it will store all the information necessary for its operation. However H2 is usually a database used in dev, or in test, it is not really a RDBMS that you would want to use in production, but don’t worry, since keycloak uses hibernate (a very popular java ORM), you can integrate keycloak with any RDBMS.

By clicking on the link above, you can download keycloak as a compressed version in zip or tar format. Once you have downloaded the zip decompress it. When you enter the keycloak directory you should see a tree structure that looks like the one in the image below.

keycloak file tree structure

Starting up keycloak

For those of you who are used to using wildfly should be familiar with this file tree and I’m sure you should know how to run keycloak on the port you want. But for our lay friends, to start keycloak, you need to go to the \bin directory and open a terminal. If you don’t know how to open a command prompt in a particular directory, try to find out on the Internet.

The command to launch keycloak is standalone.bat or ./standalone.sh depending on whether you are on windows or linux/mac respectively.

Normally once you run this command keycloak should start on port 8080, and the administration interface on port 9990, but it just so happens (and this is my case) that one of the many ports necessary for the proper functioning of keycloak is already used by another process. In this case, we have two solutions, either we stop all the processes that prevent us from starting keycloak, or we shift all the keycloak execution ports by an integer n. So if for example the integer chosen is n=10 keycloak starts on port 8080+10=8090 and the administration interface on port 9990+10=10000. And to do this you have to add the option -Djboss.socket.bindin.port-offset=n, where n represents the integer in question. I happen to have a preference for n=100. So to start keycloak I often execute the command standalone.bat -Djboss.socket.binding.port-offset=100 or ./standalone.sh -Djboss.socket.binding.port-offset=100 depending on whether I’m on windows or linux/mac respectively.

launching keycloak from the windows cmd

Once the keycloak startup is finished go to the url http://localhost:8180 you should see the keycloak homepage similar to the one shown in the following figure.

I guess you can see on this page a form with username, password and confirm password fields. In order to log in on keycloak you must have an account on keycloak, and this form allows you to create an account in super administrator time, so please fill this form with a username, I usually choose my own name, and in the next two fields you enter your password that will be asked every time you want to log in on keycloak. Once you have entered the data, click on the create button, and if everything went well you should see a page similar to the one below.

By clicking on the Administration Console link (framed in red on the image above) you should be redirected to the keycloak login page shown in the figure below.

Fill in these fields according to the information you provided when creating the super administrator. And if all goes well you should be redirected to the keycloak administration console similar to the image shown in the following figure.

Here you have installed keycloak and you are now ready to use it. ✌️ ✌️ ✌️ 🎊 🎈 🎈

For the next week I will present a summary of most of the features offered by keycloak. Be well until then. 🙏 🙏

Since almost a year I fell in love with spring security, which led me to learn about OAuth 2.0, SAML, OpenID Connect and Keycloak. I'm looking for a remote job.