Ajoutez l’authentification à votre application Java Spring Boot

Ce guide vous montrera comment intégrer Logto dans votre application Java Spring Boot.

astuce

Vous pouvez trouver le code d'exemple pour ce guide dans notre dépôt github spring-boot-sample.
Aucun SDK officiel n'est requis pour intégrer Logto à votre application Java Spring Boot. Nous utiliserons les bibliothèques Spring Security et Spring Security OAuth2 pour gérer le flux d'authentification OIDC avec Logto.

Prérequis

Un compte Logto Cloud ou un Logto auto-hébergé.
Notre code d'exemple a été créé en utilisant le securing web starter de Spring Boot. Suivez les instructions pour démarrer une nouvelle application web si vous n'en avez pas.
Dans ce guide, nous utiliserons les bibliothèques Spring Security et Spring Security OAuth2 pour gérer le flux d'authentification OIDC avec Logto. Veuillez vous assurer de parcourir la documentation officielle pour comprendre les concepts.

Configurez votre application Java Spring Boot

Ajout de dépendances

Pour les utilisateurs de gradle, ajoutez les dépendances suivantes à votre fichier build.gradle :

build.gradle
dependencies {
  implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'
	implementation 'org.springframework.boot:spring-boot-starter-web'
  implementation 'org.springframework.boot:spring-boot-starter-security'
	implementation 'org.springframework.boot:spring-boot-starter-oauth2-client'
}

Pour les utilisateurs de maven, ajoutez les dépendances suivantes à votre fichier pom.xml :

pom.xml
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-security</artifactId>
</dependency>
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-oauth2-client</artifactId>
</dependency>

Configuration du client OAuth2

Enregistrez une nouvelle application Java Spring Boot dans Logto Console et obtenez les informations d'identification du client et les configurations IdP pour votre application web.

Ajoutez la configuration suivante à votre fichier application.properties :

application.properties
spring.security.oauth2.client.registration.logto.client-name=logto
spring.security.oauth2.client.registration.logto.client-id={{YOUR_CLIENT_ID}}
spring.security.oauth2.client.registration.logto.client-secret={{YOUR_CLIENT_ID}}
spring.security.oauth2.client.registration.logto.redirect-uri={baseUrl}/login/oauth2/code/{registrationId}
spring.security.oauth2.client.registration.logto.authorization-grant-type=authorization_code
spring.security.oauth2.client.registration.logto.scope=openid,profile,offline_access
spring.security.oauth2.client.registration.logto.provider=logto

spring.security.oauth2.client.provider.logto.issuer-uri={{LOGTO_ENDPOINT}}/oidc
spring.security.oauth2.client.provider.logto.authorization-uri={{LOGTO_ENDPOINT}}/oidc/auth
spring.security.oauth2.client.provider.logto.jwk-set-uri={{LOGTO_ENDPOINT}}/oidc/jwks

Implémentation

Avant de plonger dans les détails, voici un aperçu rapide de l'Expérience utilisateur. Le processus de connexion peut être simplifié comme suit :

Votre application lance la méthode de connexion.
L'utilisateur est redirigé vers la page de connexion Logto. Pour les applications natives, le navigateur système est ouvert.
L'utilisateur se connecte et est redirigé vers votre application (configurée comme l'URI de redirection).

Concernant la connexion basée sur la redirection

Ce processus d'authentification (Authentication) suit le protocole OpenID Connect (OIDC), et Logto applique des mesures de sécurité strictes pour protéger la connexion utilisateur.
Si vous avez plusieurs applications, vous pouvez utiliser le même fournisseur d’identité (Logto). Une fois que l'utilisateur se connecte à une application, Logto complétera automatiquement le processus de connexion lorsque l'utilisateur accède à une autre application.

Pour en savoir plus sur la logique et les avantages de la connexion basée sur la redirection, consultez Expérience de connexion Logto expliquée.

Pour rediriger les utilisateurs vers votre application après leur connexion, vous devez définir l'URI de redirection en utilisant la propriété client.registration.logto.redirect-uri à l'étape précédente.

Configurer les URIs de redirection

Passez à la page des détails de l'application de Logto Console. Ajoutez une URI de redirection http://localhost:3000/callback.

Tout comme pour la connexion, les utilisateurs doivent être redirigés vers Logto pour se déconnecter de la session partagée. Une fois terminé, il serait idéal de rediriger l'utilisateur vers votre site web. Par exemple, ajoutez http://localhost:3000/ comme section d'URI de redirection après déconnexion.

Ensuite, cliquez sur "Enregistrer" pour sauvegarder les modifications.

Implémentez le WebSecurityConfig

Créez une nouvelle classe `WebSecurityConfig` dans votre projet

