Découverte de Keycloak : installation d’une solution IAM avec Docker

I. Présentation

La gestion des identités et des accès est devenue une composante essentielle dans les environnements informatiques modernes, notamment pour l'accès aux applications web et aux API. Pour répondre à ce besoin, il existe différentes solutions sur le marché. Aujourd'hui, nous allons voir comment installer Keycloak, une solution de gestion des identités open source.

Nous commencerons par une présentation de Keycloak, en évoquant notamment les protocoles pris en charge et quelques cas d'usage, avant de se pencher sur l'installation. Plusieurs méthodes d'installation sont disponibles, mais dans le cas présent, nous partirons sur un déploiement basé sur Docker.

II. Keycloak, c'est quoi ?

Les services numériques sont omniprésents dans les entreprises, il devient donc rapidement indispensable de disposer d'une solution centralisée pour authentifier les utilisateurs et attribuer les bons droits d'accès aux ressources. C'est précisément le rôle de Keycloak, une solution open source qui permet de mettre en place facilement une gestion des identités et des accès (IAM). Cette solution représente une alternative à d'autres solutions comme Microsoft Entra ID, et même l'Active Directory.

Initialement développé par Red Hat depuis 2014, le projet Keycloak est désormais un peu plus indépendant puisque Red Hat développe aussi un autre projet basé sur Keycloak : Red Hat SSO. Il permet aux développeurs d'ajouter rapidement des fonctionnalités d'authentification et d'autorisation à leurs applications, tout en s’appuyant sur des standards ouverts et la fédération des identités. Actuellement, Keycloak est distribué sous licence Apache version 2.0.

Keycloak prend en charge l’authentification unique (SSO - Single Sign-On), la gestion des utilisateurs, l’autorisation basée sur les rôles (RBAC), l’authentification à double facteur (2FA) et la fédération avec des fournisseurs d’identité externes (comme Google, Microsoft, GitHub, GitLab, LDAP, etc.).

• Site du projet Keycloak
• GitHub de Keycloak

A. Protocoles pris en charge

Pour assurer la compatibilité avec divers systèmes, Keycloak prend en charge plusieurs protocoles et normes :

• OpenID Connect (OIDC) : une couche d'identification basée sur OAuth 2.0.
• OAuth 2.0 : délégation d’accès entre applications, c'est un protocole d'autorisation.
• SAML 2.0 : une norme utilisée pour l'authentification unique (SSO) entre plusieurs domaines.
• LDAP et Kerberos : pour l’intégration avec des annuaires d’entreprise existants, comme Active Directory

Si vous avez l'habitude d'utiliser des solutions d'IAM, vous avez forcément déjà entendu parler de ces termes. Keycloak est une solution adaptée aux besoins modernes en matière d'authentification.

B. Cas d'usage

Parmi les cas d’usage les plus fréquents de Keycloak, on peut citer :

• Authentifier les utilisateurs sur un portail web avec possibilité de connexion via un compte Google ou Microsoft.
• Sécuriser l’accès à des API en utilisant des tokens OAuth2.
• Intégrer l’authentification d'une application interne avec un annuaire LDAP d’entreprise.
• Offrir un service d'authentification centralisé pour un ensemble d'applications web utilisées par une entreprise.

En tant que citoyen français, vous utilisez peut-être régulièrement OpenID Connect par l'intermédiaire du mécanisme FranceConnect. Par exemple, c'est grâce à lui que vous pouvez accéder à votre compte CAF à partir de vos identifiants du site des Impôts.

C. Les différentes façons d'installer Keycloak

La documentation de Keycloak est relativement exhaustive sur les méthodes d’installation disponibles. La solution peut s'adapter à différents besoins et environnement d’exécution :

• Installation manuelle (et autonome) : téléchargement du binaire depuis le site officiel, avec configuration sur une machine physique ou virtuelle.
• Conteneurisation avec Docker ou Podman : facilite le déploiement rapide, autant dans des environnements de test que de production.
• Déploiement dans Kubernetes ou OpenShift : un déploiement facilement scalable et orchestrable.
• Installation automatisée via des outils comme Ansible : pour les adeptes d’Infrastructure as Code.

