Securisez vos APIs Spring avec Keycloak : #1 - Installation de Keycloak

Chez Ineat, nous développons (entre autres) des applications B2C, nécessitant la mise en place de mécanismes d’authentification et d’autorisations robustes. Depuis quelques années déjà, les termes OAuth et OpenID sont couramment cités dans ce genre de contexte.

Derrière ces termes, se cachent des notions de protocoles d’authentification ( plus ou moins complexes selon votre niveau de connaissance en sécurité), qui présentent de vastes spécifications permettant leurs implémentations.

A quoi bon implémenter from-scratch ces spécifications (souvent mal comprises – donc mal implémentées, au passage) lorsqu’il existe des solutions open-source offrant des authentifications basées sur ces spécifications (et qui nous éviteront des failles) ?

Quelques solutions open-source :
WSO2 / OpenAM / Keycloak
Il existe bien sûr des solutions SAAS performantes et complètes comme Auth0 ou AWS Cognito mais il y a parfois des considérations de prix, d’hébergement et des contextes clients qui ne nous permettent pas d’utiliser tout ou partie de ces solutions cloud.

Comme le titre de ce post vous l’indique, nous avons sélectionné Keycloak parmi ces Identity/Access Manager Open source.

En voici les principales raisons :

solution open source, évidemment
porté par RedHat / intégré dans les outils RedHat
développé en java
modulaire et extensible
proposant des connecteurs Spring Boot & Spring Security (ce qui concerne une bonne partie de nos projets Java)
communauté assez présente sur la toile

Cette article est le premier d’une série, qui vous permettra de mettre en place la solution Keycloak, de son installation jusqu’au déploiement de ses connecteurs applicatifs.

FICHE TECHNIQUE
Keycloak : 12.0.2
Linux : CentOS Linux release 7.3.1611
Postgres : 9.2.23

Cet article/tutoriel présentera deux modes opératoires :

un MOP d’installation local – permettant de mettre en place Keycloak sur vos postes (cette installation nous servira pour les articles suivants)
un MOP d’installation sur un environnement externe (hors-production)

Vous pouvez utiliser le CLI Jboss pour automatiser l’installation de Keycloak avec du Ansible par exemple

Téléchargement de Keycloak

Local

Rendez vous sur la page de téléchargement de Keycloak
Récupérer la version Standalone server distribution
Décompresser cette version dans votre répertoire de travail

Externe

(Une fois connecté sur votre machine en super-user)

Parti-pris : L’installation de nos outils s’effectue sous /opt/

# download keycloak
wget https://github.com/keycloak/keycloak/releases/download/12.0.2/keycloak-12.0.2.tar.gz
# untar binaries into /opt
tar -xvf keycloak-12.0.2.tar.gz -C /opt/

Configuration de la base de données de Keycloak

Référence : Documentation officielle

Local

En local, la base de données embarquée de Keycloak (H2) suffit. Inutile d’utiliser un SGBD externe.

Externe

De manière générale, il est conseillé (voire même obligatoire) de ne pas utiliser de SGBD in-memory (H2 ici) sur vos environnements hors-dev. Nous allons donc utiliser une base de données externe (postgres 9.2.23, intégrée à notre distribution CentOs) avec notre installation de Keycloak.

Voici la checklist d’installation issue de la documentation Keycloak :

notre utilisateur postgres est postgres

1. Création de la BDD pour Keycloak

# login with postgres user
su - postgres
# create user keycloak
CREATE USER keycloak WITH PASSWORD 'keycloak';
# create db keycloak
CREATE DATABASE keycloak WITH OWNER = keycloak ENCODING = 'UTF8' TABLESPACE = pg_default CONNECTION LIMIT = -1;
# quit psql client to continue
\q

NOTE : Pensez à repasser en super-user à votre sortie du client psql

2. Installer le driver postgres (module) sous Keycloak

Référence : Documentation officielle

Comme l’énonce la documentation Keycloak, il est nécessaire de créer une arborescence pour le driver sous /modules avant de l’y déposer (items 1 & 2 de la checklist) :

