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

  1. Download the Keycloak Server (Distribution powered by Quarkus) from the official site of the Keycloak.
  2. For Windows, download the ZIP file and for Linux / Ubuntu / Unix / Mac download the TAR.GZ file.

    Keycloak tutorial
  3. 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 Server folder and run the following script file to start the server:
  4. In Windows

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

    In Linux / Ubuntu / Unix

    
        $ sudo tar -xvzf keycloak-12.0.1.tar.gz
        $ cd keycloak-12.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, type admin.
  • In the password field, type admin123$ or any other password of your wish.
  • Retype password in the Password Confirmation field.
  • Choose Create.

Sign-in to the Keycloak Admin Console

Login to 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 login, 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, do as follows:

  • Type your realm name in the name field. For our example - my-test-realm.
  • Choose Create.

Refer to the image below for example:

create Keycloak realm

You will be taken to the main admin console page with realm set to my-test-realm.

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:

  1. The first type of clients are applications that wants to secure themselves by Keycloak and uses signle-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 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 on the Create client button and when it brings you to the Create Client page, do the following:

  • 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 our example, we will use - my-test-client.
  • In the Name field, you can give your client a name.
  • 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.
  • Click on the Next button, you should see Client Capability config page.
  • Turn On Client authentication.
  • Turn On Authorization.
  • Select Standard flow.
  • Select Direct access grants.
  • Select OAuth 2.0 Device Authorization Grant as shown in the example image below:
  • Click the Save button, and you will be redirected to the client Settings page. On your client 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, I 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, lets use http://localhost:8081 as our base URL for this example as shown below:
  • Leave the other settings as it is. You can change them later as per your application need.
  • Choose the Save button for saving the update.

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 on the right side 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. Here is an example of realm role for student type of users:

Click the Save button.

Go to the Clients page and look for the client that you created. In this example, our client is my-test-client.

Click on the link of your client ID, it will bring you to the Client's Settings tab as shown in the image below:

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.