Aller au contenu

Guide pratique : premier realm et clients

Pourquoi faire cet exercice ?

Ce parcours crée une instance locale de développement, un realm de test, puis des clients OIDC et SAML. Il permet de comprendre comment les pièces s’assemblent avant une intégration applicative réelle. Les options de console changent parfois selon la version ; adaptez les libellés à votre installation.

Avertissement : start-dev, le compte d’administration d’exemple et le secret secret ci-dessous sont uniquement pour un environnement local jetable. Ne les exposez pas à Internet et ne les réutilisez jamais en production.

Schéma du parcours

flowchart TD
    Docker[Conteneur Keycloak en mode développement] --> Realm[Créer le realm demo]
    Realm --> OIDC[Créer client OIDC et callback exact]
    Realm --> SAML[Créer client SAML et configurer métadonnées]
    OIDC --> User[Créer utilisateur et groupe de test]
    SAML --> User
    User --> Roles[Attribuer rôles et scopes nécessaires]
    Roles --> Test[Test avec application et endpoints]
    Test --> Cleanup[Arrêter et supprimer le conteneur]

1. Démarrer Keycloak localement

Docker doit être installé. Dans un terminal :

docker run --name keycloak -p 8080:8080 \\
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \\
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \\
  quay.io/keycloak/keycloak:latest start-dev

Pour un test reproductible, remplacez latest par un tag de version fixé et contrôlé. Ouvrez http://localhost:8080, connectez-vous à la console d’administration avec les identifiants locaux, puis créez un realm nommé demo via le sélecteur de realm et l’action de création. La page d’accueil du realm et ses endpoints sont maintenant distincts de ceux de master.

Vérifiez la découverte OIDC :

curl -s http://localhost:8080/realms/demo/.well-known/openid-configuration | python3 -m json.tool

Résultat attendu : un document JSON avec issuer, authorization_endpoint, token_endpoint, userinfo_endpoint et jwks_uri. Si la commande échoue, vérifiez le nom du realm et les journaux de conteneur (docker logs keycloak).

2. Créer un client OIDC

Dans le realm demo, créer un client avec protocole OpenID Connect et un client ID tel que demo-web. Pour une application web exécutée côté serveur :

  1. Activer l’authentification du client / le mode confidentiel, puis enregistrer le secret dans le backend (jamais dans le navigateur ni dans Git).
  2. Activer le flux Standard Flow (Authorization Code). Désactiver les flux non utilisés, notamment les flux historiques ou les comptes de service si inutiles.
  3. Configurer une URI de redirection de test exacte, par exemple http://localhost:3000/callback, et une origine Web exacte si requise. Ne pas utiliser de joker ouvert.
  4. Utiliser PKCE, idéalement méthode S256, dans l’application cliente en plus de l’authentification du client. Vérifier que la bibliothèque OIDC prend en charge state et nonce.
  5. Copier le secret uniquement dans un environnement local sûr. Un client SPA/mobile serait plutôt public, sans secret, avec Code + PKCE.

La console peut exposer les options sous des noms différents selon la version. Une connexion réussie doit revenir sur le callback configuré avec un code, puis l’application échange ce code côté serveur contre des jetons.

Pour examiner la configuration publique :

curl -s http://localhost:8080/realms/demo/.well-known/openid-configuration

Résultat attendu : l’issuer contient /realms/demo et les URLs des endpoints correspondent à localhost:8080.

3. Rôles, scopes, utilisateurs et groupes

Dans Realm roles, créer un rôle lecteur. Dans Clients, ouvrir demo-web puis Roles et créer rapport:consulter (rôle propre au client). Créer un groupe equipe-demo, puis attribuer au groupe le rôle de realm ou client voulu. Créer un utilisateur de test, définir son mot de passe temporaire et ajouter cet utilisateur au groupe.

Les rôles ne sont pas forcément présents dans chaque jeton. Les scopes et protocol mappers règlent les claims émis : associer un client scope ou configurer les mappers du client pour inclure les rôles nécessaires dans l’access token (et uniquement là où c’est utile). Examiner le contenu du jeton dans un environnement de test, sans publier de jeton réel. L’API doit encore vérifier signature, issuer, audience, expiration et privilèges attendus.

