Keycloak Tutorial

Keycloak is an open source Identity and Access Management tool that makes it simple and quick to add user sign-up, sign-in, and access control to your web and mobile applications.

Keycloak supports standard protocols such as OAuth 2.0, OpenID Connect, and SAML. Keycloak provides single sign on solution, meaning a user can authenticate to multiple systems with a single login ID and password.

Keycloak also provides social login features which means Keycloak can delegate authentication to third party identity providers like Google, Facebook.

Keycloak is designed to make the life of software developers easy as it provides out of the box security features which are configurable and simple to integrate with applications and services. Keycloak provides customizable interfaces for registration, login, account management, and administration.

This tutorial will guide you to setup and use Keycloak so that you can assess it before deploying it in a production environment. It explains how to set up a standalone Keycloak server, create accounts and realms for managing users and apps:

Downloading the Keycloak Server

To install and run the Keycloak server, follow the steps below:

Download keycloak [zip|tar.gz] Server (Distribution powered by Quarkus) at Keycloak downloads. This download file contains scripts and binaries needed to run the Keycloak server.
Move the zip file to a directory of your choice.
Unzip the zip file:

In Windows


    unzip keycloak-21.0.1.zip

In Linux / Ubuntu / Unix


    $ sudo tar -xvzf keycloak-21.0.1.tar.gz

Configuring Keycloak Server

Keycloak can load configuration from four different sources. These sources have a descending ordinal as shown by order below:

command-line parameters - Configuration set via command-line parameters take precedence over environment variables.
environment variables - Configuration options set by using environment variables take precedence over options set by using a specific user config file.
user-created .confg file - Configuration options from a specific user config file have precedence over those in conf/keycloak.conf file.
keycloak.conf - Configuration file located in bin directory.

When the same configuration key appears in different configuration sources, the applied value is taken from the configuration source with the highest ordinal.

Here is an example format for configuring the db-url-host parameter in different sources:

Source	Format	Example
Command-line parameter CLI	The configuration adheres to a "unified-per-source" format, making it simple to translate configuration between sources. Here, the format is --key-with-dashes=value.	--db-url=cliValue
Environment Variable	Environment variable values are formatted using the uppercase KC_KEY_WITH_UNDERSCORES=value convention.	KC_DB_URL=envVarValue
Config file	Configuration file values are formatted using the key-with-dashes=value convention.	db-url=confFileValue

The server always reads configuration settings from the conf/keycloak.conf file by default.

Running Keycloak Server

Keycloak can be started in development mode and production mode.

To run Keycloak in development mode, go to the bin directory of Keycloak and run the boot script as shown below:

In Windows


    cd keycloak-20.0.1/bin/
    .\kc.bat start-dev

In Linux / Ubuntu / Unix


    $ cd keycloak-20.0.1/bin/
    $ ./kc.sh start-dev

When running in development mode, by default, HTTP is enabled, strict hostname resolution is disabled, cache is disabled by setting cache to local for high availability, theme and template theme is also disabled.

To start Keycloak in production mode, we have to execute the command as follows:

In Windows


    cd keycloak-20.0.1/bin/
    kc.bat start

In Linux / Ubuntu / Unix


    $ cd keycloak-20.0.1/bin/
    $ ./kc.sh start

When running Keycloak in production mode, by default, HTTP is disabled as Transport Layer Security (HTTPS) is necessary, configuration for hostname, and HTTPS/TLS are also expected.

Creating Keycloak Admin Account

After the Keycloak Server is up and running, you must first create an admin account so as to be able to access the Keycloak admin console.

Follow the steps below to create an admin account:

Open your web browser and go to http://localhost:8080. You will see the Keycloak welcome page if the server is running without error:
Enter username in the Username field and password of your choice in the Password field as shown in the example image below:

Logging into the Keycloak Admin Console

You can access the admin panel after creating the initial admin account to add users and register applications to be protected by Keycloak from this admin console.

Go to http://localhost:8080/admin/ or click the Administration Console link on the Welcome page.

To access the admin console, sign-in by entering the username and password that you created previously on the Welcome page:

On successful sign-in, the admin console's main screen appears as shown below:

Creating a Realm

A realm is responsible for managing a set of users, roles, groups, and credentials. From the admin interface, you can start creating realms, which will allow administrators to create users and grant them access to apps.

There are two types of realms:

Master Realms - This realm was created initially when you started Keycloak and it is where you'll find the admin account you created when you first logged in. This realm is only used to create other realms.
Other Realms - The admin in the master realm creates these realms. Administrators create users and applications in these realms. Users are the owners of the applications.

Follow the steps below to create a realm:

Log in to the Keycloak admin panel with the admin account at http://localhost:8080/admin/.
To create a new realm, take your mouse cursor to the top left corner over Master drop-down menu and click Create Realm from the Master menu as shown in the image below:

Enter my-app-realm or any name of your choice in the Realm name field:

Click the Create button and you will be taken to the main admin console page of your newly created realm as shown in the example below:

Creating a User

Follow the steps below to create a new user with a temporary password under your newly created realm:

Click Users from the menu to go to the user list page.
Click on the Create new user button.
Enter a username of your choice as this is the only required field. You can fill up other details if you wish.

Turn the Email Verified switch to On if you want the user to verify email address.
Click the Create button and you will be taken to the management page of the new user.
Click on the Credentials tab to create a temporary password for the new user.
Click on the Set Password button.
Enter a new password and confirm it. This password is temporary, and the user must change it the first time they log in. To create a persistent password, toggle the Temporary switch to Off.

Click on the Save button.

Logging into the Account console

The account console is accessible to every user in a realm. You can now try logging in with the user in the realm that you just created and test updating your profile information and change your credentails.

Follow these steps to login into the account console:

Go to the user menu and choose Sign Out to logout of the admin console.
Copy http://localhost:8080/realms/my-realm-name/account to your web browser, replace my-realm-name with your realm name and hit enter. Sign-in into your realm, with the username and temporary password you just created.
When you're asked to choose a new password, choose one that you'll remember.
On successful sign-in, go to Personal info and try updating your information.

You're now ready to secure your web application and services with Keycloak. See how a sample Spring Boot application is being secured here.

NOTE: When deploying Keycloak in the Production environment, you may also need to configure an external shared database like PostgreSQL, MySQL, Oracle for Keycloak storage to run in a cluster and also configure securities such as encryption and HTTPS.