Keycloak : Installation & configuration

Écrit par Etienne R.

Dans ce tutoriel de découverte, nous allons voir comment installer et configurer Keycloak afin de mettre en place un SSO (Single Sign-On) basique avec OpenID Connect.

Keycloak, c’est quoi ?

Keycloak est une plateforme open-source de gestion des identités et des accès (IAM pour Identity Management Access) développée par la société RedHat. Elle fournit des fonctionnalités clés telles que l’authentification unifiée (SS0), la gestion des rôles (par groupe ou utilisateur) et les normes de sécurité (OpenID Connect, OAuth 2.0 et SAML).

En résumé, on a un realm (“royaume” en français) qui contient une liste d’utilisateurs. Chaque utilisateur peut appartenir à aucun ou un ou plusieurs groupes. Chaque groupe contient une liste de rôles. Dans ce realm, on a une liste d’intentity provider c’est à dire OpenID Connect et/ou SAML et/ou un provider externe tel que Microsoft, Google, Github, Gitlab, Facebook, etc… et/ou un annuaire tel que Kerberos ou LDAP.

Remarque : pour des raisons de sécurité, chaque realm est isolé dans la BDD de Keycloak.

OpenID Connect

OIDC est un protocole d’identification qui vérifie l’identification d’une personne via HTTPS. Il est basé sur OAuth2.0.

Concrètement, l’utilisateur demande une authentification au serveur. Si l’utilisateur a bien saisi ses identifiants, le serveur lui retourne un token d’accès appelé “access_token” et redirige l’utilisateur vers une url spécifique. Ce token est sous la forme d’un JWT (Jeton Web Token) qui comporte des informations propres à l’utilisateur. En plus de ce token, il peut retourner un “refresh_token” (token de rafraichissement) afin d’éviter à l’utilisateur de se reconnecter après la fin de vie du JWT.

Remarque : le serveur d’authentification ne retournera jamais le mot de passe de l’utilisateur.

Dockeriser Keycloak

Keycloak met à disposition une image Docker. Il a aussi besoin d’une base de données Postgres, ce qui donne le “docker-compose.yml” ci-dessous.

services: postgres: image: postgres:17.0 volumes: - postgres_data:/var/lib/postgresql/data environment: POSTGRES_DB: ${POSTGRES_DB} POSTGRES_USER: ${POSTGRES_USER} POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} restart: always networks: - keycloak_network keycloak: image: quay.io/keycloak/keycloak:26.1 command: start environment: KC_HOSTNAME_STRICT_BACKCHANNEL: false KC_HTTP_ENABLED: true KC_HOSTNAME_STRICT_HTTPS: false KC_HEALTH_ENABLED: true KC_KEYCLOAK_ADMIN: ${KEYCLOAK_ADMIN} KC_KEYCLOAK_ADMIN_PASSWORD: ${KEYCLOAK_ADMIN_PASSWORD} KC_DB: postgres KC_DB_URL: jdbc:postgresql://postgres/${POSTGRES_DB} KC_DB_USERNAME: ${POSTGRES_USER} KC_DB_PASSWORD: ${POSTGRES_PASSWORD} ports: - 8080:8080 restart: always depends_on: - postgres networks: - keycloak_network volumes: postgres_data: driver: local networks: keycloak_network: driver: bridge

Comme vous pouvez le constater, ce fichier contient des valeurs de variables d’environnement. Pour les interpréter, créez un fichier nommé ”.env” pour renseigner les 5 variables avec les valeurs de votre choix.

POSTGRES_DB=keycloak POSTGRES_USER=keycloak POSTGRES_PASSWORD=keycloak KEYCLOAK_ADMIN=keycloak KEYCLOAK_ADMIN_PASSWORD=keycloak

Lancez le build avec la commande docker compose up -d. Puis rendez-vous sur l’URL par défaut http://localhost:8080.

Renseignez les champs avec les valeurs de KEYCLOAK_ADMIN et KEYCLOAK_ADMIN_PASSWORD pour vous connecter.

Configurer Keycloak

Création d’un nouveau royaume

Par défaut, il existe un seul realm, celui de “master” car il permet de gérer les autres realm. On n’est pas censé toucher à ce dernier !