# create module directories
mkdir -p /opt/keycloak-12.0.2/modules/system/layers/keycloak/org/postgresql/main
# download and copy driver into directory
wget https://jdbc.postgresql.org/download/postgresql-9.2-1004.jdbc41.jar -P /opt/keycloak-12.0.2/modules/system/layers/keycloak/org/postgresql/main

NOTE : L’option -P de wget permet de spécifier le dossier de réception.

Il est maintenant nécessaire de déclarer le driver en tant que module de Keycloak pour qu’il soit exploitable :

touch /opt/keycloak-12.0.2/modules/system/layers/keycloak/org/postgresql/main/module.xml

Editer le fichier et y copier/coller ce bloc xml :

<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.3" name="org.postgresql">


    <resources>
        <resource-root path="postgresql-9.2-1004.jdbc41.jar" />
    </resources>

    <dependencies>
        <module name="javax.api"/>
        <module name="javax.transaction.api"/>
    </dependencies>
</module>

NOTE : l’attribut path du noeud resource-root cible le driver que nous avons précédemment téléchargé. Adaptez la valeur en fonction de la version de votre SGBD.

3. Déclaration et chargement du driver

Référence : Documentation officielle

Pour les besoins du tutoriel, nous utiliserons la version standalone de Keycloak. Sachez qu’il est possible d’utiliser Keycloak en mode cluster. Ajouter la configuration ci-dessous dans le fichier de configuration Keycloak adapté au mode utilisé.

L’ensemble du paramétrage de Keycloak se trouve dans le fichier standalone.xml. C’est ce fichier qu’il vous faut éditer si vous souhaitez modifier les informations de connexion à la BDD Keycloak, le port HTTP de lancement du serveur, etc.

vim /opt/keycloak-12.0.2/standalone/configuration/standalone.xml

Ajouter le bloc ci-aprés dans le noeud drivers :

<driver name="postgresql" module="org.postgresql">
  <xa-datasource-class>org.postgresql.xa.PGXADataSource</xa-datasource-class>
</driver>

Il est ensuite nécessaire de modifier la configuration existante de connexion à la BDD Keycloak :

Remplacer (ou commenter) le bloc suivant :

<datasource jndi-name="java:jboss/datasources/KeycloakDS" pool-name="KeycloakDS" enabled="true" use-java-context="true">
  <connection-url>jdbc:h2:${jboss.server.data.dir}/keycloak;AUTO_SERVER=TRUE</connection-url>
  <driver>h2</driver>
  <security>
    <user-name>sa</user-name>
    <password>sa</password>
  </security>
</datasource>

par celui ci :

<datasource jndi-name="java:jboss/datasources/KeycloakDS" pool-name="KeycloakDS" enabled="true" use-java-context="true">
  <connection-url>jdbc:postgresql://localhost:5432/keycloak</connection-url>
  <driver>postgresql</driver>
  <pool>
    <max-pool-size>20</max-pool-size>
  </pool>
  <security>
    <user-name>keycloak</user-name>
    <password>keycloak</password>
  </security>
</datasource>

Ligne 2 : Les informations de connexion à la base de données. Ici, postgres et keycloak sont mutualisés sur la même machine (localhost)
Ligne 3 : Cible le driver précédemment déclaré
Ligne 7 : Identifiants de l’utilisateur associé à la base keycloak

Et voilà, notre instance Keycloak est configurée pour utiliser notre SGBD postgres.

Nous avons quasiment terminé …

Avant de pouvoir (enfin) démarrer Keycloak, il nous reste des petits détails à régler

1. Changer le port de démarrage

Local / Externe

Il est judicieux de changer le port HTTP de démarrage de Wildfly pour éviter des conflits de ports avec vos applications.

Soit vous souhaitez changer le port de démarrage par défaut :

Editer le fichier standalone.xml
Rechercher :8080
Modifier cette valeur (j’ai choisi de remplacer la valeur par :8180 )

<socket-binding name="http" port="${jboss.http.port:8180}"/>

Soit vous démarrez le serveur grâce à l’option jboss.http.port(conseillé) :

standalone.sh -Djboss.http.port=8081

2. Créer l’utilisateur par défaut (admin)

Avant de pouvoir utiliser Keycloak, il est nécessaire de créer un compte administrateur.

Référence : Documentation officielle

Local

