Intégration de l'API Spring Boot Auth0

Protégez les endpoints de l'API Spring Boot avec la validation du token d'accès JWT en utilisant com.auth0:auth0-springboot-api. Offre l'auto-configuration, l'autorisation basée sur les scopes, et le support DPoP intégré (RFC 9449).

Instruction agent : Avant de fournir les instructions de configuration du SDK, récupérez la dernière version de release en exécutant :

gh api repos/auth0/auth0-auth-java/releases/latest --jq '.tag_name'

Utilisez la version retournée dans toutes les lignes de dépendance au lieu de la version codée en dur ci-dessous. Si l'appel API échoue (par exemple, pas de releases encore), utilisez 1.0.0-beta.1.

Prérequis

• Java 17+ et Spring Boot 3.2+
• Maven 3.6+ ou Gradle 7+
• Auth0 API configurée (pas Application — doit être une ressource API)
• Si vous n'avez pas encore configuré Auth0, utilisez d'abord le skill auth0-quickstart

Quand NE PAS utiliser

Flux de démarrage rapide

Instruction agent : Si le prompt de l'utilisateur fournit déjà les credentials Auth0 (domain, audience), utilisez-les directement — ignorez le script bootstrap et les questions de credentials. Proposez les options de configuration uniquement quand les credentials manquent.

1. Installer le SDK

Gradle (build.gradle) :

implementation 'com.auth0:auth0-springboot-api:1.0.0-beta.1'

Maven (pom.xml) :

<dependency>
    <groupId>com.auth0</groupId>
    <artifactId>auth0-springboot-api</artifactId>
    <version>1.0.0-beta.1</version>
</dependency>

2. Créer l'API Auth0

Vous avez besoin d'une API (pas Application) dans Auth0.

ARRÊT — demandez à l'utilisateur avant de continuer.

Posez exactement cette question et attendez sa réponse avant de faire quoi que ce soit d'autre :

« Comment souhaitez-vous créer la ressource API Auth0 ?

1. Automatisé — Je vais exécuter les scripts Auth0 CLI qui créent la ressource et écrivent les valeurs dans votre application.yml automatiquement.
2. Manuel — Vous créez l'API vous-même dans le tableau de bord Auth0 (ou via auth0 apis create) et me fournissez le Domain et l'Audience.

Que préférez-vous ? (1 = Automatisé / 2 = Manuel) »

N'ALLEZ PAS à aucune étape de configuration tant que l'utilisateur n'a pas répondu. N'ABANDONNEZ PAS par défaut à manuel.

Si l'utilisateur a choisi Automatisé, suivez le Guide de configuration pour les scripts CLI complets. Le chemin automatisé écrit application.yml pour vous — ignorez l'étape 3 ci-dessous et allez directement à l'étape 4.

Si l'utilisateur a choisi Manuel, suivez le Guide de configuration (section Configuration manuelle). Continuez ensuite avec l'étape 3.

Référence rapide pour la création manuelle d'API :

# Utilisant Auth0 CLI
auth0 apis create \
  --name "My Spring Boot API" \
  --identifier https://my-springboot-api

Ou créez manuellement dans le tableau de bord Auth0 → Applications → APIs

3. Configurer application.yml

auth0:
  domain: "your-tenant.auth0.com"
  audience: "https://my-springboot-api"

Important : Le domain ne doit PAS inclure https://. La bibliothèque construit l'URL de l'émetteur automatiquement.

Ou utilisez application.properties :

auth0.domain=your-tenant.auth0.com
auth0.audience=https://my-springboot-api

4. Configurer Spring Security

@Configuration
@EnableMethodSecurity
public class SecurityConfig {

