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 ( plus ou moins complexes selon votre niveau de connaissance en sécurité) d’authentification, 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 de nombreuses 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 RedHat
  • développé en java
  • 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 à la mise en place de ses connecteurs applicatifs.

FICHE TECHNIQUE

Keycloak : 3.3.0.Final

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)

Téléchargement de Keycloak

Local
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://downloads.jboss.org/keycloak/3.3.0.Final/keycloak-3.3.0.Final.tar.gz
# untar binaries into /opt
tar -xvf keycloak-3.3.0.Final.tar.gz -C /opt/

Configuration de la base de données de Keycloak

Référencehttp://www.keycloak.org/docs/latest/server_installation/index.html#_database

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 :

Capture d’écran 2017-11-02 à 15.17.22

notre utilisateur postgres est postgres

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 : http://www.keycloak.org/docs/latest/server_installation/index.html#package-the-jdbc-driver

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-3.3.0.Final/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-3.3.0.Final/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-3.3.0.Final/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érencehttp://www.keycloak.org/docs/latest/server_installation/index.html#declare-and-load-jdbc-driver

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 après 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-3.3.0.Final/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

<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.
Nous allons une nouvelle fois éditer 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}"/>

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 : http://www.keycloak.org/docs/latest/server_admin/index.html#server-initialization

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-3.3.0.Final/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 '/opt/keycloak-3.3.0.Final/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 sélectionné) 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-3.3.0.Final/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-3.3.0.Final/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
12:03:15,694 INFO  [org.jboss.as] (Controller Boot Thread) WFLYSRV0025: Keycloak 3.3.0.Final (WildFly Core 3.0.8.Final) started in 28348ms - Started 535 of 857 services (570 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.

Série d’articles Keycloak :