Keycloak

Keycloak is an open source identity and access management system which allows single sign-on for web applications and services.


Note

For this guide you should be familiar with the basic concepts of

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 ~]$

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>