Rédigé par : Adnene Hamdouni,

Comment installer et configurer Keycloak ?

Les jeudis pratiques sont lancés ! Chaque semaine, retrouvez sur notre blog un article dédié à notre série « Guide pratique pour sécuriser une application Java Spring Boot et maîtriser son déploiement dans le Cloud AWS ». L’objectif est de réaliser, pas à pas, la configuration d’un environnement sécurisé, la création d’une API et in fine, son déploiement dans le cloud.

Sommaire

Photo de profil Linkedin de Yassine Nefari, en couleur, consultant Data Engineer Azure TECOS

Rédigé par : Adnene Hamdouni,

Icon linkedIn
Icone Github

Catégorie : Les jeudis pratiques

Ne manquez
aucun épisode

Introduction

Dans les bonnes pratiques, le développement d’applications sécurisées repose avant toute chose sur la mise en place d’une solution d’authentification fiable et robuste. En ce sens, les premières étapes de sécurisation d’une application (et par rapport à notre cas d’usage), consistent à installer et configurer Keycloak.

Dans cet article, nous aborderons en détail ces étapes en utilisant OAuth2 et OpenID Connect (OIDC) pour la configuration initiale de Keycloak. À noter que cette base servira de point de départ pour l’épisode suivant, dans lequel nous verrons comment utiliser Keycloak pour sécuriser une application Spring Boot à l’aide de requêtes d’authentification testées avec Postman.

Prérequis

  • Java JDK 17 ou supérieur
  • Docker Desktop
  • Keycloak 12.0.4 ou supérieur
  • Postman pour tester les requêtes d’authentification

Installer l’environnement de développement

1. Java JDK 17

En premier lieu, assurez-vous que Java JDK 17 est installé sur votre machine. Vous pouvez télécharger le JDK depuis le site officiel d’Oracle ou adopter une distribution OpenJDK. Pour vérifier votre installation, ouvrez un terminal et tapez :

java -version

2. IntelliJ IDEA

Téléchargez et installez ensuite IntelliJ IDEA depuis le site officiel. La version Community est gratuite et sera suffisante pour ce projet.

Installer et configurer Docker

Pour assurer une implémentation réussie de l’authentification OAuth2 et OpenID avec Keycloak et Spring Security, il est crucial de débuter par la mise en place d’un environnement Docker. Docker est une plateforme de conteneurisation qui permet d’encapsuler l’application et ses dépendances dans un conteneur isolé. Cela garantit que l’application s’exécute de manière uniforme dans n’importe quel environnement de développement, de test ou de production.

1. Pourquoi Docker ?

  • Isolation : chaque conteneur fonctionne de manière isolée, ce qui réduit les conflits entre les applications.
  • Portabilité : les conteneurs peuvent être déployés sur n’importe quel système prenant en charge Docker. Cela facilite le déploiement et le scaling.
  • Reproductibilité : les environnements de développement, de test et de production sont identiques, ce qui réduit les “ça marche sur ma machine”.

2. Installation de Docker

L’installation de Docker varie en fonction du système d’exploitation :

Sur Windows
  • Télécharger Docker Desktop : visitez Docker Hub et téléchargez Docker Desktop pour Windows.
  • Installation : exécutez ensuite le fichier d’installation et suivez les instructions à l’écran. Redémarrez votre ordinateur si nécessaire.
  • Vérification : pour finir, ouvrez un terminal et tapez la commande suivante pour vérifier l’installation :

docker –version

Sur Mac
  • Télécharger Docker Desktop : visitez Docker Hub et téléchargez Docker Desktop pour Mac.
  • Installation : ouvrez le fichier .dmg et glissez l’icône Docker dans le dossier Applications.
  • Vérification : ouvrez un terminal et vérifiez l’installation avec :

docker –version

Sur Linux
  • Mise à jour du système :

sudo apt-get update

  • Installation des prérequis :

sudo apt-get install apt-transport-https ca-certificates curl software-properties-common

  • Ajout du repository Docker :

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add – sudo add-apt-repository « deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable »

  • Installation de Docker :

sudo apt-get update && sudo apt-get install docker-ce

  • Vérification de la version de Docker :

docker –version

3. Tester docker

Pour confirmer que Docker est installé et fonctionne correctement, exécutez :

docker run hello-world

