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:

Installing and Running the Keycloak Server

The server can be installed on either Linux or Windows.

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

  1. Download keycloak-15.x.x.[zip|tar.gz] (Server) at Keycloak downloads. This download file contains scripts and binaries needed to run the Keycloak server.
  2. Move the zip file in a directory of your choice.
  3. Unzip the zip file:
  4. In Windows

    
        unzip keycloak-15.0.2.zip
        

    In Linux / Ubuntu / Unix

    
        $ sudo tar -xvzf keycloak-15.0.2.tar.gz
        
  5. Go the the bin directory of the Keycloak Server folder.
  6. Run the standalone boot script to start the Keycloak server as shown below:
  7. In Windows

    
        cd keycloak-15.0.2/bin/
        standalone.bat
       

    In Linux / Ubuntu / Unix

    
        $ cd keycloak-15.0.2/bin/
        $ ./standalone.sh
       

    The server should run without any error.

Creating Keycloak Admin Account

You must first create an admin account, which you will use to access the Keycloak admin console.

Follow the steps below to create an admin account:

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

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/auth/admin/ or click the Administration Console link on the Welcome page.

To access the admin console, enter the username and password you created on the Welcome page. 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:

  1. 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.
  2. 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:

  1. Log in to the Keycloak admin panel with the admin account at http://localhost:8080/auth/admin/.
  2. To create a new realm, take your mouse cursor to the top left corner over Master drop-down menu and click Add realm from the Master menu as shown in the image below:
  3. Type my-test-realm in the Name field:
  4. create Keycloak realm
  5. Click on the Create button and you will be taken to the main admin console page with realm set to my-test-realm.

Creating a User

Follow the steps below to create a new user with a temporary password in the my-test-realm:

  1. Click Users from the menu to go to the user list page.
  2. Click on the Add user button on the right side of the empty user list to open the Add User page.
  3. Enter a username of your choice as this is the only required field. You can fill up other details if you wish.
  4. Turn the Email Verified switch to On.
  5. Click the Save button and you will be taken to the management page of the new user.
  6. Click on the Credentials tab to create a temporary password for the new user.
  7. 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.
  8. Click on the Set Password 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:

  1. Go to the user menu and choose Sign Out to logout of the admin console.
  2. Open http://localhost:8080/auth/realms/my-test-realm/account in a web browser and log in to your my-test-realm realm as the user you just created.
  3. When you're asked to choose a new password, choose one that you'll remember.
  4. 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 need to choose an operating mode between Standalone and Domain mode. In 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.