Guida alla configurazione di un server Keycloak
Questo thread raccoglie tutte le informazioni necessarie al setup di un’istanza Keycloak in modalità standalone, dietro un reverse proxy NGINX e con backend PostgreSQL.
La guida è volutamente basata su una versione di Keycloak non recente, da usare successivamente come base di partenza per illustrare il processo di upgrade.
Prerequisiti
Eseguiamo una installazione cosiddetta bare-metal, ovvero direttamente sull’host che esegue il sistema operativo, invece che un’installazione su container.
- Sistema operativo host: Ubuntu Server 20.04
- Java: OpenJDK 11
- PostgreSQL: 12
Dopo aver installato il sistema operativo server, aggiornare tutti i pacchetti e installare il Java Runtime Environment. Se necessario, riavviare il sistema:
sudo apt update
sudo apt upgrade
sudo apt install default-jre-headless postgresql
sudo shutdown -r now
Preparazione del database
L’interazione con il DBMS PostgreSQL avviene tramite il programma client psql
oppure tramite utility dedicate. Eseguendolo per conto dell’utente postgres
si ha pieno accesso amministrativo, potendo quindi istanziare database e utenti.
Per keycloak, creeremo un database ed un utente dedicato.
Setup database
Per interagire con DBMS come amministratori, utilizziamo l’account postgres
creato automaticamente in fase di installazione del software.
Creazione utente database
Per l’accesso al database, usiamo un utente dedicato denominato keycloak
sudo -u postgres createuser -P keycloak
Verrà chiesto di scegliere una password per l’utente appena creato. Questa password ci servirà poi in fase di configurazione dell’applicazione.
Creazione database
Anche per il database, scegliamo il nome keycloak_db
sudo -u postgres createdb --owner=keycloak keycloak_db
A questo abbiamo un database chiamato keycloak_db
accessibile dall’utente keycloak
usando la password specificata oppure tramite un omonimo utente di sistema.
Preparazione dell’utente che eseguirà l’applicazione Keycloak
Per eseguire l’applicazione Keycloak predisponiamo un utente dedicato, evitando così di eseguire il servizio come utente root. Creiamo a tal proposito l’utente di sistema denominato keycloak
, non a caso lo stesso nome usato per l’utente del database:
sudo adduser --system --home /home/wildfly --group --disabled-password --shell /bin/bash keycloak
Uso il nome wildfly
per la home directory perché corrisponde al nome dell’application server su cui gira il software (in precedenza, WildFly era noto come JBoss).
Il comando precedente provvederà a creare anche il gruppo keycloak
omonimo, che sarà il gruppo primario dell’utente.
L’utente, così come è configurato, non ha una password e non può fare il login nella maniera tradizionale. Possiamo però impersonare l’utente ed eseguire tutte le operazioni successive in sua vece:
sudo su - keycloak
Il comando precedente avvia una shell di login per l’utente keycloak
. Infatti:
~$ whoami
keycloak
~$ pwd
/home/wildfly
Download del software
Scarichiamo e scompattiamo Keycloak 15.0.2 nella home dell’utente keycloak
:
wget https://github.com/keycloak/keycloak/releases/download/15.0.2/keycloak-15.0.2.tar.gz
tar xzvf keycloak-15.0.2.tar.gz
Verrà creata la directory keycloak-15.0.2 di proprietà dell’utente keycloak
.
Installazione e configurazione driver JDBC per PostgreSQL
Affinché l’applicazione Keycloak sia in grado di utilizzare un DBMS esterno al posto di quello integrato, è necessario fornire e configurare il driver opportuno. Sul sito di Keycloak c’è una guida abbastanza dettagliata:
https://www.keycloak.org/docs/latest/server_installation/#_database
Creazione del struttura di directory
Spostarsi in modules/system/layers/keycloak/org
e creare la directory per il modulo del driver PostgreSQL:
cd keycloak-15.0.2/modules/system/layers/keycloak/org
mkdir -p postgresql/main
cd postgresql/main
wget https://jdbc.postgresql.org/download/postgresql-42.3.2.jar
Nella stessa directory, creare il file denominato module.xml
con il seguente contenuto:
<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.3" name="org.postgresql">
<resources>
<resource-root path="postgresql-42.3.2.jar"/>
</resources>
<dependencies>
<module name="javax.api"/>
<module name="javax.transaction.api"/>
</dependencies>
</module>
Configurazione Keycloak standalone con backend PostgreSQL
Poiché si intende eseguire l’applicazione in modalità “standalone”, ovvero non in HA né in cluster, bisognerà intervenire sul file di configurazione apposito nella directory keycloak-15.0.2/standalone/configuration
. Il file in questione è denominato standalone.xml
.
In questo file vanno specificati i dettagli del driver da usare per connettersi al DBMS, nonché le politiche di creazione e migrazione del database.
Dichiarazione del driver
Nel file standalone.xml
, nella sezione dedicata ai driver dei database, aggiungere la porzione di codice seguente:
<subsystem xmlns="urn:jboss:domain:datasources:6.0">
<datasources>
...
<drivers>
<!-- INIZIO porzione da aggiungere -->
<driver name="postgresql" module="org.postgresql">
<driver-class>org.postgresql.Driver</driver-class>
<xa-datasource-class>org.postgresql.xa.PGXADataSource</xa-datasource-class>
</driver>
<!-- FINE porzione da aggiungere -->
<driver name="h2" module="com.h2database.h2">
<xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>
</driver>
</drivers>
</datasources>
</subsystem>
Definizione della datasource
Definito il driver, è necessario dire a Keycloak di usare una “datasource” differente rispetto a quella predefinita. Sempre nel file standalone.xml
, aggiungere la seguente porzione nella sezione datasources, rimpiazzando quella di default che punta al database H2:
<subsystem xmlns="urn:jboss:domain:datasources:6.0">
<datasources>
...
<datasource jndi-name="java:jboss/datasources/KeycloakDS" pool-name="KeycloakDS" enabled="true" use-java-context="true">
<connection-url>jdbc:postgresql://localhost/keycloak_db</connection-url>
<driver>postgresql</driver>
<pool>
<max-pool-size>20</max-pool-size>
</pool>
<security>
<user-name>keycloak</user-name>
<password>PASSWORD UTENTE DB</password>
</security>
</datasource>
...
</datasources>
</subsystem>
Configurazione database
Questa porzione di configurazione stabilisce come si deve interagire col database quando questo è vuoto (prima installazione) oppure quando si fa una migrazione (ad esempio in seguito ad un aggiornamento dell’applicazione).
Impostando il parametro initializeEmpty
a true
, si fa in modo che al primo avvio l’applicazione si preoccupi di creare nel database la struttura di tabelle necessarie. Il default è true
. Analogamente, migrationsStrategy
stabilisce l’approccio da prendere in seguito a un aggiornamento (default update
).
<subsystem xmlns="urn:jboss:domain:keycloak-server:1.1">
...
<spi name="connectionsJpa">
<provider name="default" enabled="true">
<properties>
<property name="dataSource" value="java:jboss/datasources/KeycloakDS"/>
<property name="initializeEmpty" value="true"/>
<property name="migrationStrategy" value="update"/>
<property name="migrationExport" value="${jboss.home.dir}/keycloak-database-update.sql"/>
</properties>
</provider>
</spi>
...
</subsystem>
Primo avvio (manuale) e creazione utente admin
La prima cosa da fare prima di utilizzare l’applicazione è quella di creare l’utente amministratore del realm Master, che è il realm da cui si eseguono tutte le configurazioni.
La creazione dell’admin può avvenire da command line, mediante uno script dedicato, oppure da interfaccia web dopo aver avviato l’applicazione sul server. L’accesso web senza SSL, tuttavia, è permesso soltanto da localhost, almeno finché non si sarà completata la configurazione del reverse proxy o non sia configurato l’application server per usare https.
Se si sta configurando l’applicazione sul proprio client, è sufficiente lanciare il comando bin/standalone.sh
dalla directory keycloak-15.0.2 e poi accedere dal browser alla URL http://localhost:8080; se ciò non fosse possibile, perché l’applicazione è installata su un server remoto, dopo aver avviato l’applicazione si può ricorrere al tunnelling ssh dal proprio client, facendo il forward della porta 8080 locale alla porta 8080 del server Keycloak:
ssh -L 8080:localhost:8080 user@keycloak.server.address
Creazione utente
Accedendo a http://localhost:8080 si viene invitati a creare l’utenza amministrativa:

