[Série Auth/Aut] 1. Configuration de Keycloak

Résumé

Cette série d’articles illustre la mise en place de politiques de contrôle d’accès basée sur des rôles au sein d’une application web. L'introduction de la série est disponible ici et explique l’importance du contrôle d’accès dans un système numérique.

Dans cet article, nous allons voir comment mettre en place une gestion d’utilisateur pour l’application en example avec Keycloak, une solution sur étagère.

Le choix de Keycloak

Keycloak est un outil de gestion des identités et des accès (IAM). Il agit comme une plateforme centralisée permettant la gestion de l’authentification et de l’autorisation au sein de multiples applications et permettant l’intégration de système de gestion d’utilisateurs externes (LDAP, Active Directory). Les principaux standards et protocoles d’authentification sont supportés comme OpenID Connect, OAuth 2.0, et SAML.

Une interface d’administration est disponible pour gérer tout le parametrage (ajout d’utilisateurs, de roles, de permissions, création de clients applicatifs, configurations des jetons…). Une interface de login utilisateur est aussi mise à disposition et personnalisable avec des templates HTML pour une utilisation en marque blanche.

L’outil est open-source et incubé à la Cloud Native Computing Foundation (CNCF) qui est une organisation associée à la Linux Foundation qui fournit des outils, technologies et bonnes pratiques pour l’usage des ressources dans le cloud. Kubernetes (orchestration de conteneur) et Prometheus (monitoring et gestion d’alertes) sont deux autres exemples de projets d’envergure gérés par la CNCF.

Keycloak est écrit en Java et tire profit du framework Quarkus pour optimiser la performance de la solution en environnement cloud ce qui lui permet de tenir des charges importantes.

La communauté de contributeurs est active et relativement importante, la version majeure 25.0.0 est sortie en mai 2024. La documentation est abondante et bien structurée avec notamment des guides de mise en place, d’utilisation et de déploiement pour une multitude d’environnements de production différents:

• des versions conteneurisées sont disponibles en lignes
• des dépôts Helm sont maintenus par la communauté pour un déploiement simplifié sur Kubernetes
• l’application peut aussi être déployée seule sur bare-metal ou VPS fourni par un cloud provider

De nombreuses options sont disponibles pour gérer la persistence : via un fichier pour le développement et le tests, MariaDB, Microsoft SQL, Amazon Aurora ou PostgreSQL pour la production. Cette configuration se fait via une simple variable d’environnement.

Enfin, utiliser une solution existante et modulable comme proposé ici permet non seulement d’éviter de réinventer la roue sur les sujets liés à l’authentification et l’autorisation. Mais c’est aussi se conformer aux standards de sécurité établis et robustes pouvant être ainsi facilement mis en place.

Keycloak se présente donc comme une solution éprouvée et recommandée pour la gestion IAM. Il est de plus déjà en place dans de nombreuses administration publiques européennes comme les gouvernements allemands et belges, l’INRIA et l’université de Lausanne, ou encore le Gouvernement de Polynésie Française, l’Union Nationale Des Missions Locales et France Active.

La mise en place de la brique d’authentification

Les extraits de code présentés au long des articles sont disponibles dans leur version complète sur ce dépôt Github. Une branche est disponible par article de la série avec l’état du dépôt à la fin de l’article correspondant.

Nous allons utiliser un environnement local se basant sur des images Docker. On utilise l’image de la version 25.0 mise à disposition par quay.io via le fichier docker-compose suivant :

name: "demo-auth-aut"

services:
  keycloak:
    image: quay.io/keycloak/keycloak:25.0
    environment:
      KC_HTTP_PORT: 9081
      KEYCLOAK_ADMIN: admin # A remplacer par un secret au passage en production
      KEYCLOAK_ADMIN_PASSWORD: admin # A remplacer par un secret au passage en production
    ports:
      - 9081:9081
    entrypoint: '/opt/keycloak/bin/kc.sh start-dev' # Pour le développement uniquement

On définit un service keycloak utilisant l’image mentionnée ci-dessus. On précise à Keycloak de se lancer en écoutant sur le port 9081, et on configure le port mapping avec la machine locale. Les deux variables d’environnement KEYCLOAK_ADMIN et KEYCLOAK_ADMIN_PASSWORD permettent de définir le nom d’utilisateur et le mot de passe associé au compte d’administration sur l’instance.

