Setup Keycloak Server on Ubuntu 18.04
https://medium.com/@hasnat.saeed/setup-keycloak-server-on-ubuntu-18-04-ed8c7c79a2d9
https://www.youtube.com/watch?v=FdYAdJkwynA
https://www.youtube.com/watch?v=XJYy6Aq-PJ8
https://www.youtube.com/watch?v=FdYAdJkwynA
https://www.youtube.com/watch?v=XJYy6Aq-PJ8
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.
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
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/7.0.0/keycloak-6.0.0.tar.gz
Extract the tar package and rename the extracted directory to keycloak.This will be Keycloak’s installation directory
$ sudo tar -xvzf keycloak-7.0.0.tar.gz$ sudo mv keycloak-7.0.0 /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:
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=keycloakLimitNOFILE=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:
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
Now access Keycloak server at:
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
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 root -p rootme123
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 masterrealm. 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:
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:
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:
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:
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/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
Save and exit the file
Since we have changed the service unit file, we have to inform the systemdmanager
$ sudo systemctl daemon-reload
Now restart the keycloak service
$ sudo systemctl restart keycloak
Once restarted, Access the Keycloak management console at:
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
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’:
Once successfully logged in, we land inside the management console
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?
- Securing Applications with Keycloak
Tidak ada komentar:
Posting Komentar