Commencez par créer un nouveau royaume en cliquant sur le bouton “Create realm”.

Puis remplissez le seul champ obligatoire, celui du nom, “Realm name” que l’on nomme “ouidou” dans notre cas et validez en cliquant sur le bouton “Create”.

Création de groupes

Outre le fait de classer des utilisateurs, l’intérêt de créer des groupes permet d’attribuer un ensemble de règles appelées “role”.

Remarque : un utilisateur peut appartenir à 0,n groupe(s).

On va donc créer 2 groupes chez Ouidou, celui des managers et celui des développeurs. Dans le menu de gauche, cliquez sur “Groups” puis sur le bouton “Create group”.

Saisissez le nom du premier groupe “managers” et validez en cliquant sur le bouton “Create”.

Création des utilisateurs

Dans le menu de gauche, cliquez sur “Users”.

Rentrez un nom d’utilisateur puis cliquez sur “Join groups” afin de le rattacher au groupe des “managers” puis cliquez sur le bouton “Join”. Enregistrez l’utilisateur en cliquant sur le bouton “Create”.

Remarque : si vous ne remplissez par le champ “Email”, il sera demandé lors de la première connexion.

Une fois créé, l’utilisateur bénéficie d’un id unique. Avant de poursuivre, il faut lui définir un mot de passe par défaut. Pour ce faire, cliquez sur l’onglet “Credentials” puis sur le bouton “Set password”.

Validez en cliquant sur le bouton “Save”.

Remarque : en laissant l’option “Temporary”, l’utilisateur devra se crée un nouveau mot de passe lors de la première authentification.

Tester la connexion

Dans le menu de gauche, cliquez sur “Clients”.

Sur la première ligne intitulée “account”, vous avez l’URL de connexion dans la dernière colonne “Home URL”, cliquez dessus.

Une demande de changement de mot de passe est demandée.

Une fois connecté, on arrive sur la page de notre compte.

Mot de passe oublié et langue en français

Par défaut, il n’y a pas de “Mot de passe oublié” sur le formulaire de connexion.

En tant qu’admin, dans le menu de gauche, cliquez sur “Realm settings” puis sur l’onglet “Login”. Cochez “Forgot password”. Avant de tester, changez la langue en cliquant sur l’onglet “Localization”. Passez la valeur de “Internationalization” à “Enabled”. Dans “Supported locales”, sélectionnez “French” puis dans le champ “Default locale”, sélectionnez la valeur “French” et validez en cliquant sur le bouton “Save”.

Retournez sur la page de login, le lien “Forgot Password?” apparait.

Sauvegarder et importer sa configuration Keycloak

Sur Keycloak, il est possible (et recommandé) de sauvegarder la configuration sous la forme d’un fichier JSON afin de pouvoir la réimporter et restaurer la configuration en cas de perte des données.

Exporter

Pour l’exportation, on lance la commande d’exécution classique avec Docker.

docker exec -it keycloak /opt/keycloak/bin/kc.sh export --dir /opt/keycloak/data/import --users realm_file --realm ouidou

Puis, on copie le fichier de sauvegarde “ouidou-realm.json” depuis le container de Keycloak vers la machine hôte, dans le répertoire “/tmp” (répertoire spécifique à Linux).

docker cp keycloak:/opt/keycloak/data/import/ouidou-realm.json /tmp

Importer

Pour l’importation, on fait le chemin inverse. On copie le fichier de la machine hôte vers le container.

docker cp /tmp/ouidou-realm.json keycloak:/tmp/ouidou-realm.json

Puis on exécute la commande d’importation en spécifiant le chemin du fichier JSON.

docker exec -it keycloak /opt/keycloak/bin/kc.sh import --file /tmp/ouidou-realm.json

Outro

Keycloak est un outil d’IAM puissant en terme de granularité pour des projets plus poussés mais aussi de sa liste de providers disponibles. En déléguant la partie authentification, il permet de développer des applications web rapidement. Dans la seconde partie, nous allons voir comment mettre en place Keycloak sur une application web Angular.

Sources

• Documentation officielle de Keycloak : Documentation ;
• Image Docker officielle de Postgres : postgres – Official Image | Docker Hub ;
• Image Docker officielle de Keycloak : Quay .