Administrer Keycloak : realms, users, roles

Ce guide vous apprend à administrer Keycloak via la console web. Après l’installation Docker (K1-01), vous allez créer un realm, gérer des utilisateurs dans des groupes, assigner des rôles et configurer un client. Ces compétences sont le socle de tous les guides suivants.

Prérequis

• K1-01 — Installation Docker terminée
• Keycloak accessible à http://localhost:8080
• Identifiants admin créés lors de l’installation

Ce que vous allez apprendre

À la fin de ce module, vous saurez :

• Naviguer efficacement dans l’admin console
• Créer et configurer des realms
• Gérer les utilisateurs et leurs credentials
• Organiser les utilisateurs en groupes hiérarchiques
• Créer et assigner des rôles (realm et client)
• Configurer un client basique
• Surveiller les sessions actives et les events

Accéder à la console d’administration

Ouvrez http://localhost:8080 et cliquez sur Administration Console.

Connectez-vous avec les identifiants créés lors de l’installation :

• Username : admin
• Password : celui défini dans KEYCLOAK_ADMIN_PASSWORD

Navigation dans la console

La console d’administration se divise en plusieurs zones :

Zone	Description
Realm selector (en haut à gauche)	Bascule entre les realms disponibles
Menu latéral	Accès aux différentes sections (Clients, Users, Groups, etc.)
Zone principale	Formulaires de configuration et listes
Breadcrumb	Navigation hiérarchique dans la configuration

Glissez pour voir

Raccourci clavier

Utilisez Ctrl+K (ou Cmd+K sur Mac) pour ouvrir la recherche rapide.

Comprendre les Realms

Un realm est un espace isolé de gestion des identités. Chaque realm possède ses propres :

• Utilisateurs et groupes
• Rôles et permissions
• Clients (applications)
• Configurations de login
• Tokens et sessions

Realm master vs realms applicatifs

Bonne pratique

Ne jamais utiliser le realm master pour les applications. Le realm master est réservé aux super-admins de Keycloak.

Realm	Usage	Utilisateurs
master	Administration de Keycloak lui-même	Super-admins uniquement
Realms applicatifs	Applications et utilisateurs finaux	Utilisateurs de vos apps

Glissez pour voir

Créer un realm applicatif

1. Connectez-vous à la console admin
2. Cliquez sur le realm selector (en haut à gauche, affiche “master”)
3. Cliquez sur Create realm
4. Renseignez les informations :
   • Realm name : lab (en minuscules, sans espaces)
   • Enabled : On
5. Cliquez sur Create

Vous êtes automatiquement basculé sur le nouveau realm.

Configurer un realm

Après création, configurez les paramètres essentiels dans Realm settings :

General

Paramètre	Valeur recommandée	Description
Display name	Lab Formation	Nom affiché aux utilisateurs
HTML Display name	<b>Lab</b> Formation	Avec HTML pour le branding
Frontend URL	(vide en dev)	URL publique en production

Glissez pour voir

Login

Paramètre	Valeur Lab	Description
User registration	Off	Les admins créent les comptes
Forgot password	On	Permet la récupération de mot de passe
Remember me	On	Case “Se souvenir de moi”
Login with email	On	Email comme identifiant
Verify email	Off	Pas de vérification en dev

Glissez pour voir

Sessions

Paramètre	Valeur	Description
SSO Session Idle	30 minutes	Timeout d’inactivité SSO
SSO Session Max	10 hours	Durée max d’une session SSO
Access Token Lifespan	5 minutes	Validité du token d’accès
Refresh Token Lifespan	30 minutes	Validité du refresh token

Glissez pour voir

Tokens

Paramètre	Valeur	Description
Default Signature Algorithm	RS256	Algo de signature des tokens
Access Token Lifespan	5 minutes	Durée de vie des access tokens
Client login timeout	5 minutes	Timeout pendant le flow login

Glissez pour voir

Sauvegarde

Cliquez sur Save après chaque modification. Keycloak ne sauvegarde pas automatiquement.

Gérer les utilisateurs

