Guide rapide d'utilisation de Keycloak avec Spring Boot
1. Vue d'ensemble
Dans cet article, nous aborderons les bases de la configuration d'un serveur Keycloak, comment yconnect a Spring Boot application et comment l'utiliser avec Spring Security.
2. Qu'est-ce que Keycloak?
Keycloak est une solution open source de gestion des identités et des accès destinée aux applications et services modernes.
Keycloak offre des fonctionnalités telles que l'authentification unique (SSO), le courtage d'identité et la connexion sociale, la fédération d'utilisateurs, les adaptateurs clients, une console d'administration et une console de gestion de compte. Pour en savoir plus sur Keycloak, veuillez visiter leofficial page.
Dans notre didacticiel, nous utiliserons la console d'administration de Keycloak pour configurer, puis nous connecter à Spring Boot à l'aide de l'adaptateur client Keycloak.
3. Configuration d'un serveur Keycloak
3.1. Téléchargement et installation de Keycloak
Vous avez le choix entre plusieurs distributions.
Cependant, dans ce didacticiel, nous utiliserons la version autonome.
TéléchargezKeycloak-3.3.0.Final Standalone server distribution depuis la source officielle.
Une fois que nous avons téléchargé la distribution du serveur autonome, nous pouvons décompresser et démarrer Keycloak à partir du terminal:
unzip keycloak-3.3.0.Final.zip
cd keycloak-3.3.0.Final/bin
./standalone.sh -Djboss.socket.binding.port-offset=100
Après avoir exécuté./standalone.sh, Keycloak démarrera ses services. Une fois que nous voyons une ligne contenantKeycloak 3.3.0.Final (WildFly Core 3.0.1.Final) démarrée, nous saurons que son démarrage est terminé.
Ouvrez un navigateur et visitezhttp://localhost:8180. Nous serons redirigés vershttp://localhost:8180/auth pour créer une connexion administrative:
Créons un utilisateur nommé «initial1» avec le mot de passe «zaq1!QAZ».
Nous voyons maintenant «Welcome to Keycloak”:
Nous pouvons maintenant passer à la console d'administration.
3.2. Créer un royaume
Passons notre souris dans le coin supérieur gauche pour découvrir le bouton“Create a Realm”:
Nous l'appelons «SpringBootKeycloak»:
3.3. Création d'un client
Nous allons maintenant accéder à la page Clients. Comme nous pouvons le voir dans l'image ci-dessous,Keycloak comes with Clients that are already built in:
Mais nous devons ajouter un client à notre application, alors nous cliquons sur «Créer». Nous appellerons le nouveau client «login-app»:
Dans l'écran suivant, pour ce didacticiel, nous laisserons toutes les valeurs par défaut, à l'exception du champ "URI de redirection valides". Nous serons redirigés vers le port8081:
3.4. Créer un rôle et un utilisateur
Keycloak utilise l'accès basé sur les rôles. Par conséquent, chaque utilisateur doit avoir un rôle.
Nous devons accéder à la page «Rôle»:
Ensuite, nous ajoutons le rôle «user»:
Nous avons maintenant un rôle qui peut être attribué aux utilisateurs, mais il n'y a pas encore d'utilisateurs. Alors allons sur la page "Utilisateurs" et ajoutez-en une:
On ajoute l'utilisateur“user1”:
Une fois l'utilisateur créé, nous verrons cette page:
Nous pouvons maintenant aller à l'onglet "Credentials". Nous allons définir le mot de passe sur «[email protected]”:
Nous naviguons vers l'onglet «Mappages de rôles». Nous attribuerons le rôle utilisateur:
3.5. Création d'une page de connexion personnalisée
Keycloak fournit une API REST permettant de générer et d'actualiser des jetons d'accès. Nous pouvons facilement utiliser cette API pour créer notre propre page de connexion.
Tout d'abord, nous devons acquérir un jeton d'accès auprès de Keycloak en envoyant une demande POST à cette adresse URL:
http://localhost:8180/auth/realms/master/protocol/openid-connect/token
La requête doit avoir ce corps JSON:
{
'client_id': 'your_client_id',
'username': 'your_username',
'password': 'your_password',
'grant_type': 'password'
}
En réponse, nous obtiendrons unaccess_token et unrefresh_token.
Le jeton d'accès doit être utilisé dans chaque requête à une ressource protégée par Keycloak en le plaçant simplement dans l'en-têteAuthorization:
headers: {
'Authorization': 'Bearer' + access_token
}
Une fois que le jeton d'accès a expiré, nous pouvons l'actualiser en envoyant une demande POST à la même URL que ci-dessus, mais contenant le jeton d'actualisation à la place du nom d'utilisateur et du mot de passe:
{
'client_id': 'your_client_id',
'refresh_token': refresh_token_from_previous_request,
'grant_type': 'refresh_token'
}
Cela répondra avec un nouveauaccess_token etrefresh_token.
4. Création d'une application de démarrage de printemps
4.1. Les dépendances
Les dernières dépendances de Spring Boot Keycloak Starter peuvent être trouvéeson Maven Central.
The Keycloak Spring Boot adaptercapitalizes on Spring Boot’s auto-configuration, donc tout ce que nous devons faire est d'ajouter le démarreur Keycloak Spring Boot à notre projet.
Dans l'élément XML dépendances, nous avons besoin des éléments suivants pour exécuter Keycloak avec Spring Boot:
org.keycloak
keycloak-spring-boot-starter
Après l'élément XML dependencies, nous devons spécifierdependencyManagement pour Keycloak:
org.keycloak.bom
keycloak-adapter-bom
3.3.0.Final
pom
import
Les conteneurs intégrés suivants sont désormais pris en charge et ne nécessitent aucune dépendance supplémentaire si vous utilisez Spring Boot Keycloak Starter:
-
Matou
-
Reflux
-
Jetée
4.2. Pages Web Thymeleaf
Nous utilisons Thymeleaf pour nos pages Web.
Nous avons trois pages:
-
external.html – une page Web ouverte au public
-
customers.html - une page tournée en interne dont l'accès sera limité uniquement aux utilisateurs authentifiés avec le rôle «utilisateur».
-
layout.html - une mise en page simple, composée de deux fragments, qui est utilisée à la fois pour la page tournée vers l'extérieur et la page tournée vers l'intérieur
Le code des modèles Thymeleaf estavailable on Github.
4.3. Manette
Le contrôleur Web mappe les URL internes et externes aux modèles Thymeleaf appropriés:
@GetMapping(path = "/")
public String index() {
return "external";
}
@GetMapping(path = "/customers")
public String customers(Model model) {
addCustomers();
model.addAttribute("customers", customerDAO.findAll());
return "customers";
}
Pour le chemin/customers, nous récupérons tous les clients d'un référentiel et ajoutons le résultat en tant qu'attribut àModel. Plus tard, nous parcourons les résultats dans Thymeleaf.
4.4. Configuration de Keycloak
Voici la configuration de base obligatoire:
keycloak.auth-server-url=http://localhost:8180/auth
keycloak.realm=SpringBootKeycloak
keycloak.resource=login-app
keycloak.public-client=true
Comme nous le rappelons, nous avons démarré Keycloak sur le port8180, d'où le chemin spécifié danskeycloak.auth-server-url. Nous entrons le nom de domaine que nous avons créé dans la console d'administration Keycloak.
La valeur que nous spécifions danskeycloak.resource correspond au client que nous avons nommé dans la console d'administration.
Voici les contraintes de sécurité que nous utiliserons:
keycloak.security-constraints[0].authRoles[0]=user
keycloak.security-constraints[0].securityCollections[0].patterns[0]=/customers/*
L'état des contraintes de sécurité ci-dessus garantit que chaque demande adressée à/customers/* ne sera autorisée que si celui qui la demande est un utilisateur authentifié avec le rôle «utilisateur».
4.5. Manifestation
Maintenant, nous sommes prêts à tester notre application. Pour exécuter une application Spring Boot, nous pouvons la démarrer facilement via un IDE tel que Spring Tool Suite (STS) ou exécuter cette commande dans le terminal:
mvn clean spring-boot:run
Nous visitonslocalhost:8081:
Maintenant, nous cliquons sur «customers» pour entrer dans l'intranet, qui est l'emplacement des informations sensibles.
Nous pouvons voir que nous avons été redirigés pour nous authentifier via Keycloak pour voir si nous sommes autorisés à afficher ce contenu:
Une fois que nous nous sommes authentifiés et que notre autorisation est vérifiée par Keycloak, nous sommes redirigés vers la page des clients restreints:
Nous avons maintenant terminé la configuration de la connexion de Spring Boot à Keycloak et démontré son fonctionnement.
Nous allons maintenant examiner comment utiliser Spring Security en conjonction avec notre application existante.
5. Sécurité de printemps
Il existe un adaptateur de sécurité Keycloak Spring, et c'estalready included in our Spring Boot Keycloak Starter dependency. Nous allons maintenant voir comment intégrer Spring Security à Keycloak.
5.1. Dépendance
Pour utiliser Spring Security avec Spring Boot, nous devons ajouter cette dépendance:
org.springframework.boot
spring-boot-starter-security
1.5.3
La dernière version de Spring Boot Starter Security peut être trouvéeon Maven Central.
5.2. Classe de configuration
Keycloak fournit unKeycloakWebSecurityConfigurerAdapter comme classe de base pratique pour créer une instanceWebSecurityConfigurer, ce qui est pratique car une classe de configuration étendantWebSecurityConfigurerAdapter est nécessaire pour toute application sécurisée par Spring Security:
@Configuration
@EnableWebSecurity
@ComponentScan(basePackageClasses = KeycloakSecurityComponents.class)
class SecurityConfig extends KeycloakWebSecurityConfigurerAdapter {
@Autowired
public void configureGlobal(
AuthenticationManagerBuilder auth) throws Exception {
KeycloakAuthenticationProvider keycloakAuthenticationProvider
= keycloakAuthenticationProvider();
keycloakAuthenticationProvider.setGrantedAuthoritiesMapper(
new SimpleAuthorityMapper());
auth.authenticationProvider(keycloakAuthenticationProvider);
}
@Bean
public KeycloakSpringBootConfigResolver KeycloakConfigResolver() {
return new KeycloakSpringBootConfigResolver();
}
@Bean
@Override
protected SessionAuthenticationStrategy sessionAuthenticationStrategy() {
return new RegisterSessionAuthenticationStrategy(
new SessionRegistryImpl());
}
@Override
protected void configure(HttpSecurity http) throws Exception {
super.configure(http);
http.authorizeRequests()
.antMatchers("/customers*")
.hasRole("user")
.anyRequest()
.permitAll();
}
}
Veuillez noter le code ci-dessus:
-
configureGlobal: charge leSimpleAuthorityMapper pour s'assurer que les rôles ne sont pas précédés deROLE_
-
keycloakConfigResolver: cela définit que nous voulons utiliser la prise en charge du fichier de propriétés Spring Boot au lieu deskeycloak.json par défaut
5.3. application.properties
Étant donné que nous avons configuré les contraintes de sécurité avec Spring Security, nous pouvons supprimer les contraintes de sécurité précédentes que nous avons placées dansapplication.properties.
Nous allons maintenant ajouter ceci à nosapplication.properties:
keycloak.principal-attribute=preferred_username
5.4. Manette
Pour utiliser le nom d'utilisateur d'un utilisateur, nous mettons à jour notre contrôleur pour injecter lesPrincipal:
@GetMapping(path = "/customers")
public String customers(Principal principal, Model model){
addCustomers();
model.addAttribute("customers", customerDAO.findAll());
model.addAttribute("username", principal.getName());
return "customers";
}
5.5. Thymeleaf
Sous le conteneur div, nous allons ajouter cette ligne pour saluer l'utilisateur:
Hello, --name--.
6. Conclusion
Dans ce tutoriel, nous avons configuré un serveur Keycloak et l'avons utilisé avec une application de démarrage Spring.
Nous avons également vu comment configurer Spring Security et l'utiliser conjointement avec Keycloak. Une version fonctionnelle du code présenté dans cet article est disponibleover on Github.