Cette commande télécharge une image de test et exécute un conteneur qui affiche un message de bienvenue. Si vous voyez ce message, cela signifie que Docker est correctement installé et configuré sur votre machine.

test docker, exemple d'image "Hello World"

Exemple d’image “Hello World”

Avoir Docker installé et configuré correctement est la première étape pour déployer des applications conteneurisées. Cela vous prépare à l’installation de Keycloak dans un environnement Dockerisé, ce qui facilite la gestion de l’authentification et de l’autorisation dans les applications Spring Boot.

Installer et configurer Keycloak

Pour intégrer l’authentification et l’autorisation dans nos applications en utilisant Keycloak avec OAuth2 et OpenID, nous devons d’abord configurer Keycloak. Une manière efficace et isolée de le faire est d’utiliser Docker Compose, qui nous permet de déployer Keycloak dans un conteneur Docker.

1. Avantages de Docker Compose

  • Simplicité : Docker Compose facilite le démarrage de plusieurs conteneurs Docker comme un service unique.
  • Configuration via Code : toute la configuration est gérée à travers un fichier YAML. Cela rend le déploiement reproductible et facile à versionner.
  • Isolation : chaque service s’exécute dans son propre conteneur, ce qui assure l’isolation et la sécurité entre services.

2. Configurer Keycloak

Commencez par installer et lancer Keycloak. Créez ensuite un Realm et un client. Notez bien les identifiants du client et le secret. Ils seront utilisés dans la configuration de Spring Boot.

Étape 1 : création du fichier Docker Compose

Créez un dossier pour votre projet Keycloak :

mkdir keycloak_project && cd keycloak_project

Ensuite, créez un fichier docker-compose.yml : ce fichier contiendra la configuration nécessaire pour exécuter Keycloak.

capture d'écran, Exemple de configuration keycloak via docker-compose

Exemple de configuration Keycloak via Docker Compose

Ce fichier définit deux services : keycloak et db. Keycloak dépend de db, un service de base de données PostgreSQL configuré pour stocker les données de Keycloak.

Étape 2 : lancez Keycloak

Après avoir créé votre fichier docker-compose.yml, vous pouvez démarrer Keycloak en exécutant :

docker-compose up -d

Cette commande lance les conteneurs en arrière-plan. Keycloak sera accessible via http://localhost:8180.

Étape 3 : configuration initiale de Keycloak

Accédez à Keycloak : ouvrez votre navigateur et allez à http://localhost:8180/auth

configuration keycloak, interface de connexion à Keycloak

Interface de connexion à Keycloak

Connectez-vous au panneau d’administration : utilisez les identifiants qui sont définis dans le docker-compose pour accéder à l’interface d’administration de Keycloak. Dans notre exemple :

User : admin / Password : Pa55w0rd

Étape 4 : création d’un nouveau Realm

Créez un Realm : lancez Keycloak et créez un nouveau Realm. Un realm dans Keycloak représente un espace isolé où vous pouvez gérer vos utilisateurs, crédentials, rôles, et groupes.

configuration Keycloak, création d'un nouveau realm

Création d’un nouveau Realm

Ajoutez un nom pour le realm (ex. Keycloak_springboot) :

configurer Keycloak, définition du nom du Realm

Définition du nom du Realm

Étape 5 : création et configuration d’un nouveau client

Configurez un client : les clients sont des entités qui peuvent demander l’authentification d’un utilisateur. Pour une application Spring Boot, la configuration d’un client s’effectue avec le protocole openid-connect.

configurer Keycloak, création d'un Realm

Création d’un Realm

Sous ce Realm, créez un client (ex. springboot-openid-client-app) et configurez-le pour l’authentification OAuth2/OpenID.

  • Allez à Clients > Create : dans le panneau d’administration de Keycloak.
  • Entrez les informations de base : comme le Client ID et Root URL.
  • Configurez les paramètres OIDC : tels que les Valid Redirect URIs et autres paramètres selon vos besoins.
configurer Keycloak, interface de création de nouveaux clients

Interface de création de nouveaux clients

installer et configurer keycloak, valeurs par défaut paramétrage

Valeurs par défaut de paramétrage du nouveau client

installer et configurer Keycloak, configuration de l'url de redirection

Configuration de l’url de redirection

Étape 6 : création de rôle pour le client

