Keycloak Quickstart

To get started with Keycloak, follow the steps below to setup the Keycloak server:

Download and Run Keycloak Server

  1. Download the Keycloak Server (Distribution Powered By WildFly) 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/
    standalone.bat
       

    In Linux / Ubuntu / Unix

    
        $ sudo tar -xvzf keycloak-12.0.1.tar.gz
    $ cd keycloak-12.0.1/bin/
    $ ./standalone.sh
       

Create Keycloak Server Initial Admin

When you run the Keycloak server for the first time and open http://localhost:8080/auth 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/auth/admin.

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 Add realm button when it appears:

On the Add 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

After creating a new realm, you will be taken to your newly created realm Admin console page, as shown in the image 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:

  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 button on the right side of the page and when it brings you to the Add 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. For our example, we will use - my-test-client.
  • Choose openid-connect from the Client Protocol dropdown list. OpenID Connect is the preferred protocol to secure applications and works best with HTLM5/Javascript applications.
  • In the Root URL field, enter the base URL of your application 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.
  • Choose the Save button.

Refer to the example image below for creating a new client:

This will create your client and bring you to your client Settings page. On your client settings page, do the following:

  • The Client ID is the ID of the client, leave it as it is.
  • In the Name field, you can give your client a name. For our example - My Client.
  • For Access Type, choose confidential. The confidential access type allows us to create and login users from our application.
  • Enable the Standard Flow Enabled option by setting it to ON.
  • Enable the Direct Access Grants Enabled option by setting it to ON.
  • Enable the Authorization Enabled option by setting it to ON.
  • Leave the other settings as it is. You can change them later as per your need.
  • Choose the Save button

Refer to the example image below:

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 Roles setting from the left menu on the realm admin console page and choose the Add Roles button on the right side as shown in the image below:

On the Add Role page, type a role for your users in the Role Name field and choose the Save button. For our example - student.

Next, go to the Clients page and look for your client. In our case - my-test-client.

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

Next, go to the Service Account Roles tab as shown in the image below:

Choose your role in the Available Roles field box and click the Add selected 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.