Les utilisateurs sont des identités qui peuvent se connecter à vos applications.

Utilisateurs locaux vs fédération LDAP

Dans ce module, vous créez des utilisateurs locaux directement dans Keycloak. C’est approprié pour :

• Environnements de développement et formation
• Petites équipes sans annuaire existant
• Comptes admin ou techniques

En production avec un annuaire existant (LDAP, Active Directory), privilégiez la fédération — les utilisateurs restent dans l’annuaire, Keycloak les synchronise. Cette approche est couverte dans le module K3-02 — Fédération LDAP/AD (à venir).

Créer un utilisateur

1. Dans le menu, cliquez sur Users
2. Cliquez sur Add user
3. Renseignez les informations :
   • Username : alice (obligatoire, unique dans le realm)
   • Email : alice@example.com
   • First name : Alice
   • Last name : Martin
   • Enabled : On
4. Cliquez sur Create

Configurer les credentials

Un utilisateur créé n’a pas encore de mot de passe.

1. Après création, allez dans l’onglet Credentials
2. Cliquez sur Set password
3. Renseignez le mot de passe deux fois
4. Temporary :
   • On = l’utilisateur devra le changer à la première connexion
   • Off = mot de passe permanent
5. Cliquez sur Save

Attributs utilisateur

Les attributs permettent de stocker des métadonnées sur l’utilisateur.

Dans l’onglet Attributes, ajoutez des paires clé/valeur :

Attribut	Exemple	Usage
department	Engineering	Département de l’entreprise
employee_id	EMP-001	Identifiant RH
phone	+33612345678	Numéro de téléphone

Glissez pour voir

Ces attributs peuvent être inclus dans les tokens via les mappers (voir K2-01).

Required Actions

Les required actions forcent l’utilisateur à effectuer une action à la prochaine connexion.

Dans l’onglet Details, section Required User Actions, vous pouvez ajouter :

Action	Description
UPDATE_PASSWORD	Changer le mot de passe
VERIFY_EMAIL	Vérifier l’adresse email
UPDATE_PROFILE	Compléter le profil
CONFIGURE_TOTP	Configurer le MFA (TOTP)

Glissez pour voir

Organiser avec les groupes

Les groupes permettent d’organiser les utilisateurs et de leur assigner des attributs et rôles de manière groupée.

Hiérarchie des groupes

Les groupes peuvent être imbriqués. Un utilisateur dans un sous-groupe hérite des attributs et rôles du groupe parent.

Employees/
├── Engineering/
│   ├── Backend/
│   └── Frontend/
├── Marketing/
└── Sales/

Créer une hiérarchie de groupes

1. Dans le menu, cliquez sur Groups
2. Cliquez sur Create group
3. Name : Employees, puis Create
4. Cliquez sur le groupe Employees
5. Cliquez sur Create group (crée un sous-groupe)
6. Name : Engineering, puis Create
7. Répétez pour Marketing et Sales

Assigner un utilisateur à un groupe

1. Allez dans Users et sélectionnez un utilisateur
2. Cliquez sur l’onglet Groups
3. Cliquez sur Join group
4. Sélectionnez le groupe (ex: Employees/Engineering)
5. Cliquez sur Join

Attributs de groupe

Les attributs de groupe sont hérités par tous les membres.

1. Allez dans Groups et sélectionnez un groupe
2. Cliquez sur l’onglet Attributes
3. Ajoutez un attribut : department = Engineering
4. Cliquez sur Save

Tous les membres du groupe auront cet attribut disponible dans leurs tokens (si un mapper est configuré).

Créer et assigner des rôles

Les rôles définissent les permissions des utilisateurs dans les applications.

Types de rôles

Type	Scope	Exemple	Usage
Realm roles	Global au realm	admin, user	Permissions transverses
Client roles	Spécifique à un client	app:read, app:write	Permissions applicatives
Composite roles	Combine d’autres rôles	manager = user + app:read	Bundles de permissions

Glissez pour voir

Créer un realm role