Ce processus est une étape fondamentale dans la gestion des droits d’accès dans Keycloak. Les rôles permettent de définir des ensembles de permissions pour les utilisateurs. Ici, nous allons voir comment le nouveau rôle est créé dans Keycloak pour notre application. Il est crucial pour gérer l’accès et les permissions au sein de l’application.

installer et configurer keycloak, étape 6, interface de création de nouveau rôle

Interface de création de nouveau rôle

Il faut savoir qu’en créant un rôle, l’administrateur prépare le système à attribuer des accès basiques. Ils seront probablement utilisés pour les nouveaux utilisateurs ou pour des utilisateurs ayant besoin de permissions standards dans l’application.

Ensuite, passons à la création d’un nouveau rôle “user” dans l’interface d’administration de Keycloak pour le ‘realm’ appelé “Keycloak_SpringBoot”.

installer et configurer keycloak, étape 6

Ajout du nom du nouveau rôle

Dans le champ “Role name”, nous pouvons voir que l’administrateur est en train de saisir le nom du nouveau rôle, ici “user”. Le champ de description est vide, ce qui suggère que l’administrateur peut choisir de fournir des détails supplémentaires sur le rôle ou de le laisser sans description.

Étape 7 : création d’un nouvel utilisateur

Dans l’univers de la gestion des identités et des accès, Keycloak se distingue comme un serveur d’identité polyvalent qui fournit une interface riche pour administrer les utilisateurs et leurs rôles au sein d’une application. La première étape de cette gestion consiste à créer un nouvel utilisateur dans Keycloak.

Étape 7, création de l'utilisateur

Création de l’utilisateur

L’image ci-dessous montre l’écran de gestion d’un utilisateur spécifique. Les détails fondamentaux tels que l’ID unique, l’adresse e-mail, la vérification de l’email, ainsi que les informations personnelles comme le prénom et le nom sont affichés et peuvent être édités.

étape 7
Ajout du nom du nouveau rôle

Chaque utilisateur peut être activé ou désactivé, permettant un contrôle de l’accès à l’application. De plus, des actions requises peuvent être assignées, poussant l’utilisateur à accomplir certaines tâches comme la confirmation de son e-mail ou la mise à jour de son mot de passe. Cette interface d’administration illustre bien la facilité avec laquelle Keycloak permet aux administrateurs de maintenir la sécurité tout en gérant efficacement les droits d’accès des utilisateurs.

Vous pouvez voir différentes informations et configurations pour un utilisateur créé dans un ‘realm’ spécifique de Keycloak, identifié ici par “Keycloak_SpringBoot”. Voici ce que nous pouvons interpréter des différents champs présents dans la capture d’écran ci-dessus :

  • ID : identifiant unique attribué à l’utilisateur au sein de Keycloak.
  • Created at : il s’agit de la date et de l’heure de la création de l’utilisateur dans le système.
  • Username : le nom d’utilisateur, utilisé pour se connecter à l’application.
  • Email : l’adresse e-mail associée à l’utilisateur. Elle peut également être utilisée pour les communications et potentiellement pour la récupération de mot de passe.
  • Email verified : cet indicateur informe si l’adresse e-mail de l’utilisateur a été vérifiée ou non.
  • First name et Last name : le prénom et le nom de l’utilisateur, utilisés pour l’identification personnelle dans l’application.
  • Enabled : il s’agit d’un commutateur qui indique si le compte de l’utilisateur est actif. Il peut aussi être utilisé pour se connecter.
  • Required user actions : actions que l’utilisateur pourrait avoir à effectuer, comme la mise à jour du mot de passe ou la vérification de l’e-mail.

Étape 8 : ajout des autorisations pour l’utilisateur

L’assignation de rôles à cet utilisateur détermine ses autorisations au sein de l’application. Il s’agit d’une étape clé dans la gestion des utilisateurs dans Keycloak.
Sur le premier écran de gestion des utilisateurs ci-dessous, nous pouvons voir qu’un utilisateur spécifique, “my-user”, n’a actuellement aucun identifiant de sécurité (ou credentials) configuré.

Étape 8, ajout des autorisations

Ajout des autorisations

C’est une page cruciale, où les administrateurs peuvent définir ou réinitialiser les mots de passe des utilisateurs. Cette étape est fondamentale afin d’assurer que l’accès à l’application soit sécurisé. Le bouton “Set password” permet d’attribuer un mot de passe à l’utilisateur. Cela renforce notamment la première ligne de défense pour la sécurité des comptes utilisateurs.

