Java Spring Boot

Prérequis :

JDK 17+ (télécharger)
Maven 3.6+ ou Gradle 7+ (Maven | Gradle)
Un IDE (IntelliJ IDEA, Eclipse ou VS Code recommandés)

Compatibilité des versions de Java : Spring Boot 3.x+ et le Okta Spring Boot Starter 3.x nécessitent Java 17 ou une version ultérieure.

Pour commencer

Ce Quickstart montre comment ajouter la connexion Auth0 à une application Web Spring Boot. Vous créerez une application Web sécurisée avec login, logout et une page de profil protégée à l’aide d’Okta Spring Boot Starter, qui configure automatiquement la prise en charge de OAuth2 login dans Spring Security.

Créer un nouveau projet

Créez un projet Spring Boot avec les dépendances requises.

Avec Spring Initializr
Ou créez-le manuellement avec Maven

curl -L https://start.spring.io/starter.zip \
    -d dependencies=web,security,thymeleaf \
    -d javaVersion=17 \
    -d name=auth0-webapp \
    -d artifactId=auth0-webapp \
    -d packageName=com.auth0.example \
    -o auth0-webapp.zip

mkdir auth0-webapp && unzip auth0-webapp.zip -d auth0-webapp && cd auth0-webapp

mvn archetype:generate \
    -DgroupId=com.auth0 \
    -DartifactId=auth0-webapp \
    -DarchetypeArtifactId=maven-archetype-quickstart \
    -DinteractiveMode=false

cd auth0-webapp

Ajouter le module Okta Spring Boot Starter

Ajoutez la dépendance Okta Spring Boot Starter à votre projet. Cette dépendance ajoute la prise en charge de l’authentification OAuth2 de Spring Security avec l’autoconfiguration propre à Auth0/Okta.

Maven (pom.xml)
Gradle (build.gradle)

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>
<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.thymeleaf.extras</groupId>
    <artifactId>thymeleaf-extras-springsecurity6</artifactId>
</dependency>
<dependency>
    <groupId>com.okta.spring</groupId>
    <artifactId>okta-spring-boot-starter</artifactId>
    <version>3.1.0</version>
</dependency>

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-security'
    implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.thymeleaf.extras:thymeleaf-extras-springsecurity6'
    implementation 'com.okta.spring:okta-spring-boot-starter:3.1.0'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    testImplementation 'org.springframework.security:spring-security-test'
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
}

Configurer Auth0

Créez une Regular Web Application dans votre tenant Auth0 et ajoutez la configuration à votre projet.Vous pouvez choisir de configurer automatiquement votre application Auth0 en exécutant une commande CLI, ou de le faire manuellement par le biais du Dashboard :

CLI
Dashboard

Exécutez la commande shell suivante à la racine de votre projet pour créer une application Auth0 et mettre à jour votre fichier src/main/resources/application.yml :

# Installez Auth0 CLI (s’il n’est pas déjà installé)
brew tap auth0/auth0-cli && brew install auth0

# Configurez l’application Auth0 et générez application.yml
auth0 qs setup --app --type regular --framework spring-boot --build-tool maven --port 3000 --name "My Spring Boot App"

# Installez Auth0 CLI (s’il n’est pas déjà installé)
scoop bucket add auth0 https://github.com/auth0/scoop-auth0-cli.git
scoop install auth0

# Configurez l’application Auth0 et générez application.yml
auth0 qs setup --app --type regular --framework spring-boot --build-tool maven --port 3000 --name "My Spring Boot App"

Cette commande :

Vérifie si vous êtes authentifié (et vous invite à vous connecter au besoin)
Crée une Regular Web Application Auth0 configurée pour http://localhost:3000
Génère src/main/resources/application.yml avec okta.oauth2.issuer, okta.oauth2.client-id et okta.oauth2.client-secret

Les utilisateurs de Gradle doivent remplacer --build-tool maven par --build-tool gradle.