1. Dans le menu, cliquez sur Realm roles
2. Cliquez sur Create role
3. Role name : staff (minuscules, sans espaces)
4. Description : Employé de l'entreprise
5. Cliquez sur Save

Créez également les rôles manager et admin.

Créer un composite role

Un composite role regroupe plusieurs rôles. Utile pour simplifier l’administration.

1. Créez ou éditez un rôle (ex: manager)
2. Activez Composite : On
3. Dans Associated roles, cliquez sur Add roles
4. Sélectionnez les rôles à inclure (ex: staff)
5. Cliquez sur Add

Un utilisateur avec le rôle manager aura automatiquement le rôle staff.

Assigner un rôle à un utilisateur

1. Allez dans Users et sélectionnez un utilisateur
2. Cliquez sur l’onglet Role mapping
3. Cliquez sur Assign role
4. Sélectionnez le rôle (ex: staff)
5. Cliquez sur Assign

Assigner un rôle à un groupe

1. Allez dans Groups et sélectionnez un groupe
2. Cliquez sur l’onglet Role mapping
3. Cliquez sur Assign role
4. Sélectionnez le rôle (ex: staff)
5. Cliquez sur Assign

Tous les membres du groupe héritent automatiquement du rôle.

Default roles

Les default roles sont automatiquement assignés à tout nouvel utilisateur.

1. Allez dans Realm settings > User registration
2. Dans Default roles, cliquez sur Assign role
3. Sélectionnez les rôles par défaut (ex: default-roles-lab)

Configurer les clients

Un client représente une application qui s’authentifie auprès de Keycloak.

Types de clients

Type	Paramètre Client authentication	Usage
Public	Off	SPA, applications mobiles (pas de secret)
Confidential	On	Backend, API (avec secret client)

Glissez pour voir

Créer un client basique

1. Dans le menu, cliquez sur Clients
2. Cliquez sur Create client
3. General settings :
   • Client type : OpenID Connect
   • Client ID : my-app
4. Cliquez sur Next
5. Capability config :
   • Client authentication : Off (public client)
   • Authorization : Off
   • Standard flow : On
   • Direct access grants : Off (recommandé)
6. Cliquez sur Next
7. Login settings :
   • Root URL : http://localhost:3000
   • Valid redirect URIs : http://localhost:3000/*
   • Web origins : http://localhost:3000
8. Cliquez sur Save

Redirect URIs

En production, utilisez des URIs spécifiques. Évitez les wildcards * sauf pour le développement.

Client roles

Créez des rôles spécifiques à votre application :

1. Sélectionnez votre client dans Clients
2. Allez dans l’onglet Roles
3. Cliquez sur Create role
4. Role name : app:admin
5. Cliquez sur Save

Ces rôles apparaissent dans les tokens si l’utilisateur les possède.

Surveiller les sessions

La section Sessions permet de voir qui est connecté et d’invalider les sessions.

Voir les sessions actives

1. Dans le menu, cliquez sur Sessions
2. Vous voyez la liste des sessions actives avec :
   • Utilisateur
   • IP
   • Début de session
   • Dernière activité

Invalider une session

Pour déconnecter un utilisateur :

1. Dans Sessions, trouvez la session
2. Cliquez sur l’icône poubelle
3. Confirmez la déconnexion

Invalider toutes les sessions d’un utilisateur

1. Allez dans Users et sélectionnez l’utilisateur
2. Cliquez sur l’onglet Sessions
3. Cliquez sur Sign out ou Sign out all sessions

Configurer les Events

Les events permettent d’auditer les actions dans Keycloak.

Types d’events

Type	Exemples	Usage
Login events	LOGIN, LOGIN_ERROR, LOGOUT	Audit des authentifications
Admin events	CREATE_USER, UPDATE_ROLE	Audit des actions admin

Glissez pour voir

Activer les events

1. Allez dans Realm settings > Events
2. Onglet User events settings :
   • Save user events : On
   • Expiration : 30 jours
   • Event types : cochez les events à capturer
3. Onglet Admin events settings :
   • Save admin events : On
   • Include representation : On (stocke le payload)
4. Cliquez sur Save

Consulter les events

