This guide contains the necessary methodology to deploy a Identity and Access Management provider on a Enterprise Linux 9 based environment with recommended security considerations.
In order to set up a complete Identity and Access Manager, this guide takes advantage of Keycloak which is a complete and open source Identity and Access Management backed by the RedHat team.
To be able to configure Keycloak properly, you need to have the super-administrator right on your machine for every steps of the installation. We recommend you to process this entire installation on the root account or to run every commands behind the sudo prefix.
All of the security rules applied in this document is only the recommended on minimal security that a production environment need, this doesn't make the server invulnerable, you should yourself have your owns additional rules and preventions. Remember in Linux that the rule number one is: less privileges, more security. Set the least of privileges on files, processes, and users. Always keep your system up to date.
Edition of the February 2023 Document edited by : Matisse AMEN GEORGE (hello@matissime.eu) Find me on the social network : https://linktr.ee/matissime
[TOC]
Before installing Keycloak, we must install the library OpenJDK 17 or newer, to do that we need to install two java package :
dnf install java-11-openjdk-devel
dnf install java-17-openjdk-devel
Select the higher version of java (should be the 17):
alternatives --config java
Install the MariaDB packages:
dnf install mariadb-server php-mysqlnd
systemctl enable --now mariadb
Next, we need to secure our database access (run it as root with sudo) :
mariadb-secure-installation
And, answer theses questions :
Enter current password for root --> None (Press enter)
Set root password? --> n
Switch to unix_socket authentication --> n
Change the root password? --> n
Remove anonymous users? --> y
Disallow root login remotely? --> y
Remove test database and access to it? --> y
Reload privilege tables now? --> y
Now, we will create the database for Keycloak, first connect to the MariaDB back-end :
mariadb
And create a database named keycloak_prod :
CREATE DATABASE keycloak_prod CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
And now we create a user named keycloak_prod :
GRANT ALL PRIVILEGES ON keycloak_prod.* TO 'keycloak_prod'@'localhost' IDENTIFIED BY 'greatpassword';
Update the permissions changes we've done and exit the MariaDB shell :
FLUSH PRIVILEGES;
EXIT;
And now for security purpose we will delete the MariaDB command prompt history to avoid someone to retrive the password from the history :
rm /root/.mysql_history
Or remove the file from your user home folder if you access MariaDB with your user credentials instead of root.
Now that we have OpenJDK 17 and MariaDB installed, we can download the latest Keycloak release on github : https://github.com/keycloak/keycloak/releases/latest
https://github.com/keycloak/keycloak/releases/download/20.0.2/keycloak-20.0.2.zip
unzip keycloak-*.zip
And place all the content of the zip file into the directory you want but I recommend you using this one : /opt/keycloak
mkdir /opt/keycloak
mv keycloak-* /opt/keycloak
Create a keycloak user :
useradd keycloak
And set all the permissions of the Keycloak directories to this user :
chown -R keycloak:keycloak /opt/keycloak
chmod -R 775 /opt/keycloak
Go in the keycloak directory:
cd /opt/keycloak
Now you need to specify the database provider and credentials in the keycloak configure file :
sudo -u keycloak nano conf/keycloak.conf
Set the credentials you've chosen when creating the PostgreSQL database previously in the database section:
# Database
# The database vendor.
db=mariadb
# The username of the database user.
db-username=keycloak_prod
# The password of the database user.
db-password=greatpassword
# The full database JDBC URL. If not provided, a default URL is set based on the selected database vendor. The string is structured like that: jdbc:postgresql://<database_host/<database_name>
db-url=jdbc:mariadb://localhost/keycloak_prod
# Observability
# If the server should expose healthcheck endpoints.
health-enabled=true
# If the server should expose metrics endpoints.
metrics-enabled=true
Set also the hostname that will be used to connect on internet :
# Hostname for the Keycloak server.
hostname=fqdn.domain.tld
If you want to run keycloak behind a reverse proxy like HAProxy with SSL offloading, you can set these value : Note : If you set keycloak in edge proxy mode, it will not work outside the reverse proxy, so if you attempt to access it from directly from the IP, you will get blocked on the login page that will load infinitely because keycloak detected that there is no reverse proxy.
# PROXY
proxy=edge
hostname_strict_https=false
Or, if you directly want to keycloak that handle HTTPS connection, you will need to provide a pem certificate file as well as its belonging private key :
# HTTP
https-certificate-file=/the/path/to/your/certficate.crt.pem
https-certificate-key-file=/the/path/to/your/certificate.key.pem
Switch to the keycloak user :
sudo su keycloak
And define environment variables to create the admin account :
export KEYCLOAK_ADMIN=admin
export KEYCLOAK_ADMIN_PASSWORD=admin
Now you need to build the server using the keycloak user
bin/kc.sh build
And start the server :
bin/kc.sh start-dev
Test the data persistence by creating a test user, and rebooting the keycloak instance.
Create a systemd service for keycloak :
nano /etc/systemd/system/keycloak.service
[Unit]
Description=Keycloak
After=network.target
[Service]
User=keycloak
Group=keycloak
ExecStart=/var/www/keycloak/bin/kc.sh start --optimized
[Install]
WantedBy=multi-user.target
Reload the systemd daemon :
systemctl daemon-reload
And enable the keycloak service we just created :
systemctl enable --now keycloak