Installazione Keycloak

Apr 29, 2022 | Cyber Security, News | 0 commenti

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 che mostra il primo accesso a Keycloak

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:

  1. predisporre una cartella contenente le opzioni di configurazione del servizio
  2. collocare uno script bash di avvio del servizio nella directory bin della distribuzione di keycloak
  3. 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.

Torna alle NEWS