Dans ce tutoriel, nous allons opter pour l’installation de Keycloak via Docker, où l'instance sera associée à PostgreSQL pour refléter un déploiement tel qu'on peut en trouver en production. D'autres moteurs de base de données sont pris en charge (voir cette page).

III. Installation de Keycloak avec Docker

Avant de commencer, assurez-vous que Docker est installé et en fonctionnement sur votre machine. Pour ma part, je vais utiliser une machine sous Debian 13 sur laquelle Docker a été installé (ce n'est qu'un exemple, vous pouvez utiliser un autre système). Si vous avez besoin d'aide pour l'installation, suivez ce tutoriel :

• Tutoriel - Installation de Docker sur Debian

Quand c'est fait, vous pouvez envisager le déploiement d'une instance Keycloak à l’aide de Docker.

A. Créer l'arborescence de répertoires

Nous allons commencer par créer un dossier dans lequel seront stockées les données du projet :

sudo mkdir /opt/docker-compose/keycloak

Dans le répertoire /opt/docker-compose/keycloak, créez les sous-dossiers suivants :

• certs : il contiendra le certificat TLS et la clé privée pour sécuriser les connexions à l'interface web (HTTPS).
• postgresql : il contiendra les données de PostgreSQL, le moteur de base de données qui sera lié à Keycloak.

La structure finale attendue, en tenant compte des futurs fichiers que nous allons créer, est la suivante :

keycloak/
├── certs
│   ├── tls.crt
│   └── tls.key
├── docker-compose.yml
├── .env
└── postgresql

B. Le fichier Docker Compose pour Keycloak

Notre déploiement de Keycloak repose sur deux conteneurs : l'application Keycloak en elle-même et PostgreSQL pour la base de données. Ces deux conteneurs seront connectés sur le même réseau et Keycloak est dépendant du bon fonctionnement du second conteneur.

Créez le fichier Docker Compose à la racine du projet (soit dans le dossier /opt/docker-compose/keycloak) :

sudo nano docker-compose.yml

Dans ce fichier, ajoutez le contenu suivant :

services:
  keycloak:
    container_name: keycloak_app
    image: quay.io/keycloak/keycloak:latest
    restart: always
    environment:
      KEYCLOAK_ADMIN: ${KEYCLOAK_USER}
      KEYCLOAK_ADMIN_PASSWORD: ${KEYCLOAK_PASSWORD}
      KC_HOSTNAME: ${KEYCLOAK_URL}
      KC_DB: postgres
      KC_DB_USERNAME: ${POSTGRES_USER}
      KC_DB_PASSWORD: ${POSTGRES_PASSWORD}
      KC_DB_URL_HOST: keycloak_postgres
      KC_DB_URL_DATABASE: keycloak
      KC_HTTPS_CERTIFICATE_FILE: /etc/x509/https/tls.crt
      KC_HTTPS_CERTIFICATE_KEY_FILE: /etc/x509/https/tls.key
    volumes:
      - ./certs:/etc/x509/https
    depends_on:
      keycloak_postgres:
        condition: service_healthy
    ports:
      - "8080:8080"
      - "8443:8443"
    networks:
      - keycloak-network
    command:
      - start

  keycloak_postgres:
    container_name: keycloak_postgres
    image: postgres:17
    restart: always
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - ./postgresql:/var/lib/postgresql/data
    networks:
      - keycloak-network
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d keycloak"]
      interval: 10s
      timeout: 5s
      retries: 5

networks:
  keycloak-network:
    name: keycloak-network
    driver: bridge

Quelques explications au sujet du contenu de ce fichier.

La première partie déclare le service keycloak, avec un conteneur qui sera nommé keycloak_app :

• Différentes variables d'environnement sont définies sous environment. Certaines d'elles seront par la suite dans un fichier .env, ce qui facilite le partage de valeurs entre plusieurs conteneurs (ce qui limite les risques d'erreurs liées à la cohérence des valeurs).
• KC_HTTPS_CERTIFICATE_FILE: /etc/x509/https/tls.crt : nom du fichier correspondant au certificat TLS (accès HTTPS).
• KC_HTTPS_CERTIFICATE_KEY_FILE: /etc/x509/https/tls.key : nom du fichier correspondant à la clé privée associée au certificat.
• ./certs:/etc/x509/https : le répertoire certs situé à la racine du projet sera mappé dans le conteneur. Ceci permet de pousser les fichiers du certificat dans le conteneur facilement.
• La section ports indique que le conteneur sera exposé sur deux ports : 8080 pour l'accès HTTP (on pourrait même s'en passer) et 8443 pour l'accès HTTPS.

