Ajoutez l’authentification à votre application Java Spring Boot (Add authentication to your Java Spring Boot application)

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 consulter la documentation officielle pour bien comprendre les concepts.

Configurez votre application Java Spring Boot

Ajout des 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 la Console Logto et récupérez les identifiants 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 d’entrer dans les détails, voici un aperçu rapide de l’expérience utilisateur finale. 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).

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.

Afin de 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:8080/login/oauth2/code/logto.

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
// Voir le code ci-dessus, inchangé

Créez un bean `idTokenDecoderFactory`

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

WebSecurityConfig.java
// Voir le code ci-dessus, inchangé

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

CustomSuccessHandler.java
// Voir le code ci-dessus, inchangé

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
// Voir le code ci-dessus, inchangé

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 autoriser l'accès à la page d'accueil et exiger l'authentification pour toutes les autres requêtes. Utilisez les classes CustomSuccessHandler et CustomLogoutHandler pour gérer les événements de connexion et de déconnexion.

WebSecurityConfig.java
// Voir le code ci-dessus, inchangé

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
// Voir le code ci-dessus, inchangé

Ce contrôleur redirigera l'utilisateur vers la page utilisateur s'il 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
// Voir le code ci-dessus, inchangé

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

Lisez les données utilisateur et transmettez-les au template 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 affirmation 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 dans le fichier application.properties. Par exemple, pour demander les portées email, phone et urn:logto:scope:organizations, ajoutez la ligne suivante dans le fichier application.properties :

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

Vous pourrez alors accéder aux revendications supplémentaires dans l'objet OAuth2User.

Exécutez et testez l'application

Lancez 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 informations.
Cliquez sur le bouton de déconnexion pour vous déconnecter. Vous serez redirigé vers la page d'accueil.

Portées et revendications (Scopes and Claims)

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 prises en charge et les revendications correspondantes :

openid

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

profile

Nom de la revendication	Type	Description	Besoin de 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 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 écoulées 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 écoulées 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 de 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 de 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 de userinfo ?
custom_data	`object`	Les données personnalisées de l'utilisateur	Oui

identities

Nom de la revendication	Type	Description	Besoin de 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

roles

Nom de la revendication	Type	Description	Besoin de userinfo ?
roles	`string[]`	Les rôles de l'utilisateur	Non

urn:logto:scope:organizations

Nom de la revendication	Type	Description	Besoin de 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 de 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 de userinfo ?" est "Oui", cela signifie que la revendication n'apparaîtra pas dans le jeton d’identifiant, 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.

Pour aller plus loin

Parcours utilisateur final : flux d’authentification, flux de compte et flux d’organisation Configurer les connecteurs Autorisation (Authorization)

Prérequis​

Configurez votre application Java Spring Boot​

Ajout des dépendances​

Configuration du client OAuth2​

Implémentation​

Concernant la connexion basée sur la redirection​

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 (Scopes and Claims)​

Pour aller plus loin​