Pour vérifier le jeton de découverte sans secret utilisateur, utiliser le flux client credentials uniquement si les comptes de service sont activés et autorisés :

curl -s -X POST 'http://localhost:8080/realms/demo/protocol/openid-connect/token' \\
  -H 'Content-Type: application/x-www-form-urlencoded' \\
  -d 'grant_type=client_credentials' \\
  -d 'client_id=demo-web' \\
  -d 'client_secret=REMPLACER_PAR_LE_SECRET_LOCAL'

Ce test n’est pas une connexion utilisateur. Résultat attendu si activé et autorisé : JSON avec access_token, token_type et expires_in. Si la réponse indique unauthorized_client, vérifier que les comptes de service sont activés et que le secret est correct. Désactiver ce grant si l’application n’en a pas besoin. Pour un flux utilisateur réel, utiliser une bibliothèque OIDC et Authorization Code + PKCE plutôt qu’un échange manuel dans un script.

4. Créer un client SAML

Créer un client avec protocole SAML, par exemple demo-saml. Renseigner l’Entity ID correspondant au SP et configurer l’URL Assertion Consumer Service (ACS) exacte fournie par l’application. Les paramètres et leur emplacement dépendent de la version et du SP.

Pour importer ou publier les métadonnées, utiliser l’option de téléchargement/import de métadonnées du client ou les métadonnées SAML de Keycloak. Vérifier entity ID, ACS, binding, certificat et paramètres de signature de part et d’autre. Configurer le SP avec les métadonnées IdP de Keycloak, et Keycloak avec celles du SP si le client les fournit. Les URL doivent correspondre exactement aux endpoints atteints. Tester l’initiation SP-initiated, puis seulement si nécessaire IdP-initiated.

Résultat attendu : le navigateur est dirigé vers Keycloak, l’utilisateur s’authentifie, puis une réponse POST arrive à l’ACS ; le SP valide signature, issuer, audience, destinataire, dates et corrélation avant de créer une session. Utilisez une bibliothèque SAML maintenue plutôt que de décoder ou valider le XML à la main.

5. Tester avec une application ou les endpoints

Pour OIDC, connecter une application d’exemple maintenue (par exemple une application web de démonstration compatible avec la version OIDC) avec issuer http://localhost:8080/realms/demo, client ID demo-web et callback configuré. Résultat attendu : redirection vers le login Keycloak puis retour dans la session de l’application. Le secret demeure côté serveur.

Pour lire un access token si un jeton valide a été obtenu par l’application, curl peut appeler un endpoint de ressource qui accepte ce jeton :

curl -H 'Authorization: Bearer <ACCESS_TOKEN>' http://localhost:3000/api/me

Le serveur doit valider le jeton avant de retourner le profil. Remplacer les URL et valeurs selon l’application. Éviter de coller de vrais jetons dans des journaux, tickets ou sites de décodage publics.

Pour obtenir UserInfo avec un jeton OIDC disposant des permissions requises :

curl -H 'Authorization: Bearer <ACCESS_TOKEN>' \\
  http://localhost:8080/realms/demo/protocol/openid-connect/userinfo

Résultat attendu : un objet JSON avec les claims autorisés, dont sub ; une réponse 401/403 indique généralement un jeton absent/invalide ou des droits/scopes insuffisants.

6. Nettoyage et prochaines étapes

Arrêter l’instance de test :

docker stop keycloak && docker rm keycloak

Ce conteneur n’a pas de volume de persistance : supprimer le conteneur supprime les données locales de l’exercice. Poursuivre avec les concepts Keycloak, OIDC, SAML 2.0 et les flux d’authentification. En environnement réel, choisir une base prise en charge, déployer derrière TLS, définir un hostname public cohérent, gérer les secrets, restreindre les URI de retour et appliquer les recommandations de durcissement de la version choisie.