On lance le conteneur avec docker-compose up -d et en naviguant sur http://localhost:9081/ on est redirigé vers la page de login.

Fig. 1 : Interface de login sur Keycloak

On utilise le nom d’utilisateur et le mot de passe définis dans les variables d’environnement du service keycloak (”admin” / “admin”) pour se connecter et on arrive sur la console d’administration.

Fig. 2 : Console d’administration

Création du royaume :

L’interface nous indique que nous sommes sur la page de configuration du “master realm” ou “royaume maître”. Un royaume (ou realm en anglais) dans Keycloak est un conteneur pour un ensemble de règles liées à l’authentification et l’autorisation. Les royaumes peuvent coexister au sein d’une même instance mais sont indépendants : les utilisateurs du royaume A ne sont pas visibles dans le royaume B et inversement. Tout le reste de la configuration (rôles, groupes d’utilisateurs, permissions, clients applicatifs …) suivent la même règle d’indépendance entre les royaumes. Le “master realm” est le royaume par défaut utiliser pour l’administration de l’instance Keycloak elle-même.

Nous allons créer un royaume pour notre application web d’exemple :

• Cliquer sur le menu déroulant avec le label “Keycloak”
• Cliquer sur “Create realm”

Fig. 3 : Liste des royaumes

• On renseigner le nom du royaume à créer et on clique sur “Create”

Fig 4 : Formulaire de création de royaume

Création des rôles :

La partie autorisation du contrôle d’accès va être effectuée directement dans Keycloak en utilisant le système de rôles associés à un royaume. On va créer deux rôles : un pour les citoyen et un pour les agents. Ces rôles permettront l’affichage des pages associés dans l’interface utilisateur et seront requis pour consommer l’API du backend.

• Cliquer sur “Realm roles” puis sur le bouton “Create role”

• On crée les deux rôles :

Création des utilisateurs :

Keycloak permet de créer des utilisateurs via la console d’administration, dans l’onglet “Users”. L’objectif est de créer un citoyen et un agent pour vérifier le bon fonctionnement de l’application web. Pour suivre les bonnes pratiques de gestion des utilisateurs, il est préférable de ne pas assigner directement le rôle à un utilisateur. On va à la place utiliser le système de groupes proposés par Keycloak. On placera les utilisateurs dans des groupes pour leur faire hériter des rôles associés à ces groupes.

On crée deux groupes : citoyens et agents.

On assigne à chaque groupe le rôle correspondant via un “role mapping”.

On peut à présent créer les utilisateurs et les adjoindre à un groupe.

Note: export du royaume

Pour éviter de devoir recréer les rôles, groupes et utilisateurs à chaque redémarrage du conteneur, j’ai exporté le royaume demo-auth-aut créé précédemment dans un fichier. Il est disponible dans le dépôt : /realm-config/realm-config.json. On le monte dans le conteneur via un volume pour qu’il soit importé au démarrage de Keycloak. Voici le fichier docker-compose.yaml après ajout du volume :

name: "demo-auth-aut"

services:
  keycloak:
    image: quay.io/keycloak/keycloak:25.0
    environment:
      KC_HTTP_PORT: 9081
      KEYCLOAK_ADMIN: admin # A remplacer par un secret au passage en production
      KEYCLOAK_ADMIN_PASSWORD: admin # A remplacer par un secret au passage en production
    ports:
      - 9081:9081
    volumes:
      - ./realm-config/:/opt/keycloak/data/import:ro
    entrypoint: '/opt/keycloak/bin/kc.sh start-dev --import-realm' # A utiliser en développement seulement

Conclusion

Notre système dispose à présent d’un brique de gestion des utilisateurs qui pourra être consommée par le reste des applications (frontend et backend). Nous avons présenté Keycloak avec ses avantages parmi les solutions de gestion IAM disponibles. Nous avons vu comment mettre en place un royaume et créer des utilisateurs avec des rôles différents.

Dans le prochain article, nous nous intéresserons à la partie authentification du contrôle d’accès pour mettre en place la génération et vérification de JSON Web Token (JWT) dans un frontend Angular et un backend Spring Boot reliés à l’instance Keycloak mise en place. L’ensemble du code produit en l’état à la fin de cet article est disponible ici.