Keycloak
Keycloak is an open source identity and access management system which allows single sign-on for web applications and services.
License
Keycloak is released under the Apache 2.0 license.
Prerequisites
You’ll need your MySQL credentials. Get them with my_print_defaults
:
[isabell@stardust ~]$ my_print_defaults client
--default-character-set=utf8mb4
--user=isabell
--password=MySuperSecretPassword
[isabell@stardust ~]$
You can use the domains that are currently configured:
[isabell@stardust ~]$ uberspace web domain list
isabell.uber.space
[isabell@stardust ~]$
If you want to use Keycloak with a domain not shown here, such as your own domain, setup your domain for use with your Asteroid.
Installation
Download
Download the latest version of Keycloak release from the GitHub release page:
[isabell@stardust ~]$ curl -L https://github.com/keycloak/keycloak/releases/download/26.1.2/keycloak-26.1.2.tar.gz | tar -xzf -
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0
100 141M 100 141M 0 0 52.6M 0 0:00:02 0:00:02 --:--:-- 62.6M
[isabell@stardust ~]$
Create symlink
Next create a symlink to point to the latest version:
[isabell@stardust ~]$ ln -sf ~/keycloak-26.1.2 ~/keycloak
[isabell@stardust ~]$
Configuration
Create database
Create a database for Keycloak:
[isabell@stardust ~]$ mysql --execute "CREATE DATABASE ${USER}_keycloak"
[isabell@stardust ~]$
Configure Keycloak
Update the config file ~/keycloak/conf/keycloak.conf
with the following content:
Note
Replace isabell
with your username and fill the database password db-password
with yours.
# The database vendor.
db=mariadb
# The username of the database user.
db-username=isabell
# The password of the database user.
db-password=MySuperSecretPassword
# The full database JDBC URL. If not provided, a default URL is set based on the selected database vendor.
db-url=jdbc:mariadb://localhost/isabell_keycloak
# Hostname for the Keycloak server.
hostname=isabell.uber.space
# Enables the HTTP listener.
http-enabled=true
# The proxy headers that should be accepted by the server.
proxy-headers=xforwarded
Create initial admin user
To create a temporary admin user, execute the following command:
[isabell@stardust ~]$ ~/keycloak/bin/kc.sh bootstrap-admin user
Changes detected in configuration. Updating the server image.
Updating the configuration and installing your custom providers, if any. Please wait.
[...]
Enter username [temp-admin]:
Enter password: [hidden]
Enter password again: [hidden]
[...]
[isabell@stardust ~]$
This command will prompt for a username and a password.
Warning
The created admin user is temporary and should be replaced with a new user using the Administration Console.
Set up web backend
Note
Keycloak will run on port 8080.
To make the application accessible from the outside, configure a web backend:
[isabell@stardust ~]$ uberspace web backend set / --http --port <port>
Set backend for / to port <port>; please make sure something is listening!
You can always check the status of your backend using "uberspace web backend list".
[isabell@stardust ~]$
Set up daemon
Use your favourite editor to create the file ~/etc/services.d/keycloak.ini
with the following content.
[program:keycloak]
command=%(ENV_HOME)s/keycloak/bin/kc.sh start
autostart=yes
autorestart=yes
startsecs=60
After creating the configuration, tell supervisord to refresh its configuration and start the service:
[isabell@stardust ~]$ supervisorctl reread
SERVICE: available
[isabell@stardust ~]$ supervisorctl update
SERVICE: added process group
[isabell@stardust ~]$ supervisorctl status
SERVICE RUNNING pid 26020, uptime 0:03:14
[isabell@stardust ~]$
You can check the service’s log file using supervisorctl tail -f keycloak
.
Finishing installation
Point your browser to your installation URL https://isabell.uber.space
and use Keycloak. As mentioned earlier, you should create a new admin user for the master realm and delete the temporary admin user afterwards.
Updates
Note
Check the update feed regularly to stay informed about the newest version.
Before keycloak can be updated, it needs to be shutdown first:
[isabell@stardust ~]$ superivisorctl stop keycloak
[isabell@stardust ~]$
Next, install the new version as described in the installation chapter.
Then copy conf/
, providers/
and themes/
from the previous installation to the new installation.
Please have a look at the Upgrading Guide and perform any manual migration steps.
After that start Keyclock again:
[isabell@stardust ~]$ superivisorctl start keycloak
[isabell@stardust ~]$
Keycloak performs database migrations automatically.
Tested with Keycloak 26.2.1, Uberspace 7.16.1
Written by: Julius Künzel, Yannick Ihmels <yannick@ihmels.org>