Setup Keycloak Server on Ubuntu 18.04

Hasnat Saeed
9 min readJul 31, 2019

--

Keycloak, by RedHat Community, is an open-source Identity and Access Management solution aimed at modern applications and services. It makes it easy to secure applications and services with little to no code.

Keycloak offers a broad set of features, like SSO, authentication and authorization, social login, multifactor authentication, and centralized user management. I suggest you check the official documentation to get all the details.

Keycloak Home Page

In this article, we’ll cover the basics of downloading and setting up a Keycloak server.

Step 1 — Install JDK

Keycloak requires Java 8 or later versions to work. You can check and verify that Java is installed with the following command.

$ java -version

If java is not installed, you will see java: command not found”. Run below commands to install Java.

$ sudo apt-get update$ sudo apt-get install default-jdk -y

After installation, check if java is installed correctly by executing below command

$ java -version
Installed Java version

If Java is installed, the output should look similar to above depending upon what is the latest version of java at that time.

Step 2 — Download and Extract Keycloak Server

Check Keycloak downloads page for latest releases before downloading. For this tutorial, we will download Keycloak 6.0.1 Standalone Server Distribution.

We are going to install Keycloak to /opt directory, so we will download the Keycloak package to that location.

Change directory to /opt and download Keycloak to that directory.

$ cd /opt$ sudo wget https://downloads.jboss.org/keycloak/6.0.1/keycloak-6.0.1.tar.gz

Extract the tar package and rename the extracted directory to keycloak. This will be Keycloak’s installation directory

$ sudo tar -xvzf keycloak-6.0.1.tar.gz$ sudo mv keycloak-6.0.1 /opt/keycloak

Step 3 — Create User and Group for Keycloak

We should not run Keycloak under the root user for security reasons. Let’s create a group keycloak and add a user keycloak to it.

Additionally, the home directory of keycloak user will be the Keycloak’s installation directory i.e. /opt/keycloak.

$ sudo groupadd keycloak$ sudo useradd -r -g keycloak -d /opt/keycloak -s /sbin/nologin keycloak

Step 4 — Change Permission and Ownership of the Keycloak Installation Directory

Next, we will modify ownership and permission of /opt/keycloak directory. We will also give executable permissions to /opt/keycloak/bin/ directory. While under /opt directory, run the following commands:

$ sudo chown -R keycloak: keycloak$ sudo chmod o+x /opt/keycloak/bin/

Step 5 — Creating a SystemD Service File for Keycloak

Create a configuration directory for Keycloak under /etc directory by the name keycloak.

$ cd /etc/$ sudo mkdir keycloak

Copy Keycloak configuration file /opt/keycloak/docs/contrib/scripts/systemd/wildfly.conf to /etc/keycloak/ and rename it to keycloak.conf

$ sudo cp /opt/keycloak/docs/contrib/scripts/systemd/wildfly.conf /etc/keycloak/keycloak.conf

Next, copy Keycloak launch script (launch.sh) under /opt/keycloak/docs/contrib/scripts/systemd/ to /opt/keycloak/bin/ directory

$ sudo cp /opt/keycloak/docs/contrib/scripts/systemd/launch.sh /opt/keycloak/bin/

We need to make keycloak user as the owner of this script so that it can execute it:

$ sudo chown keycloak: /opt/keycloak/bin/launch.sh

Next we need to correct the Keycloak installation path in launch.sh, so open launch.sh in an editor.

$ sudo nano /opt/keycloak/bin/launch.sh

Update the Keycloak installation path as shown below:

launch.sh script

Save and exit the file.

Now, copy service definition file (wildfly.service) under /opt/keycloak/docs/contrib/scripts/systemd/ to /etc/systemd/system/ directory and rename it to keycloak.service

$ sudo cp /opt/keycloak/docs/contrib/scripts/systemd/wildfly.service /etc/systemd/system/keycloak.service

Open keycloak.service in an editor

$ sudo nano /etc/systemd/system/keycloak.service

Make the changes marked as bold or you can simply copy/paste the below content as it is.

[Unit]
Description=The Keycloak Server
After=syslog.target network.target
Before=httpd.service
[Service]
Environment=LAUNCH_JBOSS_IN_BACKGROUND=1
EnvironmentFile=/etc/keycloak/keycloak.conf
User=keycloak
Group=keycloak
LimitNOFILE=102642
PIDFile=/var/run/keycloak/keycloak.pid
ExecStart=/opt/keycloak/bin/launch.sh $WILDFLY_MODE $WILDFLY_CONFIG $WILDFLY_BIND

StandardOutput=null
[Install]
WantedBy=multi-user.target

Save and exit the file.

Reload systemd manager configuration and enable keycloak service on system startup

$ sudo systemctl daemon-reload$ sudo systemctl enable keycloak

To start keycloak system service:

$ sudo systemctl start keycloak

Once the service is started, we can check the status by running below command:

$ sudo systemctl status keycloak

If the service started successfully, we should see something like below:

Keycloak system service status

The Active status, as highlighted, above verifies that the service is up and running.

We can also tail the Keycloak server logs with below command:

$ sudo tail -f /opt/keycloak/standalone/log/server.log
Keycloak server logs

Now access Keycloak server at:

http://<instance-public-ip>:8080/auth/

Step 6 — Create the Initial Administrator User

As shown on the landing page, we need to create an initial admin account to be able to access Keycloak administration console. Keycloak does not come with any configured admin account out of the box.