Avant de commencer, ajoutez la configuration d’Auth0 à votre fichier src/main/resources/application.yml :

src/main/resources/application.yml

server:
  port: 3000

okta:
  oauth2:
    issuer: "https://YOUR_AUTH0_DOMAIN/"
    client-id: "YOUR_CLIENT_ID"
    client-secret: "YOUR_CLIENT_SECRET"

Accédez à Auth0 Dashboard → Applications → Applications.
Sélectionnez Create Application.
Entrez un nom (p. ex., “My Spring Boot Webapp”) et sélectionnez Regular Web Applications.
Sélectionnez Create.
Accédez à l’onglet Application Settings et configurez :
- Allowed Callback URLs : http://localhost:3000/login/oauth2/code/okta
- Allowed Logout URLs : http://localhost:3000/
Copiez le Domain, le Client ID et le Client Secret dans l’onglet Application Settings.
Remplacez les valeurs de l’espace réservé dans application.yml.

L’URL de rappel doit correspondre exactement. La connexion OAuth2 de Spring Security utilise le chemin /login/oauth2/code/okta par défaut.L’Issuer doit inclure https:// et un / à la fin. Utilisez uniquement le domaine et la région. Par exemple : https://dev-abc123.us.auth0.com/.

Configurer l’authentification

Créez une configuration de sécurité qui active la connexion OAuth2 et gère la déconnexion d’Auth0. Les utilisateurs non authentifiés sont automatiquement redirigés vers la page de connexion Auth0.

// src/main/java/com/auth0/example/SecurityConfig.java

package com.auth0.example;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.web.authentication.logout.LogoutHandler;
import org.springframework.web.servlet.support.ServletUriComponentsBuilder;

import java.io.IOException;

import static org.springframework.security.config.Customizer.withDefaults;

@Configuration
public class SecurityConfig {

    @Value("${okta.oauth2.issuer}")
    private String issuer;
    @Value("${okta.oauth2.client-id}")
    private String clientId;

    @Bean
    public SecurityFilterChain configure(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authorize -> authorize
                .requestMatchers("/", "/images/**").permitAll()
                .anyRequest().authenticated()
            )
            .oauth2Login(withDefaults())
            .logout(logout -> logout
                .addLogoutHandler(logoutHandler()));
        return http.build();
    }

    private LogoutHandler logoutHandler() {
        return (request, response, authentication) -> {
            try {
                String baseUrl = ServletUriComponentsBuilder.fromCurrentContextPath().build().toUriString();
                response.sendRedirect(issuer + "v2/logout?client_id=" + clientId + "&returnTo=" + baseUrl);
            } catch (IOException e) {
                throw new RuntimeException(e);
            }
        };
    }
}

Créer des contrôleurs et des vues

Créez les contrôleurs et les modèles Thymeleaf pour les pages d’accueil et de profil.

Exécutez votre application

Lancez l’application à l’aide du wrapper Maven ou Gradle.

Maven
Gradle

./mvnw spring-boot:run

./gradlew bootRun

Votre application est maintenant accessible à l’adresse http://localhost:3000. Accédez à http://localhost:3000/profile pour lancer le flux de connexion Auth0.

Vous devriez maintenant avoir une application Web Spring Boot entièrement fonctionnelle avec la connexion Auth0 sur votre localhost. La page d’accueil est publique, et si vous accédez à /profile, les utilisateurs non authentifiés sont redirigés vers la page de connexion Auth0.

Utilisation avancée

Accéder aux claims du profil utilisateur

Le paramètre @AuthenticationPrincipal OidcUser vous donne accès à tous les claims de l’ID token. Utilisez getClaims() pour récupérer l’ensemble complet des claims, ou des méthodes getter individuelles pour des claims précis.

