Getting Started with Keycloak

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:

Download and Run the Keycloak Server

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

  1. 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.
  2. Move the zip|tar file to a directory of your choice.
  3. Unzip the zip|tar file and run the server:
    4. Expand-Archive -Path 'keycloak-22.0.1.zip' -DestinationPath 'E:\'

cd keycloak-22.0.1/bin/

.\kc.bat start-dev

    Replace 'keycloak-22.0.1.zip' with the version of keycloak that you downloaded and 'E:\' with the actual destination folder path on your computer drive where you want to extract the contents of the keycloak-22.0.1.zip file. If the folder doesn't exist, it will be created during the extraction process.

    sudo tar -xvzf keycloak-22.0.1.tar.gz

cd keycloak-22.0.1/bin/

./kc.sh start-dev

    Replace 'keycloak-22.0.1.tar.gz' with the version of keycloak that you downloaded.

    Here, the first command unzips or extracts the zip or tar archive file.

    The second command changes the current working directory to the 'bin' folder inside the extracted 'keycloak' directory.

    The third command runs the 'kc.bat' or 'kc.sh' script with the 'start-dev' argument.

Access Admin Console

Once the server is up and running, you can access the Keycloak Admin Console in your web browser. Open your browser and go to http://localhost:8080. You should see the login page for the Keycloak Admin Console.

The first time you run the Keycloak server, you will be prompted to set up an admin username and password. To do this, follow these steps:

  • In the username field, enter admin.
  • In the password field, enter admin123$ or any other password of your wish.
  • Re-enter password in the Password Confirmation field.
  • Click the Create button.

Here's an example image:

Configure Keycloak

Now you can start configuring realms, users, clients, and other settings using the Keycloak Admin Console:

Create New Realm: A realm is a concept that represents a separate area where users, applications, and identity providers are managed. It provides a way to partition and isolate different sets of users, applications, and configuration settings. A realm is responsible for managing a set of users, roles, groups, and credentials. In some other systems, the term realm is sometimes referred to as tenants. Both terms essentially represent the same concept of creating separate partitions or isolated areas to manage users, applications, and configurations independently.

There is a pre-defined realm called master realm which is the highest level realm in the hierarchy of realms that gets created on the first time run of the Keycloak server. The initial Admin account is also created in the Master realm. Admin accounts created in the Master realm has permission to view and manage any other realms created on that particular server instance.

It is recommended to not use the Master realm to manage the users and applications. The Master realm must only be used for creating super Admins that creates and manages other realms.

To create a new realm, sign in to the Keycloak Admin Console at http://localhost:8080/admin.

On the top-left corner of the Admin Console, click on the drop-down menu and select "Create Realm" from the list.

In the Create realm page, enter a unique name of your choice in the Realm name field. Make sure the toggle button is On to enable the realm.

Click the Create button at the bottom of the page to create the new realm.

You will be taken to the main admin console page of your newly created realm as shown in the example below:

You can switch between realms by clicking on the top-left corner dropdown menu and selecting the realm of your choice from the list.

Create Clients

A client refers to an application or service that uses Keycloak for authentication and authorization purposes to access resources secured by Keycloak on the network. In other words, clients are applications and services that can request the Keycloak server to authenticate users.

Keycloak allows you to create and manage multiple clients within a realm, each with its own set of settings and permissions, making it a versatile and secure solution for managing authentication and authorization for various types of applications.

Clients are of two types:

  1. The first type of clients are applications that wants to secure themselves by Keycloak and uses single-sign-on.
  2. The second type of clients are applications that requests for access token so that they can access protected resources using that access token.

To create a client for a particular realm, choose the realm in which you want to create the client from the drop-down menu on the top-left corner of the Admin Console. Next, go to the Clients page from the left-side menu, as shown in the example image below:

On the Clients page, you'll see a list of existing clients. To create a new client, click on the Create client button on the right side of the page. When you are on the Create Client page, provide the following details for the new client:

  • Select the protocol to be used for communication with the client from the Client type dropdown list. For this example, choose OpenID Connect as it is the preferred protocol to secure applications and works best with HTML5/Javascript applications.
  • In the Client ID field, enter a unique identifier for the client. The client ID will be used in requests to identify the client. For this example, let's use "my-app-client" as our client ID.
  • In the Name field, you can enter a name for your client.

    • For example:


  • Click on the Next button. After this, you will be redirected to the Login Settings page. Here, you should enter the base URL of your application in the Root URL field. This URL is where the requests for user authentication will come from. To avoid conflicts with the Keycloak server running on port 8080, it is recommended to run your application on a different port. For this example, let's use http://localhost:8081 as our base URL, as shown below:
  • Click the Save button to save the updates, and you will be redirected to your client settings page.
  • On your client settings page, leave the other settings as they are. You can change them later according to your application's needs.
  • Click on the Save button.

Create Realm Roles

Roles play a significant role in fine-tuning the security and access control of applications, helping to ensure that users can only access the functionality and data that they are authorized to use.

Realm based roles are shared by all clients created within that realm. Role helps to identify the type or category of users. For example, roles such as admin, moderator, user, employee, student, and any other type that may exists in an organization.

To create a role for a particular realm, choose the realm in which you want to create the role from the drop-down menu on the top-left corner of the Admin Console. Next, go to the Realm client page from the left-side menu, as shown in the example image below:

Click on the Create role button. Once you are on the Create role page, provide a role name for your users in the Role name field. Optionally, you can add some details about the role in the Description field. For example:


Click on the Save button to create the role.

The next step involves assigning roles to the specific client where you want this role to be applied. To accomplish this, access the Client page from the left menu of the Admin console. The Client page should list all clients, as shown below:


Click on the client ID to which you want to assign the role. It will bring you to the Client's Settings tab.

Next, navigate to the Service accounts roles tab. You will see something like this:

Click on the Assign role button, and then select the role that you created, as demonstrated in the example below:

Click on Assign button at the bottom, and you will see the new role listed in the Service accounts roles section.

Create a User

To create a user in Keycloak, follow these steps:

  • Choose the realm in which you want to create the user from the drop-down menu on the top-left corner of the Admin Console. Next, go to the Users page from the left-side menu, as shown in the example image below:

  • Click on the Add user button.
  • When you are on the Create user page, enter a unique username in the Username field, and then click on the Create button. Next, provide other necessary details and click on the Save button. To set a temporary password for the new user, go to the Credentials tab, click on the Set Password button, enter a new password, and confirm it. Remember that this password is temporary, and the user will be prompted to change it the first time they log in.

    • If you want to create a persistent password, toggle the Temporary switch to Off, and then click on the Save button.

    Open your browser and go to http://localhost:8080/realms/my-realm-name/account, replacing "my-realm-name" with your realm name. Sign in to your realm using the username and temporary password you just created. When prompted, choose a new password that you will remember. Once you successfully sign in, you can navigate to Personal info and try updating your information.