Schermata di Keycloak al momento del primo accesso per configurare l’utenza amministrativa
Configurazione script di avvio
Per gestire il servizio keycloak come servizio Systemd, quindi con il sistema di gestione dei servizi della maggioranza delle distribuzioni Linux moderne, è necessario:
- predisporre una cartella contenente le opzioni di configurazione del servizio
- collocare uno script bash di avvio del servizio nella directory
bin
della distribuzione di keycloak - configurare e attivare la unit systemd
Directory e file di configurazione
Posizioniamo la configurazione del software in /etc/keycloak/keycloak.conf
. La directory va ovviamente creata da root (o sudo): sudo mkdir /etc/keycloak
Creare il file di configurazione keycloak.conf
con il seguente contenuto:
# The configuration you want to run
KEYCLOAK_CONFIG=standalone.xml
# Keycloak home directory
KEYCLOAK_HOME=/home/wildfly/keycloak-15.0.2
# The mode you want to run
KEYCLOAK_MODE=standalone
# The address to bind
KEYCLOAK_BIND=127.0.0.1
Questo file si limita semplicemente a stabilire la modalità di funzionamento del software (standalone) e a fare in modo che il servizio sia in ascolto solo su localhost.
Script di avvio
Nella directory bin
all’interno della distribuzione di Keycloak intstallata (nel nostro caso /home/wildfly/keycloak-15.0.2/bin
) creare il file launch.sh
con il seguente contenuto:
#!/bin/bash
if [ "x$KEYCLOAK_HOME" = "x" ]; then
KEYCLOAK_HOME="/home/wildfly/keycloak-15.0.2"
fi
if [[ "$1" == "domain" ]]; then
$KEYCLOAK_HOME/bin/domain.sh -c $2 -b $3
else
$KEYCLOAK_HOME/bin/standalone.sh -c $2 -b $3
fi
Il precedente script avvia il servizio invocando domain.sh
oppure standalone.sh
in funzione del primo argomento che riceve in ingresso sulla command line ($1). $2 e $3 saranno invece il file di configurazione e l’indirizzo di bind, rispettivamente.
Questi argomenti saranno impostati dalla unit systemd in funzione del file di configurazione precedentemente illustrato.
Systemd unit
Per configurare la unit systemd, copiare il contenuto seguente nel file /etc/systemd/system/keycloak.service
:
[Unit]
Description=Keycloak Identity Provider
After=syslog.target network.target postgresql.service
Before=nginx.service
[Service]
Environment=LAUNCH_JBOSS_IN_BACKGROUND=1
EnvironmentFile=-/etc/keycloak/keycloak.conf
User=keycloak
LimitNOFILE=102642
PIDFile=/var/run/keycloak/keycloak.pid
ExecStart=/home/wildfly/keycloak-15.0.2/bin/launch.sh $KEYCLOAK_MODE $KEYCLOAK_CONFIG $KEYCLOAK_BIND
StandardOutput=null
[Install]
WantedBy=multi-user.target
A questo punto è necessario eseguire il seguente comando per informare systemd della presenza della nuova service unit: sudo systemctl daemon-reload
Infine, per avviare il servizio è sufficiente eseguire il comando: sudo systemctl start keycloak
Per fare in modo che il servizio venga avviato automaticamente all’avvio del sistema operativo, eseguire: sudo systemctl enable keycloak.service
Suggerimento: per semplificare i percorsi ed evitare di dover aggiornare di volta in volta gli script ed i file di configurazione, conviene creare un link simbolico alla versione corrente di keycloak nel seguente modo:
# Dalla directory home di keycloak (/home/wildfly)
ln -s keycloak-15.0.2 keycloak
In questo modo si potrà usare il percorso /home/wildfly/keycloak
al posto di /home/wildfly/keycloak-15.0.2
.
Nel momento in cui si dovesse passare a una nuova versione di keycloak, basterà aggiornare il link simbolico per farlo puntare alla nuova installazione.