Configurer un client OAuth 2.0 / OIDC dans Keycloak

Keycloak est une solution open source de gestion des identités et des accès (IAM). Cet article décrit la configuration d'un client OAuth 2.0 / OpenID Connect dans Keycloak, en détaillant les options importantes et en montrant comment restreindre l'accès aux utilisateurs ou groupes autorisés.

Note de version. L'interface d'administration a été refondue à partir de Keycloak 19. La notion d'Access Type (confidential / public / bearer-only) a disparu au profit des toggles Client authentication et Authorization. Ce guide suit l'UI actuelle (Keycloak 24+).

1. Prérequis

• Une instance Keycloak fonctionnelle (version 24 ou supérieure recommandée).
• Des droits d'administration sur un realm.
• Une application destinée à s'authentifier via OAuth 2.0 / OIDC.
• TLS activé sur Keycloak et sur l'application cliente (obligatoire en production).

2. Qu'est-ce qu'un client dans Keycloak ?

Dans Keycloak, un client représente une application ou un service qui interagit avec le serveur d'authentification, soit pour authentifier des utilisateurs, soit pour obtenir des informations sur eux, soit pour protéger ses propres ressources. Il peut s'agir d'une application web, d'une API, d'une application mobile, d'un service interne ou d'un partenaire tiers.

Chaque client est rattaché à un realm (l'espace logique d'authentification) et identifié par un client_id unique. Cet identifiant est transmis lors de toute demande d'authentification ou d'obtention de jeton.

La configuration d'un client définit notamment :

• les flux OAuth 2.0 autorisés (authorization_code, client_credentials, etc.) ;
• la capacité ou non du client à conserver un secret (client confidentiel vs public) ;
• les URI de redirection acceptées et les origines CORS ;
• la durée de vie des jetons et la composition des claims (mappers) ;
• les politiques d'autorisation associées (rôles, groupes, attributs).

3. Création du client

1. Se connecter à la Keycloak Admin Console.
2. Sélectionner le realm cible.
3. Menu Clients > Create client.

Étape « General settings »

Étape « Capability config »

Étape « Login settings »

Bonne pratique. Les redirect URIs doivent être en https:// en production (sauf http://localhost pour le développement). Spécifier des chemins aussi précis que possible plutôt qu'un wildcard /*.

4. Authentification du client (Credentials)

L'onglet Credentials n'apparaît que si Client authentication est sur ON. Plusieurs méthodes sont disponibles :

Important. Le secret ne doit jamais être commité dans Git ni embarqué dans un binaire distribué. Pour un projet où les secrets vivent dans config/.env, ne commiter que config/.env.example.

5. Types de clients

Depuis Keycloak 19, le « type » est déduit de la combinaison des toggles. La terminologie OAuth reste utile :

Le type « bearer-only » a été retiré : pour une API qui se contente de valider des jetons sans déclencher d'authentification, créer un client confidentiel et n'activer aucun flux.

6. PKCE — recommandé pour tous les clients

PKCE (Proof Key for Code Exchange, RFC 7636) protège le flux Authorization Code contre l'interception du code d'autorisation. Conçu initialement pour les clients publics, il est aujourd'hui recommandé pour tous les clients, y compris confidentiels, et obligatoire dans OAuth 2.1.

Activation dans Advanced > Proof Key for Code Exchange Code Challenge Method > S256.

Ne jamais utiliser plain ; S256 est la seule valeur acceptable.

7. Restreindre l'accès aux utilisateurs ou groupes

Par défaut, tout utilisateur du realm peut se connecter via n'importe quel client. Deux approches permettent de restreindre cet accès.

Approche 1 — Authentification basée sur les rôles (simple)

1. Créer un rôle client dédié, par exemple app-user, dans l'onglet Roles du client.
2. Assigner ce rôle aux utilisateurs ou groupes autorisés (Users > user > Role mapping, ou Groups > group > Role mapping).
3. Dans Authentication > Flows, ajouter une exécution Conditional - User Role au flux Browser, configurée avec le rôle requis et Required.

Cette méthode bloque l'authentification elle-même : un utilisateur sans le rôle ne pourra pas se connecter au client.

Approche 2 — Authorization Services (granulaire)

À utiliser pour gérer des permissions plus fines (ressources, scopes, conditions).

1. Activer Authorization sur le client.
2. Onglet Authorization > Policies > créer une Group Policy ou Role Policy listant les utilisateurs/groupes autorisés.
3. Onglet Permissions > créer une Scope-Based Permission ou Resource-Based Permission liée à la policy.
4. Côté application, utiliser l'endpoint UMA ou l'adaptateur Keycloak pour évaluer les permissions.

Approche 3 — Limiter le client scope « roles »

Dans Client scopes > roles > Scope, désactiver Full scope allowed et n'autoriser que les rôles pertinents. Cela réduit la taille des jetons et limite ce que le client peut « voir » des rôles utilisateurs.

8. Client scopes et mappers

Les client scopes déterminent les claims présents dans les jetons (access_token et id_token).

• Les scopes Default sont systématiquement ajoutés à chaque jeton.
• Les scopes Optional ne sont ajoutés que si l'application les demande via le paramètre scope= lors de l'authentification.

Pour exposer les groupes d'un utilisateur dans le token :

1. Créer un client scope groups (ou réutiliser celui existant).
2. Ajouter un mapper de type Group Membership :
   • Token Claim Name : groups
   • Full group path : OFF (sauf besoin d'arborescence)
   • Add to ID token / Access token / Userinfo : selon l'usage.
3. Attacher le scope au client (Default ou Optional).

9. Réglages avancés à connaître

Pour appliquer automatiquement un ensemble cohérent de règles, utiliser les Client Policies du realm (profils pré-définis oauth-2-1-for-confidential-client et oauth-2-1-for-public-client).

10. Checklist de sécurité

• [ ] Client authentication = ON pour tout client qui peut conserver un secret.
• [ ] PKCE S256 activé.
• [ ] Implicit flow et Direct access grants désactivés.
• [ ] Redirect URIs en https:// et sans wildcard inutile.
• [ ] Web origins explicites (pas de *).
• [ ] Secret stocké dans un coffre-fort, jamais commité.
• [ ] Access token court (≤ 15 min) et refresh token rotatif.
• [ ] Accès restreint via rôle dédié ou Authorization Services.
• [ ] Full scope allowed désactivé si les rôles transportés doivent être limités.
• [ ] Logout backchannel ou front-channel configuré.

Conclusion

La configuration d'un client OAuth 2.0 dans Keycloak repose sur quelques choix structurants — confidentiel ou public, flux activés, PKCE, restriction d'accès — qui ont chacun des implications de sécurité fortes. S'aligner sur OAuth 2.1 (PKCE systématique, pas d'implicit flow, pas de password grant) et utiliser les Client Policies pour appliquer ces règles à l'échelle du realm évite la plupart des configurations à risque.