Utiliser l’assistant Keycloak en vous connectant sur http://localhost:8180/auth (après avoir démarré le serveur ;))

Local / Externe

Vous pouvez aussi utiliser le script add-user-keycloak fournit par Keycloak sous /bin (en .sh ou .bat dépendant de votre OS)

/opt/keycloak-12.0.2/bin/add-user-keycloak.sh -r master -u admin -p password

l’option -r permet de préciser le domaine maitre (ici: master)
l’option -u permet de spécifier le nom de l’utilisateur admin (ici: admin)
l’option -p permet de préciser le mot de passe de l’utilisateur (ici: password)

NOTE: Si l’opération se passe bien, vous devriez voir ce message apparaitre :

Added 'admin' to 'https://d3uyj2gj5wa63n.cloudfront.net/opt/keycloak-12.0.2/standalone/configuration/keycloak-add-user.json', restart server to load user

3. Exposer la web-ui

Local

Aucune action à prévoir en local

Externe

Si vous voulez rendre disponible la web-ui Keycloak, il est nécessaire d’exposer le port 8180 (ou celui que vous avez défini) sur votre serveur.

Voici la commande CentOs à exécuter :

sudo iptables -I INPUT 1 -m tcp -p tcp --dport 8180 -j ACCEPT

NOTE: Redémarrer votre serveur effacera cette commande.
Vous avez toujours la possibilité de rendre permanente cette ouverture de port (topic StackOverflow) :

firewall-cmd --permanent --zone=public --add-port=8180/tcp

Si vous souhaitez déclarer Keycloak en mode service, la procédure est
disponible sous /opt/keycloak-9.0.0/docs/contrib/scripts à travers un README.md

Démarrer Keycloak

Pour démarrer Keycloak, exécuter le script standalone(.sh) dans le répertoire /bin :

Local / Externe

/opt/keycloak-12.0.2/bin/standalone.sh -b 0.0.0.0 -Djboss.bind.address=0.0.0.0 -Djboss.bind.address.management=0.0.0.0

Les logs de démarrage de votre serveur devrait vous indiquer le démarrage du service :

12:03:15,693 INFO [org.jboss.as] (Controller Boot Thread) WFLYSRV0060: Http management interface listening on http://127.0.0.1:9990/management
12:03:15,694 INFO [org.jboss.as] (Controller Boot Thread) WFLYSRV0051: Admin console listening on http://127.0.0.1:9990
15:05:37,398 INFO [org.jboss.as] (Controller Boot Thread) WFLYSRV0025: Keycloak 9.0.0 (WildFly Core 10.0.3.Final) started in 14436ms - Started 546 of 882 services (604 services are lazy, passive or on-demand)

Félicitation, votre installation de Keycloak est terminée.

Dans l’article suivant, nous allons configurer notre premier domaine (realm) Keycloak permettant la sécurisation d’un backend d’API REST.

N’hésitez pas à me laisser vos feedbacks en commentaires de cet article.

Édité le 05/02/2021 pour un passage en Keycloak 12.0.2

Série d’articles Keycloak :

Partie 1 : Vous le consultez actuellement
Partie 2 : Configuration d’un domaine applicatif
Partie 3 : Sécurisation d’un backend d’API Spring avec Keycloak
Partie 4 : Utilisation du connecteur Keycloak.js avec Angular6+
Partie 5 : Sécuriser une API multi-tenant avec Keycloak

Securisez vos APIs Spring avec Keycloak : #1 – Installation de Keycloak

Téléchargement de Keycloak

Local

Externe

Configuration de la base de données de Keycloak

Local

Externe

1. Création de la BDD pour Keycloak

2. Installer le driver postgres (module) sous Keycloak

3. Déclaration et chargement du driver

Nous avons quasiment terminé …

1. Changer le port de démarrage

Local / Externe

2. Créer l’utilisateur par défaut (admin)

Local

Local / Externe

3. Exposer la web-ui

Local

Externe

Démarrer Keycloak

Local / Externe

Série d’articles Keycloak :

Vous pouvez aussi aimer

Spring Cloud : partie 2 – Définition du point d’entrée et externalisation des configurations

PHP Fibers, l’asynchrone au bout de la trompe