La classe WebSecurityConfig sera utilisée pour configurer les paramètres de sécurité de votre application. C'est la classe clé qui gérera le flux d'authentification et d'Autorisation. Veuillez consulter la documentation Spring Security pour plus de détails.

WebSecurityConfig.java
package com.example.securingweb;

import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;

@Configuration
@EnableWebSecurity

public class WebSecurityConfig {
 // ...
}

Créez un bean `idTokenDecoderFactory`

Ceci est nécessaire car Logto utilise ES384 comme algorithme par défaut, nous devons remplacer le OidcIdTokenDecoderFactory par défaut pour utiliser le même algorithme.

WebSecurityConfig.java
import org.springframework.context.annotation.Bean;
import org.springframework.security.oauth2.client.oidc.authentication.OidcIdTokenDecoderFactory;
import org.springframework.security.oauth2.client.registration.ClientRegistration;
import org.springframework.security.oauth2.jose.jws.SignatureAlgorithm;
import org.springframework.security.oauth2.jwt.JwtDecoderFactory;

public class WebSecurityConfig {
  // ...

  @Bean
  public JwtDecoderFactory<ClientRegistration> idTokenDecoderFactory() {
    OidcIdTokenDecoderFactory idTokenDecoderFactory = new OidcIdTokenDecoderFactory();
    idTokenDecoderFactory.setJwsAlgorithmResolver(clientRegistration -> SignatureAlgorithm.ES384);
    return idTokenDecoderFactory;
  }
}

Créez une classe LoginSuccessHandler pour gérer l'événement de succès de connexion

Nous redirigerons l'utilisateur vers la page /user après une connexion réussie.

CustomSuccessHandler.java
package com.example.securingweb;

import java.io.IOException;

import org.springframework.security.core.Authentication;
import org.springframework.security.web.authentication.AuthenticationSuccessHandler;

import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;

public class CustomSuccessHandler implements AuthenticationSuccessHandler {
  @Override
  public void onAuthenticationSuccess(HttpServletRequest request, HttpServletResponse response,
      Authentication authentication) throws IOException, ServletException {
    response.sendRedirect("/user");
  }
}

Créez une classe LogoutSuccessHandler pour gérer l'événement de succès de déconnexion

Effacez la session et redirigez l'utilisateur vers la page d'accueil.

CustomLogoutHandler.java
package com.example.securingweb;

import java.io.IOException;

import org.springframework.security.core.Authentication;
import org.springframework.security.web.authentication.logout.LogoutSuccessHandler;

import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import jakarta.servlet.http.HttpSession;

public class CustomLogoutHandler implements LogoutSuccessHandler {
  @Override
  public void onLogoutSuccess(HttpServletRequest request, HttpServletResponse response, Authentication authentication)
      throws IOException, ServletException {
    HttpSession session = request.getSession();

    if (session != null) {
      session.invalidate();
    }

    response.sendRedirect("/home");
  }
}

Mettez à jour la classe `WebSecurityConfig` avec un `securityFilterChain`

securityFilterChain est une chaîne de filtres responsables du traitement des requêtes et réponses entrantes.

Nous allons configurer le securityFilterChain pour permettre l'accès à la page d'accueil et exiger une Authentification pour toutes les autres requêtes. Utilisez le CustomSuccessHandler et le CustomLogoutHandler pour gérer les événements de connexion et de déconnexion.

WebSecurityConfig.java
import org.springframework.context.annotation.Bean;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.DefaultSecurityFilterChain;

public class WebSecurityConfig {
  // ...

  @Bean
  public DefaultSecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    http
      .authorizeRequests(authorizeRequests ->
        authorizeRequests
          .antMatchers("/", "/home").permitAll() // Permettre l'accès à la page d'accueil
          .anyRequest().authenticated() // Toutes les autres requêtes nécessitent une Authentification
      )
      .oauth2Login(oauth2Login ->
        oauth2Login
          .successHandler(new CustomSuccessHandler())
      )
      .logout(logout ->
        logout
          .logoutSuccessHandler(new CustomLogoutHandler())
      );
    return http.build();
  }
}

Créez une page d'accueil