La deuxième partie déclare le service keycloak_postgres, avec un conteneur qui sera nommé keycloak_postgres :

• Deux variables d'environnement sont définies sous environment, pour préciser le nom d'utilisateur et le mot de passe de connexion à l'instance. Ces valeurs seront définies dans le fichier .env.
• ./postgresql:/var/lib/postgresql/data : le répertoire postgresql situé à la racine du projet sera mappé dans le conteneur. Il assure la persistance des données liées à la base de données, et donc, notre application.

Enregistrez et fermez ce fichier.

C. Configurer les variables d'environnement

Créez le fichier avec les variables d'environnement à la racine du projet (soit dans le dossier /opt/docker-compose/keycloak) :

sudo nano .env

Ce fichier contient 5 variables d'environnement différentes :

KEYCLOAK_USER=admin
KEYCLOAK_PASSWORD=P@ssword!
KEYCLOAK_URL=keycloak.it-connect.local
POSTGRES_USER=postgres
POSTGRES_PASSWORD=Postgres@IT-2025

Voici l'utilité de ces variables que vous devez personnaliser :

• KEYCLOAK_USER : identifiant de l’administrateur temporaire créé lors de l'installation.
• KEYCLOAK_PASSWORD : mot de passe de l’administrateur temporaire.
• KEYCLOAK_URL : URL d'accès à l'application Keycloak, ici, ce sera https://keycloak.it-connect.local:8443, donc je précise keycloak.it-connect.local.
• POSTGRES_USER : nom de l'utilisateur pour se connecter à la base de données PostgreSQL.
• POSTGRES_PASSWORD : mot de passe de l'utilisateur PostgreSQL.

Une fois les valeurs personnalisées, enregistrez et fermez ce fichier.

D. Le certificat TLS pour Keycloak

Pour le certificat TLS, c'est toujours pareil, vous disposez de plusieurs options : auto-signé, émis par une CA d'entreprise, obtenu via Let's Encrypt ou une autre CA publique. Ici, nous choisirons l'option qui crée le moins de dépendances et qui est adaptée aux tests : le certificat auto-signé.

Positionnez-vous dans le répertoire /opt/docker-compose/keycloak/certs et exécutez cette commande :

sudo openssl req -x509 -nodes -days 365 -newkey rsa:4096 -keyout tls.key -out tls.crt

Renseignez le formulaire : plus c'est complet, mieux c'est. Mais, à minima, faites l'effort de préciser le nom du serveur pour le Common Name.

Suite à l'exécution de cette commande, vous obtenez deux fichiers :

• tls.crt : le certificat TLS
• tls.key : la clé privée associée.

Ces deux noms devraient vous rappeler quelque chose si vous avez lu l'intégralité de cet article. Pour éviter les problèmes d'accès, ajustez les permissions sur les fichiers (droits de lecture) :

sudo chmod +r certs/tls.*

Sinon, le conteneur Keycloak ne pourra pas lire la clé privée et il retournera une erreur comme celle-ci : "ERROR org.keycloak.quarkus.runtime.cli.ExecutionExceptionHandler ERROR: /etc/x509/https/tls.key".

E. Lancer la construction du projet

Tout est prêt, nous pouvons envisager le lancement du projet avec Docker ! Il va télécharger les images et construire les conteneurs ! Positionnez-vous à la racine du projet et lancez cette commande :

sudo docker compose up -d

