Intégration Keycloak + Spring Boot | Guide Complet
Intégration
Keycloak + Spring Boot
Guide complet — Authentification, Autorisation, Bonnes Pratiques
Version Framework Keycloak Auteur
1.0 Spring Boot 4.x 26.x Formation Spring Security
2026 | Confidentiel Page 1
Intégration Keycloak + Spring Boot | Guide Complet
1. Introduction et Architecture
Keycloak est un serveur d'identité open-source (IAM) qui implémente les standards OAuth
2.0 et OpenID Connect (OIDC). Il gère l'authentification, les sessions, les rôles et les tokens
JWT, permettant à vos applications Spring Boot de déléguer entièrement la sécurité.
Rôles des composants
Composant Rôle Port
Keycloak Serveur d'autorisation (Authorization Server) 8180
Spring Boot Serveur de ressources (Resource Server) 8080
Client (front / mobile) Consommateur d'API protégée -
Flux d'authentification (OIDC Authorization Code Flow)
• Le client envoie une requête de connexion à Keycloak
• Keycloak retourne un formulaire de login
• L'utilisateur saisit ses identifiants
• Keycloak émet un Access Token JWT + Refresh Token
• Le client appelle l'API Spring Boot avec Bearer token
• Spring Boot valide la signature JWT via les clés JWKS de Keycloak
• La ressource protégée est retournée si le token est valide
Pourquoi JWT ?
Les tokens JWT sont auto-porteurs (stateless). Spring Boot vérifie la signature RSA-256 sans
appeler Keycloak à chaque requête, ce qui améliore la performance et réduit le couplage.
2026 | Confidentiel Page 2
Intégration Keycloak + Spring Boot | Guide Complet
2. Configuration de Keycloak
2.1 Installation avec Docker
La méthode la plus rapide pour démarrer Keycloak en développement :
docker run -d --name keycloak \
-p 8180:8080 \
-e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
-e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
[Link]/keycloak/keycloak:26.0 start-dev
# Console d'administration disponible sur :
# [Link]
2.2 Création du Realm
Un Realm est un espace isolé qui contient ses propres utilisateurs, rôles et clients. Créez-en
un nommé spring-app :
• Connectez-vous sur [Link] (admin / admin)
• Menu déroulant en haut à gauche > Create realm
• Realm name : spring-app > Create
2.3 Création du Client
Un Client représente votre application Spring Boot dans Keycloak :
Paramètre Valeur
Client ID spring-boot-app
Client Protocol openid-connect
Access Type confidential
Valid Redirect URIs [Link]
Web Origins [Link]
Client Secret
Notez le Client Secret depuis : Clients > spring-boot-app > Credentials. Il sera utilisé pour obtenir
des tokens en grant_type=password (tests).
2.4 Création des Rôles
Dans Clients > spring-boot-app > Roles, créez :
• ROLE_ADMIN — accès complet (toutes les routes)
• ROLE_USER — accès standard (routes /api/**)
2026 | Confidentiel Page 3
Intégration Keycloak + Spring Boot | Guide Complet
2.5 Création des Utilisateurs
Dans Users > Add user, créez vos utilisateurs de test. Puis dans Role Mappings, assignez
les rôles appropriés. Définissez un mot de passe dans l'onglet Credentials (désactivez
Temporary).
2026 | Confidentiel Page 4
Intégration Keycloak + Spring Boot | Guide Complet
3. Configuration Spring Boot
3.1 Dépendances Maven
Avec Spring Boot 4.x, utilisez le support natif OAuth2 — l'ancien keycloak-spring-boot-
adapter est déprécié :
<!-- Spring Security -->
<dependency>
<groupId>[Link]</groupId>
<artifactId>spring-boot-starter-security</artifactId>
</dependency>
<!-- OAuth2 Resource Server (JWT validation) -->
<dependency>
<groupId>[Link]</groupId>
<artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>
<!-- JOSE (JSON Object Signing and Encryption) -->
<dependency>
<groupId>[Link]</groupId>
<artifactId>spring-security-oauth2-jose</artifactId>
</dependency>
3.2 Configuration [Link]
spring:
security:
oauth2:
resourceserver:
jwt:
# Keycloak expose ses clés publiques (JWKS) ici
jwk-set-uri:
[Link]
# Doit correspondre exactement au claim 'iss' du JWT
issuer-uri: [Link]
app:
keycloak:
client-id: spring-boot-app # Pour extraire les rôles du bon client
logging:
level:
[Link]: DEBUG # Utile pour déboguer
2026 | Confidentiel Page 5
Intégration Keycloak + Spring Boot | Guide Complet
4. Configuration Spring Security
4.1 [Link]
La classe de configuration principale qui définit les règles d'accès et convertit les rôles
Keycloak en GrantedAuthority Spring :
@Configuration
@EnableWebSecurity
@EnableMethodSecurity // active @PreAuthorize, @Secured
public class SecurityConfig {
@Value("${[Link]-id}")
private String clientId;
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception
{
http
.csrf(AbstractHttpConfigurer::disable) // API stateless
.sessionManagement(sm ->
[Link]([Link]))
.authorizeHttpRequests(auth -> auth
.requestMatchers("/public/**").permitAll()
.requestMatchers("/swagger-ui/**", "/v3/api-docs/**").permitAll()
.requestMatchers("/api/admin/**").hasRole("ADMIN")
.requestMatchers("/api/**").hasAnyRole("USER", "ADMIN")
.anyRequest().authenticated()
)
.oauth2ResourceServer(oauth2 -> oauth2
.jwt(jwt -> jwt
.jwtAuthenticationConverter(jwtAuthenticationConverter())))
;
return [Link]();
}
@Bean
public JwtAuthenticationConverter jwtAuthenticationConverter() {
var converter = new JwtAuthenticationConverter();
[Link](keycloakRolesConverter());
return converter;
}
// Keycloak stocke les rôles dans resource_access.<client-id>.roles
// Ce converter les mappe en GrantedAuthority Spring Security
private Converter<Jwt, Collection<GrantedAuthority>>
keycloakRolesConverter() {
return jwt -> {
List<String> roles = new ArrayList<>();
// Rôles du realm (globaux)
Map<String, Object> realmAccess = [Link]("realm_access");
if (realmAccess != null && [Link]("roles")) {
[Link]((List<String>) [Link]("roles"));
}
// Rôles du client (préférables en production)
Map<String, Object> resourceAccess =
[Link]("resource_access");
if (resourceAccess != null && [Link](clientId)) {
2026 | Confidentiel Page 6
Intégration Keycloak + Spring Boot | Guide Complet
Map<String, Object> clientAccess =
(Map<String, Object>) [Link](clientId);
if ([Link]("roles")) {
[Link]((List<String>) [Link]("roles"));
}
}
return [Link]()
.map(r -> new SimpleGrantedAuthority("ROLE_" + [Link]()))
.collect([Link]());
};
}
}
2026 | Confidentiel Page 7
Intégration Keycloak + Spring Boot | Guide Complet
5. Sécurisation des Endpoints REST
5.1 Contrôle d'accès au niveau méthode
@RestController
@RequestMapping("/api")
public class UtilisateurController {
// ROLE_USER ou ROLE_ADMIN
@GetMapping("/utilisateurs")
public List<UtilisateurDTO> listerUtilisateurs() {
return [Link]();
}
// ROLE_ADMIN seulement
@PreAuthorize("hasRole('ADMIN')")
@DeleteMapping("/utilisateurs/{id}")
public void supprimerUtilisateur(@PathVariable Long id) {
[Link](id);
}
// Accès à son propre profil (claim 'sub' = identifiant Keycloak)
@GetMapping("/utilisateurs/me")
public UtilisateurDTO monProfil(Authentication authentication) {
String keycloakId = [Link]();
return [Link](keycloakId);
}
// Logique d'accès personnalisée via un service de sécurité
@PreAuthorize("@[Link](authentication, #id)")
@GetMapping("/utilisateurs/{id}/donnees-sensibles")
public DonneesSensiblesDTO donneesSensibles(
@PathVariable Long id, Authentication authentication) {
return [Link](id);
}
}
5.2 Service de sécurité personnalisé
@Service("securityService")
public class SecurityService {
@Autowired
private UtilisateurRepository utilisateurRepository;
public boolean canAccessResource(Authentication auth, Long resourceId) {
// Admin peut tout voir
if ([Link]().stream()
.anyMatch(a -> [Link]().equals("ROLE_ADMIN"))) {
return true;
}
// User standard : accès uniquement à ses propres ressources
String keycloakId = ((JwtAuthenticationToken) auth)
.getToken().getSubject();
return utilisateurRepository
.existsByIdAndKeycloakId(resourceId, keycloakId);
2026 | Confidentiel Page 8
Intégration Keycloak + Spring Boot | Guide Complet
}
}
5.3 Récupérer les infos utilisateur depuis le JWT
@GetMapping("/api/me")
public Map<String, Object> userInfo(Authentication authentication) {
JwtAuthenticationToken jwtToken = (JwtAuthenticationToken) authentication;
Jwt jwt = [Link]();
return [Link](
"userId", [Link](),
"email", [Link]("email"),
"firstName", [Link]("given_name"),
"lastName", [Link]("family_name"),
"roles", [Link]()
);
}
2026 | Confidentiel Page 9
Intégration Keycloak + Spring Boot | Guide Complet
6. Tester avec curl
6.1 Obtenir un Access Token
# Obtenir un token JWT pour l'utilisateur 'john'
TOKEN=$(curl -s -X POST \
'[Link] \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'client_id=spring-boot-app' \
-d 'client_secret=VOTRE_SECRET' \
-d 'username=john' \
-d 'password=password123' \
-d 'grant_type=password' | jq -r '.access_token')
echo $TOKEN
6.2 Appeler les endpoints protégés
# Route ROLE_USER
curl -H "Authorization: Bearer $TOKEN" \
[Link]
# Route ROLE_ADMIN
curl -H "Authorization: Bearer $TOKEN" \
[Link]
# Décoder le JWT pour inspecter les claims (sans vérifier la signature)
echo $TOKEN | cut -d. -f2 | base64 -d | jq .
2026 | Confidentiel Page 10
Intégration Keycloak + Spring Boot | Guide Complet
7. Bonnes Pratiques de Sécurité
7.1 Gestion des tokens
Pratique Recommandation
Durée de vie Access Token 5 à 15 minutes maximum
Durée de vie Refresh Token 1 à 8 heures selon le contexte
Stockage côté client Mémoire (JS), jamais localStorage
Transport HTTPS obligatoire en production
Renouvellement Silencieux via refresh_token avant expiration
7.2 Gestion des secrets
Ne mettez jamais le client_secret en dur dans votre code source. Utilisez des variables
d'environnement :
# [Link] - référence à une variable d'environnement
spring:
security:
oauth2:
client:
registration:
keycloak:
client-secret: ${KEYCLOAK_CLIENT_SECRET}
# .env ou CI/CD
KEYCLOAK_CLIENT_SECRET=mon-secret-securise
7.3 Logs de débogage
# [Link] - activer les logs de sécurité
logging:
level:
[Link]: DEBUG
[Link].oauth2: TRACE
7.4 Checklist de sécurité
• HTTPS sur Keycloak et Spring Boot en production
• Claim issuer-uri doit correspondre exactement à l'URL HTTPS du realm
• Ne jamais désactiver la validation de signature JWT
• Préférer les rôles au niveau client (resource_access) plutôt que realm
• Rotation régulière des secrets et des clés RSA Keycloak
• Activer le logging des échecs d'authentification pour la détection d'intrusion
• Utiliser le grant_type=client_credentials pour les appels machine-to-machine
2026 | Confidentiel Page 11
Intégration Keycloak + Spring Boot | Guide Complet
2026 | Confidentiel Page 12
Intégration Keycloak + Spring Boot | Guide Complet
8. Résumé des Annotations
Annotation Niveau Exemple d'usage
@EnableWebSecurity Classe config Active Spring Security
@EnableMethodSecurity Classe config Active @PreAuthorize
hasRole('ADMIN') Route / Méthode Accès admin seulement
hasAnyRole('USER','ADMIN' Route / Méthode Accès multi-rôles
)
@PreAuthorize("...") Méthode Expression SpEL flexible
[Link]() Méthode Claim 'sub' du JWT
[Link]() Méthode Accès aux claims JWT
Aller plus loin
Pour des besoins avancés, explorez : Keycloak Admin REST API (gestion programmatique),
Keycloak Events (audit des connexions), Keycloak Themes (personnalisation du login), et
l'intégration avec Spring Cloud Gateway pour un point d'entrée centralisé.
2026 | Confidentiel Page 13