(Vous pouvez ignorer cette étape si vous avez déjà une page d'accueil dans votre projet)

HomeController.java
package com.example.securingweb;

import java.security.Principal;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;

@Controller
public class HomeController {
  @GetMapping({ "/", "/home" })
  public String home(Principal principal) {
    return principal != null ? "redirect:/user" : "home";
  }
}

Ce contrôleur redirigera l'utilisateur vers la page utilisateur si l'utilisateur est authentifié, sinon, il affichera la page d'accueil. Ajoutez un lien de connexion à la page d'accueil.

resources/templates/home.html
<body>
  <h1>Bienvenue !</h1>

  <p><a th:href="@{/oauth2/authorization/logto}">Connexion avec Logto</a></p>
</body>

Créez une page utilisateur

Créez un nouveau contrôleur pour gérer la page utilisateur :

UserController.java
package com.example.securingweb;

import java.security.Principal;
import java.util.Map;

import org.springframework.security.oauth2.client.authentication.OAuth2AuthenticationToken;
import org.springframework.security.oauth2.core.user.OAuth2User;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;

@Controller
@RequestMapping("/user")
public class UserController {

  @GetMapping
  public String user(Model model, Principal principal) {
    if (principal instanceof OAuth2AuthenticationToken) {
      OAuth2AuthenticationToken token = (OAuth2AuthenticationToken) principal;
      OAuth2User oauth2User = token.getPrincipal();
      Map<String, Object> attributes = oauth2User.getAttributes();

      model.addAttribute("username", attributes.get("username"));
      model.addAttribute("email", attributes.get("email"));
      model.addAttribute("sub", attributes.get("sub"));
    }

    return "user";
  }
}

Une fois l'utilisateur authentifié, nous récupérerons les données OAuth2User à partir de l'objet principal authentifié. Veuillez vous référer à OAuth2AuthenticationToken et OAuth2User pour plus de détails.

Lisez les données utilisateur et passez-les au modèle user.html.

resources/templates/user.html
<body>
  <h1>Détails de l'utilisateur</h1>
  <div>
    <p>
    <div><strong>nom :</strong> <span th:text="${username}"></span></div>
    <div><strong>email :</strong> <span th:text="${email}"></span></div>
    <div><strong>id :</strong> <span th:text="${sub}"></span></div>
    </p>
  </div>

  <form th:action="@{/logout}" method="post">
    <input type="submit" value="Déconnexion" />
  </form>
</body>

Demander des revendications supplémentaires

Il se peut que certaines informations utilisateur soient manquantes dans l'objet retourné par principal (OAuth2AuthenticationToken). Cela est dû au fait que OAuth 2.0 et OpenID Connect (OIDC) sont conçus pour suivre le principe du moindre privilège (PoLP), et Logto est construit sur ces normes.

Par défaut, des revendications limitées sont retournées. Si vous avez besoin de plus d'informations, vous pouvez demander des portées supplémentaires pour accéder à plus de revendications.

info

Une "revendication" est une assertion faite à propos d'un sujet ; une "portée" est un groupe de revendications. Dans le cas actuel, une revendication est une information sur l'utilisateur.

Voici un exemple non normatif de la relation portée - revendication :

astuce

La revendication "sub" signifie "sujet", qui est l'identifiant unique de l'utilisateur (c'est-à-dire l'ID utilisateur).

Le SDK Logto demandera toujours trois portées : openid, profile et offline_access.

Pour récupérer des informations utilisateur supplémentaires, vous pouvez ajouter des Portées supplémentaires au fichier application.properties. Par exemple, pour demander les Portées email, phone et urn:logto:scope:organizations, ajoutez la ligne suivante au fichier application.properties :

application.properties

  spring.security.oauth2.client.registration.logto.scope=openid,profile,offline_access,email,phone,urn:logto:scope:organizations

Ensuite, vous pouvez accéder aux revendications supplémentaires dans l'objet OAuth2User.

Exécutez et testez l'application

Exécutez l'application et accédez à http://localhost:8080.

Vous verrez la page d'accueil avec un lien de connexion.
Cliquez sur le lien pour vous connecter avec Logto.
Après une Authentification réussie, vous serez redirigé vers la page utilisateur avec vos détails utilisateur.
Cliquez sur le bouton de déconnexion pour vous déconnecter. Vous serez redirigé vers la page d'accueil.

Portées et Revendications

Logto utilise les conventions de portées et revendications d' OIDC pour définir les portées et revendications pour récupérer les informations utilisateur à partir du jeton d’identifiant et du point de terminaison OIDC userinfo. Les termes "portée" et "revendication" proviennent des spécifications OAuth 2.0 et OpenID Connect (OIDC).

En bref, lorsque vous demandez une portée, vous obtiendrez les revendications correspondantes dans les informations utilisateur. Par exemple, si vous demandez la portée email, vous obtiendrez les données email et email_verified de l'utilisateur.

Voici la liste des Portées (Scopes) prises en charge et les Revendications (Claims) correspondantes :

openid

Nom de la revendication	Type	Description	Besoin d'userinfo ?
sub	`string`	L'identifiant unique de l'utilisateur	Non

profile

Nom de la revendication	Type	Description	Besoin d'userinfo ?
name	`string`	Le nom complet de l'utilisateur	Non
username	`string`	Le nom d'utilisateur de l'utilisateur	Non
picture	`string`	URL de la photo de profil de l'utilisateur final. Cette URL DOIT faire référence à un fichier image (par exemple, un fichier image PNG, JPEG ou GIF), plutôt qu'à une page Web contenant une image. Notez que cette URL DOIT spécifiquement référencer une photo de profil de l'utilisateur final adaptée à l'affichage lors de la description de l'utilisateur final, plutôt qu'une photo arbitraire prise par l'utilisateur final.	Non
created_at	`number`	Heure à laquelle l'utilisateur final a été créé. Le temps est représenté comme le nombre de millisecondes depuis l'époque Unix (1970-01-01T00:00:00Z).	Non
updated_at	`number`	Heure à laquelle les informations de l'utilisateur final ont été mises à jour pour la dernière fois. Le temps est représenté comme le nombre de millisecondes depuis l'époque Unix (1970-01-01T00:00:00Z).	Non

D'autres revendications standard incluent family_name, given_name, middle_name, nickname, preferred_username, profile, website, gender, birthdate, zoneinfo, et locale seront également incluses dans la portée profile sans avoir besoin de demander le point de terminaison userinfo. Une différence par rapport aux revendications ci-dessus est que ces revendications ne seront renvoyées que lorsque leurs valeurs ne sont pas vides, tandis que les revendications ci-dessus renverront null si les valeurs sont vides.

remarque

Contrairement aux revendications standard, les revendications created_at et updated_at utilisent des millisecondes au lieu de secondes.

email

Nom de la revendication	Type	Description	Besoin d'userinfo ?
email	`string`	L'adresse e-mail de l'utilisateur	Non
email_verified	`boolean`	Si l'adresse e-mail a été vérifiée	Non

phone

Nom de la revendication	Type	Description	Besoin d'userinfo ?
phone_number	`string`	Le numéro de téléphone de l'utilisateur	Non
phone_number_verified	`boolean`	Si le numéro de téléphone a été vérifié	Non

address

Veuillez vous référer à OpenID Connect Core 1.0 pour les détails de la revendication d'adresse.

custom_data

Nom de la revendication	Type	Description	Besoin d'userinfo ?
custom_data	`object`	Les données personnalisées de l'utilisateur	Oui

identities

Nom de la revendication	Type	Description	Besoin d'userinfo ?
identities	`object`	Les identités liées de l'utilisateur	Oui
sso_identities	`array`	Les identités SSO liées de l'utilisateur	Oui

urn:logto:scope:organizations

Nom de la revendication	Type	Description	Besoin d'userinfo ?
organizations	`string[]`	Les identifiants d'organisation auxquels l'utilisateur appartient	Non
organization_data	`object[]`	Les données d'organisation auxquelles l'utilisateur appartient	Oui

urn:logto:scope:organization_roles

Nom de la revendication	Type	Description	Besoin d'userinfo ?
organization_roles	`string[]`	Les rôles d'organisation auxquels l'utilisateur appartient avec le format `<organization_id>:<role_name>`	Non

En considérant la performance et la taille des données, si "Besoin d'userinfo ?" est "Oui", cela signifie que la revendication n'apparaîtra pas dans le Jeton d’identifiant (ID token), mais sera renvoyée dans la réponse du point de terminaison userinfo.

Ajoutez des portées et revendications supplémentaires dans le fichier application.properties pour demander plus d'informations utilisateur. Par exemple, pour demander la portée urn:logto:scope:organizations, ajoutez la ligne suivante au fichier application.properties :

application.properties

spring.security.oauth2.client.registration.logto.scope=openid,profile,offline_access,urn:logto:scope:organizations

Les revendications d’ organisation utilisateur seront incluses dans le jeton d’autorisation.

Lectures complémentaires

Flux utilisateur final : flux d'authentification, flux de compte et flux d'organisation Configurer les connecteurs Protéger votre API

Prérequis​

Configurez votre application Java Spring Boot​

Ajout de dépendances​

Configuration du client OAuth2​

Implémentation​

Configurer les URIs de redirection​

Implémentez le WebSecurityConfig​

Créez une nouvelle classe WebSecurityConfig dans votre projet​

Créez un bean idTokenDecoderFactory​

Créez une classe LoginSuccessHandler pour gérer l'événement de succès de connexion​

Créez une classe LogoutSuccessHandler pour gérer l'événement de succès de déconnexion​

Mettez à jour la classe WebSecurityConfig avec un securityFilterChain​

Créez une page d'accueil​

Créez une page utilisateur​

Demander des revendications supplémentaires​

Exécutez et testez l'application​

Portées et Revendications​

Lectures complémentaires​