Une fois les deux conteneurs lancés, vous devriez les voir dans la liste des conteneurs de votre machine (sauf s'il y a un conflit sur un numéro de port, par exemple).

sudo docker ps

Vous pouvez aussi afficher les journaux des conteneurs de votre projet via la commande indiquée ci-dessous. C'est un bon moyen de voir si tout se déroule bien ou non.

sudo docker compose logs -f --tail 100

Quelques minutes plus tard, vous devriez avoir accès à l'interface web de Keycloak : https://keycloak.it-connect.local:8443. Un avertissement apparaît, mais c'est normal, car le certificat est auto-signé.

IV. Prise en main de l’interface de Keycloak

A. Connexion à l’interface d’administration

Utilisez les identifiants spécifiés dans le fichier .env pour vous connecter à la console d’administration de Keycloak. Pour ma part, ce sera donc le couple admin/P@ssword!.

Lors de la première connexion, une bannière d'avertissement est visible : You are logged in as a temporary admin user. Ce compte administrateur est temporaire, il est donc essentiel de créer un nouveau compte administrateur "définitif" et supprimer celui-ci.

Sur la gauche, dans le menu, cliquez sur "Users" puis sur le bouton "Add user". À noter ici que nous sommes dans le realm "master" : nous reviendrons sur cette notion essentielle par la suite.

Définissez les propriétés de ce compte, notamment le nom d'utilisateur, comme ici adm_itconnect. Validez la création du compte. D'une façon générale, chaque utilisateur dispose de plusieurs attributs (nom, prénom, e-mail, etc.) et peut-être membre d'un ou plusieurs groupes.

Pour le moment, notre nouveau compte n'a pas de mot de passe ! Bénéficiez sur l'onglet "Credentials" puis cliquez sur le bouton "Set password" pour définir le mot de passe de ce compte.

Saisissez le mot de passe du compte, deux fois. Décochez l'option "Temporary" pour que ce mot de passe n'expire pas automatiquement.

Une dernière étape doit être accomplie : associer le rôle "admin" à ce compte. Effectuez l'attribution de ce rôle via l'onglet "Role mapping" disponible sur la fiche de cet utilisateur.

Voilà, le nouveau compte administrateur a été créé ! Désormais, il est recommandé de se déconnecter pour se reconnecter avec ce compte. L'utilisateur créé initialement peut être supprimé dès maintenant.

Note : nous venons de voir comment créer un utilisateur manuellement. Pour aller plus loin, vous pouvez aussi effectuer cette action par l'intermédiaire de l'API ou les importer depuis un fournisseur d'identité externe comme un annuaire LDAP.

B. Les realms (royaumes)

Un realm est un espace de gestion indépendant dans Keycloak. Chaque realm dispose de ses propres utilisateurs, clients, rôles, etc. Cela permet de compartimenter les configurations, par exemple :

• Un realm pour les utilisateurs internes.
• Un autre pour des applications destinées à des clients externes.

À l’installation, un realm par défaut nommé "master" est présent (avec le nom d'affichage "Keycloak"). Il est réservé à l’administration de Keycloak lui-même. De ce fait, il est déconseillé de créer des utilisateurs destinés à s'authentifier sur d'autres applications dans ce realm. Pour respecter cette bonne pratique, vous serez donc rapidement amené à cliquer sur le bouton "Create realm" pour créer un nouveau realm sur votre instance Keycloak.

C. Les clients

Les clients, à ne pas confondre avec les utilisateurs, représentent les applications qui utilisent Keycloak pour authentifier leurs utilisateurs. Les exemples sont divers et variés, en voici quelques-uns :

• Applications web,
• API sécurisées,
• Applications mobiles ou desktop

La configuration de chaque client doit faire référence à plusieurs propriétés, notamment le protocole utilisé (OIDC ou SAML), l’URL de redirection, les rôles et les permissions associés.

V. Conclusion

L'instance Keycloak est désormais opérationnelle : il ne reste plus qu'à aller plus loin dans la configuration avec l'intégration d'un client, c'est-à-dire une application externe, et la mise en place d'un premier flux d'authentification.

Nous pourrons voir Keycloak en action dans de prochains tutoriels. En attendant, je vous recommande la lecture de l'article ci-dessous où vous apprendrez à manipuler ClientFedID, un outil open source qui vous permettra de mieux appréhender les mécanismes d'authentification modernes. Ce sera l'occasion de lui associer le rôle de client et de simuler une authentification !

• ClientFedID, un outil open source développé par Aduneo