Passer au contenu principal
Prérequis :
  • JDK 17+ (télécharger)
  • Maven 3.6+ ou Gradle 7+ (Maven | Gradle)
  • Un EDI (IntelliJ IDEA, Eclipse ou VS Code recommandés)
Compatibilité des versions de Java : Spring Boot 3.x+ et Okta Spring Boot Starter 3.x nécessitent Java 17 ou une version ultérieure.

​
Pour commencer

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

Créer un nouveau projet

Générez un projet Spring Boot avec les dépendances requises.
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
2

Ajoutez le starter Spring Boot d’Okta

Ajoutez la dépendance Okta Spring Boot Starter à votre projet. Elle inclut la prise en charge de la connexion OAuth2 de Spring Security avec une autoconfiguration propre à Auth0/Okta.
<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>
3

Configurer Auth0

Créez une application Web standard dans votre locataire Auth0 et ajoutez la configuration à votre projet.Vous pouvez effectuer cette opération automatiquement en exécutant une commande CLI ou manuellement via le tableau de bord :
Exécutez la commande shell suivante dans le répertoire racine de votre projet pour créer une application Auth0 et mettre à jour votre fichier application.yml :
AUTH0_APP_NAME="My Spring Boot Webapp" && \
brew tap auth0/auth0-cli && \
brew install auth0 && \
auth0 login --no-input && \
auth0 apps create -n "${AUTH0_APP_NAME}" -t regular \
    --callbacks "http://localhost:3000/login/oauth2/code/okta" \
    --logout-urls "http://localhost:3000/" \
    --json > auth0-app-details.json && \
DOMAIN=$(auth0 tenants list --json | jq -r '.[] | select(.active == true) | .name') && \
CLIENT_ID=$(jq -r '.client_id' auth0-app-details.json) && \
CLIENT_SECRET=$(jq -r '.client_secret' auth0-app-details.json) && \
mkdir -p src/main/resources && \
printf 'server:\n  port: 3000\n\nokta:\n  oauth2:\n    issuer: https://%s/\n    client-id: %s\n    client-secret: %s\n' "$DOMAIN" "$CLIENT_ID" "$CLIENT_SECRET" > src/main/resources/application.yml && \
rm auth0-app-details.json && \
echo "✅ application.yml a été créé avec les détails de votre application Auth0 :" && \
cat src/main/resources/application.yml
4

Configurer l’authentification

Créez une configuration de sécurité qui active la connexion OAuth2 et prend en charge la déconnexion d’Auth0. Les utilisateurs non authentifiés sont automatiquement redirigés vers la page de connexion d’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);
            }
        };
    }
}
5

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

Lancez votre application

Démarrez l’application à l’aide du wrapper Maven ou Gradle.
./mvnw spring-boot:run
Votre application est maintenant accessible à l’adresse http://localhost:3000. Accédez à http://localhost:3000/profile pour lancer le processus de connexion Auth0.
Vous devriez maintenant avoir une application Web Spring Boot entièrement fonctionnelle avec la connexion Auth0, exécutée sur votre localhost. La page d’accueil est publique, et lorsque vous accédez à /profile, les utilisateurs non authentifiés sont redirigés vers la page de connexion Auth0.

​
Utilisation avancée

Le paramètre @AuthenticationPrincipal OidcUser vous donne accès à tous les claims du jeton d’identification. Utilisez getClaims() pour récupérer l’ensemble complet, ou les méthodes d’accès 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";
}
Vous pouvez restreindre l’accès aux pages selon les rôles Auth0. Commencez par ajouter les rôles au jeton d’identification à l’aide d’une action Auth0, puis utilisez hasAuthority() dans votre configuration de sécurité.

​
Ajouter des rôles aux jetons

  1. Accédez au tableau de bord Auth0 → Actions → Flows → Login.
  2. Créez une action personnalisée qui ajoute les rôles comme claim personnalisé au jeton d’identification :
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 certains 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();
}
Le Okta Spring Boot Starter 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 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 de rôles personnalisés 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

Après avoir cliqué sur Connexion, 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. Par défaut, il s’agit de http://localhost:3000/login/oauth2/code/okta.
  1. Allez dans le tableau de bord Auth0 → Applications → votre application → Settings.
  2. Sous Allowed Callback URLs, ajoutez : http://localhost:3000/login/oauth2/code/okta.
  3. Cliquez sur Save Changes.
L’application ne démarre pas ou la connexion échoue en raison d’une non-correspondance de l’issuer.Le okta.oauth2.issuer doit être l’URL complète du tenant Auth0, y compris https:// et la barre oblique finale /.
# ❌ 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/"
L’application ne démarre pas et affiche 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 l’URL de votre issuer au démarrage. Vérifiez que l’URL de l’issuer est correcte et accessible depuis votre réseau. Si vous êtes derrière un pare-feu d’entreprise, configurez le proxy :
okta:
  oauth2:
    issuer: "https://dev-abc123.us.auth0.com/"
    proxy:
      host: "proxy.example.com"
      port: 8080
L’application démarre, mais la connexion échoue parce que les propriétés de configuration ne sont pas lues.Assurez-vous que votre application.yml utilise la bonne indentation YAML dans l’espace de noms okta.oauth2 :
# ❌ INCORRECT - structure à plat, 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"
Après avoir cliqué sur Déconnexion, 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 point de terminaison Auth0 /v2/logout. Vérifiez également 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 d’Auth0

Documentation officielle d’Auth0 pour les applications Spring Boot

Référence Spring Security

Documentation sur l’authentification OAuth2 avec Spring Security

Référence de configuration

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

Tableau de bord Auth0

Gérez vos API et applications Auth0

Forum de la communauté

Obtenez de l’aide de la communauté Auth0

​
Application exemple

Une application exemple complète illustrant la connexion, l’affichage du profil et la déconnexion avec Auth0 est offerte dans le dépôt d’exemples Auth0.

Exemple de connexion MVC

Comprend la connexion, la déconnexion 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 cliquez sur le lien Connexion pour tester le flux de connexion Auth0.