TOC

Guide rapide d’utilisation de Keycloak avec Spring Boot

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:

image

Créons un utilisateur nommé «initial1» avec le mot de passe «zaq1!QAZ».

Nous voyons maintenant «Welcome to Keycloak”:

image

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”:

image

Nous l'appelons «SpringBootKeycloak»:

image

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:

image

Mais nous devons ajouter un client à notre application, alors nous cliquons sur «Créer». Nous appellerons le nouveau client «login-app»:

image

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:

image

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»:

image

Ensuite, nous ajoutons le rôle «user»:

image

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:

image

On ajoute l'utilisateur“user1”:

image

Une fois l'utilisateur créé, nous verrons cette page:

image

Nous pouvons maintenant aller à l'onglet "Credentials". Nous allons définir le mot de passe sur «[email protected]”:

image

Nous naviguons vers l'onglet «Mappages de rôles». Nous attribuerons le rôle utilisateur:

image

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:

image

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:

image

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:

image

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--.

5.6. Demo

Maintenant, une fois que nous nous sommes authentifiés et que nous sommes redirigés vers la page des clients internes, nous verrons:

image

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.

Related