Introduction
Keycloak is an open-source Identity and Access Management (IAM) solution for modern applications and services. It provides features such as Single Sign-On (SSO), user federation, identity brokering, and fine-grained authorization. If you’re developing on a Windows Subsystem for Linux (WSL) using Ubuntu, you may want to install Keycloak to manage authentication securely.
In this guide, we’ll walk you through installing Keycloak on WSL (Ubuntu) step by step. This tutorial is designed for beginners and advanced users who want to set up Keycloak in a development or production environment.
Prerequisites
Before we begin, ensure that you have:
- A Windows system with WSL2 enabled (Ubuntu installed)
- Internet access to download Keycloak
- Basic Linux command-line knowledge
Step 1: Update Your System
It is always recommended to update your system before installing new packages. Open your WSL Ubuntu terminal and run:
sudo apt update && sudo apt upgrade -y
Step 2: Install Java (OpenJDK 17)
Keycloak requires Java 17 or higher. Install OpenJDK 17 using the following command:
sudo apt install openjdk-17-jdk -y
To verify the installation, check the Java version:
java -version
You should see output similar to:
openjdk version "17.0.10" 2024-03-19
Step 3: Download Keycloak
Go to the Keycloak Downloads Page and copy the latest version URL. Then, use wget to download it:
wget https://github.com/keycloak/keycloak/releases/download/24.0.1/keycloak-24.0.1.zip
(Replace 24.0.1 with the latest available version.)
Step 4: Extract Keycloak
Once downloaded, extract the Keycloak archive:
unzip keycloak-*.zip
mv keycloak-* keycloak
cd keycloak
Step 5: Create a Keycloak User
It is a good practice to run Keycloak with a dedicated user.
sudo adduser keycloak
sudo chown -R keycloak:keycloak ~/keycloak
Step 6: Configure Keycloak (Optional for Production Use)
Keycloak supports multiple databases. If you want to use PostgreSQL, you need to configure it:
Install PostgreSQL
sudo apt install postgresql -y
sudo systemctl start postgresql
Create a Database and User for Keycloak
sudo -u postgres psql
CREATE DATABASE keycloak;
CREATE USER keycloak WITH ENCRYPTED PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE keycloak TO keycloak;
\q
Configure Keycloak to Use PostgreSQL
Edit conf/keycloak.conf:
db=postgres
db-url=jdbc:postgresql://localhost:5432/keycloak
db-username=keycloak
db-password=your_password
Step 7: Start Keycloak
For development mode (without a database), run:
bin/kc.sh start-dev
For production mode (with PostgreSQL):
bin/kc.sh start
Once Keycloak starts, you can access the admin console at: http://localhost:8080
Step 8: Create an Admin User
To create an admin user, open another terminal window and run:
bin/kcadm.sh config credentials --server http://localhost:8080 --realm master --user admin --password admin
Now, you can log in to the Keycloak Admin Console with:
- Username:
admin - Password:
admin
Step 9: Enable Keycloak as a Service (Optional for Persistent Use)
If you want Keycloak to start automatically on boot, create a systemd service file:
sudo nano /etc/systemd/system/keycloak.service
Add the following content:
[Unit]
Description=Keycloak Server
After=network.target
[Service]
User=keycloak
WorkingDirectory=/home/keycloak/keycloak
ExecStart=/home/keycloak/keycloak/bin/kc.sh start
Restart=always
[Install]
WantedBy=multi-user.target
Save the file and enable the service:
sudo systemctl daemon-reload
sudo systemctl enable keycloak
sudo systemctl start keycloak
To check the status:
sudo systemctl status keycloak
Conclusion
Congratulations! 🎉 You have successfully installed Keycloak on WSL Ubuntu. You can now use Keycloak for authentication and identity management in your applications.
Next Steps:
- Configure SSO for your applications
- Integrate with OAuth 2.0, OpenID Connect, or SAML
- Secure APIs and Microservices
- Explore Keycloak themes and customization
If you found this tutorial helpful, don’t forget to share it! 🚀
