To get started with Keycloak, follow the steps below to setup the Keycloak server:
For Windows, download the ZIP file and for Linux / Ubuntu / Unix / Mac download the TAR.GZ file.
unzip keycloak-12.0.1.zip cd keycloak-12.0.1/bin/ standalone.bat
$ sudo tar -xvzf keycloak-12.0.1.tar.gz $ cd keycloak-12.0.1/bin/ $ ./standalone.sh
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:
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:
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:
Refer to the image below for example:
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.
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:
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:
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:
Refer to the example image below:
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.