Ensuite, la seconde phase de cette huitième étape est la définition d’un mot de passe pour “my-user”.

étape 8, définition du mot de passe utilisateur

Définition du mot de passe de l’utilisateur

Ici, le formulaire est simple. Un nouveau mot de passe peut être entré et confirmé. Cela permet de s’assurer que les frappes accidentelles ne causent pas d’erreur dans la création du mot de passe. L’option “Temporary” (temporaire) est disponible, ce qui est utile dans le cas où l’administrateur souhaite que l’utilisateur change son mot de passe lors de la prochaine connexion. Cette pratique est courante lors de l’initialisation des comptes ou de la réinitialisation des mots de passe oubliés. Une fois le mot de passe défini et sauvegardé, l’utilisateur “my-user” pourra accéder aux applications protégées par Keycloak en utilisant ses nouveaux identifiants.

Étape 9 : assignation du rôle à l’utilisateur

Dans la gestion des utilisateurs de Keycloak, nous pouvons observer des éléments clés qui permettent de définir et de contrôler les rôles et les accès.
Dans l’onglet “Role Mapping”, les rôles attribués à l’utilisateur sont affichés. Il est possible d’assigner ou de retirer des rôles afin d’affiner les permissions de l’utilisateur. Par exemple, un rôle par défaut est visible mais non hérité, ce qui indique qu’il a été assigné directement plutôt que par l’intermédiaire d’un groupe ou d’un autre rôle parent.

étape 9, interface de gestion des rôles utilisateurs

Interface de gestion des rôles utilisateurs

Grâce à la boîte de dialogue “Assign roles to my-user account”, il est possible de gérer les rôles spécifiques attribués à un utilisateur. Dans l’exemple ci-dessous, l’utilisateur se voit assigner le rôle “user”, un rôle probablement destiné à l’accès général à l’application.

étape 9,assignation du rôle à l'utilisateir

Assignation du rôle à l’utilisateur

Étape 10 : modification du scope par défaut

Finalement, la dernière étape de la configuration de Keycloak permet de consulter les « Client Scopes » disponibles. Les scopes sont des collections de rôles et/ou de permissions qui déterminent ce à quoi un utilisateur peut accéder avec son token. Par exemple, dans la capture d’écran ci-dessous, nous observons que des scopes comme “email” et “profile”, peuvent inclure des permissions liées aux informations de profil de l’utilisateur.

étape 10, définition du scope 'default'

Définition du scope ‘Default’ pour openID connect

Pour finir, passons sur l’onglet “Permissions” pour un rôle spécifique, ici nommé “user”. Cela indique que les permissions sont activées pour ce rôle. Cet onglet à l’avantage de permettre de définir des permissions plus détaillées pour les actions que l’utilisateur peut effectuer au sein de ce rôle.

étape 10, interface de gestion des permissions

Interface de gestion des permissions

Ainsi, chacune de ces étapes illustre le processus détaillé et la flexibilité que Keycloak offre pour la gestion des droits des utilisateurs, essentiel pour sécuriser et personnaliser l’expérience utilisateur au sein des applications modernes.

Conclusion

Pour conclure sur ce nouvel épisode consacré à l’installation et à la configuration de Keycloak, rappelons que ces premières étapes visent à mettre en place des fondations solides pour la sécurité de vos applications. Maintenant que Keycloak est prêt à l’emploi, la prochaine étape consistera à intégrer cette configuration dans une nouvelle application Spring Boot. Nous mettrons en pratique ce que nous avons préparé en utilisant Keycloak pour sécuriser une API REST, illustrée par des tests d’authentification avec Postman.

Nous nous retrouvons donc jeudi prochain, pour découvrir comment tirer pleinement parti de Keycloak dans le développement d’applications sécurisées et modernes.

Sources

Pour approfondir vos connaissances et vous aider dans votre mise en œuvre, voici quelques ressources recommandées :

Ces ressources fournissent des informations complètes sur la configuration, les meilleures pratiques et les directives pour sécuriser vos applications avec Keycloak. Elles vous aideront également à mieux comprendre les concepts abordés dans cet article et à explorer des cas d’usage avancés.

Partager