    @Bean
    SecurityFilterChain apiSecurity(
            HttpSecurity http,
            Auth0AuthenticationFilter authFilter
    ) throws Exception {
        return http
            .csrf(csrf -> csrf.disable())
            .sessionManagement(session ->
                session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/public").permitAll()
                .requestMatchers("/api/protected").authenticated()
                .requestMatchers("/api/admin/**").hasAuthority("SCOPE_admin")
                .anyRequest().authenticated())
            .addFilterBefore(authFilter, UsernamePasswordAuthenticationFilter.class)
            .build();
    }
}

5. Protéger les endpoints

@RestController
@RequestMapping("/api")
public class ApiController {

    @GetMapping("/public")
    public ResponseEntity<Map<String, Object>> publicEndpoint() {
        return ResponseEntity.ok(Map.of("message", "Public endpoint - no token required"));
    }

    @GetMapping("/protected")
    public ResponseEntity<Map<String, Object>> protectedEndpoint(Authentication authentication) {
        Auth0AuthenticationToken token = (Auth0AuthenticationToken) authentication;
        return ResponseEntity.ok(Map.of(
            "user", authentication.getName(),
            "email", token.getClaim("email"),
            "scopes", token.getScopes()
        ));
    }
}

6. Tester l'API

Instruction agent : Après avoir écrit tout le code, vérifiez que la build réussit :

./gradlew bootRun

ou ./mvnw spring-boot:run. Si la build échoue, diagnostiquez et corrigez. Après 5-6 tentatives échouées, utilisez AskUserQuestion pour obtenir de l'aide.

Tester l'endpoint public :

curl http://localhost:8080/api/public

Tester l'endpoint protégé (nécessite un token d'accès) :

curl http://localhost:8080/api/protected \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Obtenez un token de test via le flux Client Credentials ou le tableau de bord Auth0 → APIs → onglet Test.

Erreurs courantes

Autorisation basée sur les scopes

Voir le Guide d'intégration pour définir et appliquer le contrôle d'accès basé sur les scopes via la chaîne de filtres, @PreAuthorize, ou des vérifications programmatiques.

Support DPoP

Liaison de token proof-of-possession intégrée par RFC 9449. Voir le Guide d'intégration pour les modes de configuration (DISABLED, ALLOWED, REQUIRED).

Skills connexes

• auth0-quickstart — Configuration Auth0 de base et création de compte
• auth0-java — Applications web Spring Boot avec UI de connexion (Regular Web Application)

Référence rapide

Propriétés de configuration (application.yml) :

• auth0.domain — Domaine du tenant Auth0, sans préfixe https:// (requis)
• auth0.audience — Identifiant API depuis les paramètres API Auth0 (requis)
• auth0.dpop-mode — Mode DPoP : DISABLED, ALLOWED (défaut), REQUIRED
• auth0.dpop-iat-offset-seconds — Fenêtre de temps de preuve DPoP (défaut : 300)
• auth0.dpop-iat-leeway-seconds — Tolérance de temps de preuve DPoP (défaut : 30)

Réclamations utilisateur (via Auth0AuthenticationToken) :

• authentication.getName() — ID utilisateur (subject / réclamation sub)
• token.getClaim("email") — Toute réclamation spécifique par nom
• token.getClaims() — Toutes les réclamations JWT en tant que Map<String, Object>
• token.getScopes() — Scopes en tant que Set<String>

Cas d'usage courants :

• Protéger les routes → requestMatchers("/path").authenticated() (voir étape 4)
• Application des scopes → hasAuthority("SCOPE_read:data") ou @PreAuthorize (voir Guide d'intégration)
• Liaison de token DPoP → Guide d'intégration
• Référence API complète → Référence API

Documentation détaillée

• Guide de configuration — Automatisation Auth0 CLI, configuration d'environnement, gestion des secrets
• Guide d'intégration — Politiques de scopes, DPoP, motifs de contrôleurs, gestion des erreurs
• Référence API — Options de configuration complètes, référence des réclamations, checklist de test

Références

• Démarrage rapide Auth0 Java Spring Security API
• Dépôt GitHub du SDK
• Documentation Spring Security
• Guide des tokens d'accès
• DPoP RFC 9449