@GetMapping("/profile")
public String profile(Model model, @AuthenticationPrincipal OidcUser oidcUser) {
    model.addAttribute("name", oidcUser.getFullName());
    model.addAttribute("email", oidcUser.getEmail());
    model.addAttribute("picture", oidcUser.getPicture());
    model.addAttribute("sub", oidcUser.getSubject());
    model.addAttribute("allClaims", oidcUser.getClaims());
    return "profile";
}

Contrôle d’accès basé sur les rôles

Vous pouvez restreindre l’accès aux pages en fonction des rôles Auth0. Commencez par ajouter les rôles à l’ID token à l’aide d’une Action Auth0, puis utilisez hasAuthority() dans votre configuration de sécurité.

Ajouter des rôles aux jetons

Accédez à Auth0 Dashboard → Actions → Flows → Login.
Créez une Action personnalisée qui ajoute les rôles sous forme de custom claim à l’ID token :

exports.onExecutePostLogin = async (event, api) => {
  const namespace = "https://my-app.example.com";
  if (event.authorization) {
    api.idToken.setCustomClaim(`${namespace}/roles`, event.authorization.roles);
  }
};

Configurer l’autorisation

Mettez à jour votre SecurityConfig pour exiger des rôles précis sur les endpoints :

@Bean
public SecurityFilterChain configure(HttpSecurity http) throws Exception {
    http
        .authorizeHttpRequests(authorize -> authorize
            .requestMatchers("/", "/images/**").permitAll()
            .requestMatchers("/admin/**").hasAuthority("ROLE_admin")
            .anyRequest().authenticated()
        )
        .oauth2Login(withDefaults())
        .logout(logout -> logout
            .addLogoutHandler(logoutHandler()));
    return http.build();
}

Mappage personnalisé des autorités

Le starter Okta prend en charge le mappage personnalisé des autorités au moyen de l’interface AuthoritiesProvider. Enregistrez un bean pour ajouter des objets GrantedAuthority personnalisés en fonction des attributs de l’utilisateur ou de sources de données externes.

package com.auth0.example;

import com.okta.spring.boot.oauth.AuthoritiesProvider;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.core.authority.SimpleGrantedAuthority;

import java.util.HashSet;
import java.util.List;
import java.util.Set;

@Configuration
public class AuthoritiesConfig {

    @Bean
    AuthoritiesProvider customAuthoritiesProvider() {
        return (user, userRequest) -> {
            Set<GrantedAuthority> authorities = new HashSet<>();

            // Mapper le claim personnalisé des rôles vers les autorités Spring Security
            Object roles = user.getAttribute("https://my-app.example.com/roles");
            if (roles instanceof List<?> roleList) {
                roleList.forEach(role ->
                    authorities.add(new SimpleGrantedAuthority("ROLE_" + role))
                );
            }

            return authorities;
        };
    }
}

Problèmes courants

Échec de la redirection vers la page de connexion - URL de rappel invalide

Après avoir sélectionné login, Auth0 affiche une erreur indiquant que l’URL de rappel ne correspond pas.Les Allowed Callback URLs de votre application Auth0 doivent correspondre exactement à l’URL de rappel utilisée par Spring Security. La valeur par défaut est http://localhost:3000/login/oauth2/code/okta.

Accédez à Auth0 Dashboard → Applications → Votre application → Settings.
Sous Allowed Callback URLs, ajoutez : http://localhost:3000/login/oauth2/code/okta.
Sélectionnez Save Changes.

Issuer invalide au démarrage

L’application ne démarre pas, ou login échoue en raison d’une incompatibilité de l’issuer.Le okta.oauth2.issuer doit être l’URL complète du tenant Auth0, y compris https:// et un / à la fin.

# ❌ INCORRECT - https:// ou la barre oblique finale est manquant
okta:
  oauth2:
    issuer: "dev-abc123.us.auth0.com"

# ✅ CORRECT - URL complète avec barre oblique finale
okta:
  oauth2:
    issuer: "https://dev-abc123.us.auth0.com/"

