Keycloak Quickstart

This quickstart tutorial includes instructions for installing the Keycloak server in standalone mode, creating accounts and realms for managing users and applications for securing applications:

Download and Run Keycloak Server

Download the Keycloak Server (Distribution powered by Quarkus) from the official site of the Keycloak.

For Windows, download the ZIP file and for Linux / Ubuntu / Unix / Mac download the TAR.GZ file.

Move the downloaded Keycloak bundle to the directory where you want to install it and unzip/extract it there. Navigate inside the bin directory of the Keycloak and run the following script file to start the server:

In Windows


    unzip keycloak-21.0.1.zip
    cd keycloak-21.0.1/bin/
    .\kc.bat start-dev

In Linux / Ubuntu / Unix


    $ sudo tar -xvzf keycloak-21.0.1.tar.gz
    $ cd keycloak-21.0.1/bin/
    $ ./kc.sh start-dev

Create Keycloak Server Initial Admin

When you run the Keycloak server for the first time and open http://localhost:8080 in your browser, you should see the Keycloak welcome page as shown in the image below:

Under the Admin Console, do as follows:

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.

Sign-in to the Keycloak Admin Console

Sign-in into the Keycloak Admin Console at http://localhost:8080/admin. When you see a welcome page as shown in the example below, click on the Administration Console.

On the login page, type your initial admin username and password as shown in the image below:

On successful sign-in, you will be redirected to the Keycloak Admin console as shown in the image below:

Create New Realm

A realm is responsible for managing a set of users, roles, groups, and credentials.

There is a pre-defined realm called master realm which is the hightest 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, take your mouse cursor to the top left corner over realms drop-down menu as shown in the image below and click on the Create Realm button when it appears:

On the Create realm page, enter the realm name of your choice in the Realm name field. For this example, we are entering my-app-realm as our realm name:

Next, cick the Create button.

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

You can switch between realms by taking your mouse cursor on the top left corner dropdown menu.

Create Clients

A client is an entity that can request for identity information or access token so as to be able to access resources secured by Keycloak on the network.

Clients are applications and services that can request Keycloak server to authenticate users.

Clients are of two types:

The first type of clients are applications that wants to secure themselves by Keycloak and uses single-sign-on.
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 your realm from the top left corner dropdown menu and go to the Clients page from the left menu. There will be some clients associated with that particular realm as shown in the example image below:

Now, click the Create client button and when it brings you to the Create Client page, do the following:

Choose OpenID Connect from the Client type dropdown list. OpenID Connect is the preferred protocol to secure applications and works best with HTLM5/Javascript applications.
In the Client ID field, enter a unique alphanumeric name. This client ID will be used in requests to identify the client. The Client ID is the ID of the client. For this example, let my-app-client be our client ID.
In the Name field, you can enter a name for your client.
Click the Next button.

Click on the Next button, you should see Client Capability config page.
Turn On Client authentication.
Turn On Authorization.
On Authentication flow option, select Standard flow, Direct access grants, and OAuth 2.0 Device Authorization Grant as shown in the image below:

Click the Next button, and you will be redirected to the Login Settings page. On this settings page, enter the base URL of your application in the Root URL field. This root URL is from where the request for your users authentication will come. The Keycloak server runs on port 8080, so we recommend you to run your application on some other port but not on 8080. The sample applications which we will build to integrate with the Keycloak server in our next tutorials, will run on port 8081. So, let http://localhost:8081 be our base URL for this example as shown below:

Choose the Save button for saving the update and you'll be redirected to your client settings page.
On your client settings page, leave the other settings as it is. You can change them later as per your application need.
Click the Save button.

Create Realm Level Roles

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 realm level roles, go to the Realm roles setting from the left menu on the realm admin console page and choose the Create role button as shown in the image below:

On the Create role page, enter a role for your users in the Role name field. Enter any description for the role in the Description field and choose the Save button. For this example, lets create a realm role for student type of users:

Next, click the Save button.

Go to the Clients setting page and look for the client that you created.

In this example, my-app-client is our client ID:

Click on the link of your client ID, it will bring you to the Client's Settings tab.

Next, go to the Service accounts roles tab, you will see something like this:

Click on Assign role, select the role that you just created as shown in the example below:

Click on the Assign button. Your role will be moved to the Assigned Roles field box as shown in the image below:

This concludes the basic setup of Keycloak for use with web applications or RESTful services.