1. Dans le menu, cliquez sur Events
2. Utilisez les filtres :
   • User events : par type, utilisateur, date
   • Admin events : par opération, ressource
3. Cliquez sur un event pour voir les détails

Intégration SIEM

En production, exportez les events vers un SIEM (Splunk, ELK) via les Event Listeners pour une analyse centralisée.

Account Console

L’Account Console est l’interface utilisateur final pour gérer son propre compte.

Accédez-y via : http://localhost:8080/realms/lab/account/

Les utilisateurs peuvent :

• Voir et modifier leur profil
• Changer leur mot de passe
• Gérer leurs sessions actives
• Configurer le MFA
• Voir les applications autorisées

À tester

Connectez-vous à l’Account Console avec l’utilisateur alice créé précédemment pour voir l’expérience utilisateur final.

Lab A2 — Administration pratique

Mettez en pratique les concepts avec cet exercice guidé.

Objectif

Créer un realm complet avec des utilisateurs organisés en groupes et des rôles.

Étapes du lab

1. Créer le realm :

   • Nom : lab
   • Configure les sessions : SSO Idle = 30 min, Access Token = 5 min

2. Créer la hiérarchie de groupes :

   Employees/
   ├── Engineering/
   └── Marketing/

3. Créer les rôles :

   • Realm roles : staff, manager, admin
   • manager est composite et inclut staff
   • admin est composite et inclut manager

4. Assigner les rôles aux groupes :

   • Employees → rôle staff
   • Employees/Engineering → aucun rôle supplémentaire (hérite de staff)

5. Créer les utilisateurs :

   User	Email	Groupe	Rôle direct
   alice	alice@example.com	Engineering	(hérite staff)
   bob	bob@example.com	Engineering	manager
   charlie	charlie@example.com	Marketing	(hérite staff)

   Glissez pour voir

6. Créer un client de test :

   • Client ID : test-app
   • Type : Public (OIDC)
   • Redirect URIs : http://localhost:3000/*

7. Activer les events :

   • Login events : On
   • Admin events : On

8. Valider :

   • Connectez-vous à l’Account Console avec alice
   • Vérifiez les events de login dans l’admin

Critères de réussite

• Realm lab créé avec sessions configurées
• Groupes hiérarchiques créés (Employees/Engineering, Employees/Marketing)
• Rôles staff, manager (composite), admin (composite) créés
• Rôle staff assigné au groupe Employees
• Utilisateurs créés dans les bons groupes
• Client test-app configuré
• Events de login visibles après connexion utilisateur

À retenir

Concept	Point clé
Realm	Espace isolé d’identités — un par environnement/application
Master	Réservé aux super-admins, jamais pour les applications
Groupes	Organisent les utilisateurs avec héritage d’attributs et rôles
Realm roles	Permissions globales au realm
Client roles	Permissions spécifiques à une application
Composite roles	Regroupent plusieurs rôles pour simplifier l’admin
Sessions	Surveillez et invalidez les connexions actives
Events	Auditez toutes les actions pour la compliance

Glissez pour voir

Dépannage

L’utilisateur ne peut pas se connecter

1. Vérifiez que le compte est Enabled dans l’admin
2. Vérifiez que les credentials sont configurés (onglet Credentials)
3. Vérifiez les events de type LOGIN_ERROR pour le message d’erreur

Les rôles n’apparaissent pas dans le token

1. Vérifiez que le rôle est bien assigné (direct ou via groupe)
2. Vérifiez les mappers du client (voir K2-01 pour les détails)
3. Pour les client roles, vérifiez que le scope est inclus

L’Account Console affiche “Page not found”

Vérifiez l’URL : http://localhost:8080/realms/{realm-name}/account/

Remplacez {realm-name} par le nom exact de votre realm (ex: lab).

Prochaines étapes

OAuth 2.x — Les fondamentaux Comprenez les flows OAuth 2.x avant de configurer des clients.

OpenID Connect — Les fondamentaux La couche d'authentification au-dessus d'OAuth 2.x.

×

📖 Voir la documentation →