The admin account will allow us to create an admin that can log into the master realm’s administration console so that we can start creating realms, users and registering applications to be secured by Keycloak.

If we are accessing Keycloak from localhost on a browser, we can easily create this admin user by navigating to http://localhost:8080/auth

Create Initial Admin Account

Simply specify the username and password for this initial admin and we are good to go.

Since we are accessing the server from outside of localhost, we have to use the bash script (add-user-keycloak.sh) available under /opt/keycloak/bin/ directory to create the initial administrator account.

$ sudo /opt/keycloak/bin/add-user-keycloak.sh -r master -u <username> -p <password>

When Keycloak is booted for the first time, Keycloak creates a pre-defined realm for us. This initial realm is the master realm. It is the highest level in the hierarchy of realms. Admin accounts in this realm have permissions to view and manage any other realm created on the server instance.

The initial admin account that we just created is associated with the master realm. So later on in this tutorial, our initial login to the admin console will also be via the master realm using the admin credentials that we just created.

Restart the keycloak service:

$ sudo systemctl restart keycloak

Once Keycloak is restarted, navigate to:

http://<instance-public-ip>:8080/auth/

As we can see the message telling us to create initial admin user is gone. Now click on the Administration Console link to access master realm’s administration console.

Step 7 — Disable SSL on Master Realm And Login to Admin Console

When we click the Administration Console link in the previous step, we get the following error message:

HTTPS required error page

The above error shows up because Keycloak now defaults to HTTPS for all external IP addresses. This default behavior applies to the master realm as well.

Keycloak can run out of the box without SSL so long as we stick to private IP addresses like localhost, 127.0.0.1, 10.0.x.x, 192.168.x.x, and 172.16.x.x. If SSL/HTTPS is not configured on the server or if we try to access Keycloak over HTTP from a non-private IP address we will get the above error.

To get around this, we need some way to disable SSL for the master realm. One way to do this is through the Admin CLI scripts that are packaged inside Keycloak Server distribution. We can find these scripts inside the /opt/keycloak/bin/ directory.

The Linux script is called kcadm.sh, and the script for Windows is called kcadm.bat.

The Admin CLI works by making HTTP requests to Admin REST endpoints. Access to them is protected and requires authentication.

We can start an authenticated session by providing admin user credentials (created in Step 6) and logging in.

$ sudo /opt/keycloak/bin/kcadm.sh config credentials --server http://localhost:8080/auth --realm master --user <admin-username> 
–-password <admin-password>

Once logged in, we are ready to perform create, read, update, and delete (CRUD) operations.

To disable SSL on master realm we can use the update command:

$ sudo /opt/keycloak/bin/kcadm.sh update realms/master -s sslRequired=NONE

We do not need to restart Keycloak for this, just refresh the error page or go to:

http://<instance-public-ip>:8080/auth/admin/

Keycloak admin login

To login enter the admin username and password

We have successfully logged into the master realm administration console. We can now create new realms, clients, roles, groups or users as we need.

Step 8 — Configure Keycloak Management Console

The Keycloak management console allows us to manage different aspects of the Keycloak server. e.g. configuring subsystems, server monitoring, managing deployments or access control.

By default, the management console is not made accessible remotely. To make it accessible we have to make small changes in 3 files. So let’s start

Open keycloak.conf file under /etc/keycloak/ directory

$ sudo nano /etc/keycloak/keycloak.conf

Add a line at the end as shown below:

keycloak.conf

Save and exit the file.

Now open launch.sh in /opt/keycloak/bin/ directory and change its contents as shown below:

$ sudo nano /opt/keycloak/bin/launch.sh
launch.sh

Save and exit the file

Finally, open Keycloak’s system service definition file (keycloak.service) under /etc/systemd/system/ and make the changes as shown below:

$ sudo nano /etc/systemd/system/keycloak.service
keycloak.service

Save and exit the file

Since we have changed the service unit file, we have to inform the systemd manager

$ sudo systemctl daemon-reload

Now restart the keycloak service

$ sudo systemctl restart keycloak

Once restarted, Access the Keycloak management console at:

http://<instance-public-ip>:9990

Keycloak Management Console

We can successfully access the management console but as shown above, we need a management user to login.

We can use the add-user.sh script, packaged with Keycloak server distribution, to create a management user. Run the script with below command:

$ sudo /opt/keycloak/bin/add-user.sh
add-user.sh script

Once prompted, select to add a management user and provide your desired username and password.

In the last prompt, for enabling remote access for this user write yes or y.

After providing the required information, the script will verify the user creation as shown above.

We need to restart Keycloak server so our user is picked up during boot.

$ sudo systemctl restart keycloak

Now if we access the management console again, it will prompt for HTTP basic authorization.

Provide the management user credentials that we created above and click ‘ok’:

Keycloak admin console HTTP basic authorization

Once successfully logged in, we land inside the management console

Keycloak Management Conole

We have just done basic setup of Keycloak server and enabled/configured remote access to administration and management console. This concludes our tutorial.

Thanks for reading. Please feel free to comment.

Some helpful resources:

  • Keycloak Getting Started Guide
  • Keycloak Server Administration Guide
  • Kecloak Admin REST API Guide
  • Keycloak Server Installation Guide
  • Keycloak Downloads Homepage
  • How does Keycloak Work?

https://www.comakeit.com/quick-guide-using-keycloak-identity-access-management/

  • Securing Applications with Keycloak

https://www.baeldung.com/spring-boot-keycloak

http://www.mastertheboss.com/jboss-frameworks/keycloak/introduction-to-keycloak

--

--