Échec de la découverte OIDC au démarrage

L’application ne démarre pas en raison d’une erreur de connexion lors de la récupération de /.well-known/openid-configuration.Le Okta Spring Boot Starter récupère le document de découverte OpenID Connect à partir de votre issuer URL au démarrage. Vérifiez que l’issuer URL est correcte et accessible depuis votre réseau. Si vous êtes derrière un firewall d’entreprise, configurez le proxy :

okta:
  oauth2:
    issuer: "https://dev-abc123.us.auth0.com/"
    proxy:
      host: "proxy.example.com"
      port: 8080

Valeurs de configuration introuvables

L’application démarre, mais login échoue parce que les propriétés de configuration ne sont pas lues.Assurez-vous que votre application.yml utilise la bonne indentation YAML sous l’espace de noms okta.oauth2 :

# ❌ INCORRECT - structure plate, non imbriquée
okta.oauth2.issuer: "https://dev-abc123.us.auth0.com/"

# ✅ CORRECT - YAML correctement imbriqué
okta:
  oauth2:
    issuer: "https://dev-abc123.us.auth0.com/"
    client-id: "YOUR_CLIENT_ID"
    client-secret: "YOUR_CLIENT_SECRET"

Logout n’efface pas la session Auth0

Après avoir sélectionné logout, l’utilisateur est immédiatement reconnecté sans voir la page de connexion Auth0.Assurez-vous que votre SecurityConfig inclut le LogoutHandler personnalisé qui redirige vers le endpoint Auth0 /v2/logout. Vérifiez aussi que les Allowed Logout URLs dans les paramètres de votre application Auth0 incluent http://localhost:3000/.

Ressources supplémentaires

Documentation du SDK

Documentation complète du SDK, code source et notes de version

Documentation Auth0

Documentation officielle d’Auth0 pour les applications Spring Boot

Référence de Spring Security

Documentation sur OAuth2 login de Spring Security

Référence de configuration

Toutes les propriétés de configuration okta.oauth2.* offertes

Auth0 Dashboard

Gérez vos API et vos applications Auth0

Forum de la communauté

Obtenez de l’aide auprès de la communauté Auth0

Application d’exemple

Une application d’exemple complète qui montre le login, l’affichage du profil et le logout avec Auth0 est disponible dans le dépôt d’exemples Auth0.

Exemple MVC de login

Comprend le login, le logout et une page de profil avec l’intégration OAuth2 d’Auth0

Clonez et exécutez :

git clone https://github.com/auth0-samples/auth0-spring-boot-login-samples.git
cd auth0-spring-boot-login-samples/mvc-login

# Mettez à jour src/main/resources/application.yml avec votre configuration Auth0
# Puis exécutez :
./gradlew bootRun

Ouvrez http://localhost:3000 dans votre navigateur et sélectionnez le lien Login pour tester le processus de connexion avec Auth0.

Quickstarts

Aperçu d’Auth0

Configurer Auth0

Applications

Pour commencer

Utilisation avancée

Ajouter des rôles aux jetons

Configurer l’autorisation

Problèmes courants

Ressources supplémentaires

Documentation du SDK

Documentation Auth0

Référence de Spring Security

Référence de configuration

Auth0 Dashboard

Forum de la communauté

Application d’exemple

Exemple MVC de login

​Pour commencer

​Utilisation avancée

​Ajouter des rôles aux jetons

​Configurer l’autorisation

​Problèmes courants

​Ressources supplémentaires

Documentation du SDK

Documentation Auth0

Référence de Spring Security

Référence de configuration

Auth0 Dashboard

Forum de la communauté

​Application d’exemple

Exemple MVC de login

Pour commencer

Utilisation avancée

Ajouter des rôles aux jetons

Configurer l’autorisation

Problèmes courants

Ressources supplémentaires

Application d’exemple