API Java Spring Boot

Ajoutez l’authentification JWT d’Auth0 à une API Spring Boot avec des points de terminaison protégés

Ce guide de démarrage rapide est actuellement en bêta. Nous serions ravis d’avoir vos commentaires!

Utiliser l’IA pour intégrer Auth0

Si vous utilisez un assistant de programmation IA comme Claude Code, Cursor ou GitHub Copilot, vous pouvez ajouter automatiquement l’authentification Auth0 en quelques minutes à l’aide des agent skills.

Installation :

npx skills add auth0/agent-skills --skill auth0-quickstart --skill auth0-springboot-api

Demandez ensuite à votre assistant IA :

Add Auth0 JWT authentication to my Spring Boot API

Votre assistant IA créera automatiquement votre API Auth0, récupérera les informations d’identification, ajoutera la dépendance du SDK Auth0 Spring Boot API, configurera application.yml et implémentera une SecurityFilterChain avec validation des JWT et points de terminaison protégés. Documentation complète sur les agent skills →

Prérequis : Avant de commencer, assurez-vous d’avoir installé ce qui suit :

• JDK 17+ pour assurer la compatibilité avec Spring Boot 3.2+
• Maven 3.6+ ou Gradle 7+ pour la gestion des dépendances
• L’IDE de votre choix (IntelliJ IDEA, Eclipse ou VS Code avec prise en charge de Java)

Compatibilité des versions de Java : Ce guide de démarrage rapide est compatible avec Java 17+ et Spring Boot 3.2+.

​

Pour commencer

Ce guide de démarrage rapide montre comment ajouter l’authentification JWT d’Auth0 à une API Spring Boot. Vous créerez une API sécurisée avec des points de terminaison protégés à l’aide du SDK Auth0 Spring Boot API.

1. Créer un nouveau projet

   Créez un nouveau projet d’API Spring Boot pour ce guide de démarrage rapide :

   Avec Spring Initializr :

   curl -L https://start.spring.io/starter.zip \
       -d dependencies=web,security \
       -d javaVersion=17 \
       -d name=auth0-api \
       -d artifactId=auth0-api \
       -d packageName=com.example.auth0api \
       -o auth0-api.zip
   
   mkdir auth0-api && unzip auth0-api.zip -d auth0-api && cd auth0-api
   

   Ou créez-le manuellement avec Maven :

   mvn archetype:generate \
       -DgroupId=com.example \
       -DartifactId=auth0-api \
       -DarchetypeArtifactId=maven-archetype-quickstart \
       -DinteractiveMode=false
   
   cd auth0-api
   
2. Ajouter le SDK Auth0

   Ajoutez le SDK d’API Auth0 Spring Boot aux dépendances de votre projet :

   Maven (pom.xml) :

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

   Gradle (build.gradle) :

   dependencies {
       implementation 'com.auth0:auth0-springboot-api:1.0.0-beta.0'
   }
   
3. Configurez votre API Auth0

   Ensuite, créez une nouvelle API sur 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 :

   CLI

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

   Mac/Linux

   AUTH0_API_NAME="My Spring Boot API" && \
   AUTH0_API_IDENTIFIER="https://my-springboot-api" && \
   brew tap auth0/auth0-cli && \
   brew install auth0 && \
   auth0 login --no-input && \
   auth0 apis create -n "${AUTH0_API_NAME}" -i "${AUTH0_API_IDENTIFIER}" --offline-access --token-lifetime 86400 --signing-alg RS256 --json > auth0-api-details.json && \
   DOMAIN=$(auth0 tenants list --json | jq -r '.[] | select(.active == true) | .name') && \
   AUDIENCE=$(jq -r '.identifier' auth0-api-details.json) && \
   mkdir -p src/main/resources && \
   printf 'auth0:\n  domain: %s\n  audience: %s\n\nspring:\n  application:\n    name: auth0-api\n' "$DOMAIN" "$AUDIENCE" > src/main/resources/application.yml && \
   rm auth0-api-details.json && \
   echo "✅ application.yml created with your Auth0 API details:" && \
   cat src/main/resources/application.yml
   

   Windows (PowerShell)

   $ApiName = "My Spring Boot API"
   $ApiIdentifier = "https://my-springboot-api"
   $latestRelease = Invoke-RestMethod -Uri "https://api.github.com/repos/auth0/auth0-cli/releases/latest"
   $latestVersion = $latestRelease.tag_name
   $version = $latestVersion -replace "^v"
   Invoke-WebRequest -Uri "https://github.com/auth0/auth0-cli/releases/download/${latestVersion}/auth0-cli_${version}_Windows_x86_64.zip" -OutFile ".\auth0.zip"
   Expand-Archive ".\auth0.zip" .\
   [System.Environment]::SetEnvironmentVariable('PATH', $Env:PATH + ";${pwd}")
   auth0 login --no-input
   auth0 apis create -n "$ApiName" -i "$ApiIdentifier" --offline-access --token-lifetime 86400 --signing-alg RS256 --json | Set-Content -Path auth0-api-details.json
   $Domain = (auth0 tenants list --json | ConvertFrom-Json | Where-Object { $_.active -eq $true }).name
   $Audience = (Get-Content -Raw auth0-api-details.json | ConvertFrom-Json).identifier
   New-Item -ItemType Directory -Force -Path "src\main\resources"
   @"
   auth0:
     domain: "$Domain"
     audience: "$Audience"
   
   spring:
     application:
       name: auth0-api
   "@ | Set-Content "src\main\resources\application.yml"
   Remove-Item auth0-api-details.json
   Write-Output "✅ application.yml created with your Auth0 API details:"
   Get-Content "src\main\resources\application.yml"
   

   Dashboard

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

   src/main/resources/application.yml

   auth0:
     domain: "YOUR_AUTH0_DOMAIN"
     audience: "YOUR_AUTH0_API_IDENTIFIER"
   
   spring:
     application:
       name: auth0-api
   

   1. Accédez à Auth0 Dashboard → Applications → APIs
   2. Sélectionnez Create API
   3. Entrez les renseignements de votre API :
      • Name : My Spring Boot API
      • Identifier : https://my-springboot-api (cela devient votre Audience)
      • Signing Algorithm : RS256
   4. Sélectionnez Create
   5. Remplacez YOUR_AUTH0_DOMAIN dans application.yml par votre Domaine à partir de l’onglet Test (par exemple, your-tenant.auth0.com)
   6. Remplacez YOUR_AUTH0_API_IDENTIFIER dans application.yml par votre Identifier. Par exemple, https://my-springboot-api.

   Votre Domaine ne doit pas inclure https://. Utilisez uniquement le domaine et la région. Par exemple : your-tenant.auth0.com.

   L’Audience (identifiant de l’API) est un identifiant unique pour votre API et peut être n’importe quel URI valide. Elle n’a pas besoin d’être une URL accessible publiquement.

4. Configurer l’authentification

   Créez une classe de configuration de sécurité pour activer l’authentification JWT avec Auth0. Créez src/main/java/com/example/auth0api/SecurityConfig.java :

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

   package com.example.auth0api;
   
   import com.auth0.spring.boot.Auth0AuthenticationFilter;
   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.config.http.SessionCreationPolicy;
   import org.springframework.security.web.SecurityFilterChain;
   import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;
   
   @Configuration
   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/private").authenticated()
                   .anyRequest().permitAll())
               .addFilterBefore(authFilter, UsernamePasswordAuthenticationFilter.class)
               .build();
       }
   }
   
5. Créer des points de terminaison publics et protégés

   Créez des points de terminaison d’API pour tester l’authentification. Créez src/main/java/com/example/auth0api/ApiController.java :

   src/main/java/com/example/auth0api/ApiController.java

   package com.example.auth0api;
   
   import com.auth0.spring.boot.Auth0AuthenticationToken;
   import org.springframework.http.ResponseEntity;
   import org.springframework.security.core.Authentication;
   import org.springframework.web.bind.annotation.GetMapping;
   import org.springframework.web.bind.annotation.RequestMapping;
   import org.springframework.web.bind.annotation.RestController;
   
   import java.util.Map;
   
   @RestController
   @RequestMapping("/api")
   public class ApiController {
   
       // Point de terminaison public - aucune authentification requise
       @GetMapping("/public")
       public ResponseEntity<Map<String, String>> publicEndpoint() {
           return ResponseEntity.ok(Map.of(
               "message", "This endpoint is public - no authentication required"
           ));
       }
   
       // Point de terminaison protégé - authentification requise
       @GetMapping("/private")
       public ResponseEntity<Map<String, Object>> privateEndpoint(Authentication authentication) {
           Auth0AuthenticationToken auth0Token = (Auth0AuthenticationToken) authentication;
   
           return ResponseEntity.ok(Map.of(
               "message", "This endpoint requires authentication",
               "user", authentication.getName(),
               "scopes", auth0Token.getAuthorities()
           ));
       }
   }
   
6. Lancez votre API

   Démarrez votre application Spring Boot :

   Maven :

   ./mvnw spring-boot:run
   

   Gradle:

   ./gradlew bootRun
   

   Votre API s’exécute maintenant à l’adresse http://localhost:8080 (consultez la sortie de la console pour l’URL exacte).

Vérification

Vous devriez maintenant avoir une API protégée par Auth0 pleinement fonctionnelle à l’adresse localhost

---

​

Utilisation avancée

Appel d’API protégées

Testez vos points de terminaison protégés avec un jeton d’accès.

1. Obtenez un jeton d’accès auprès d’Auth0 à l’aide du flux Client Credentials :

curl --request POST \
  --url https://YOUR_DOMAIN/oauth/token \
  --header 'content-type: application/json' \
  --data '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET","audience":"YOUR_AUDIENCE","grant_type":"client_credentials"}'

Pour obtenir YOUR_CLIENT_ID et YOUR_CLIENT_SECRET, créez une application Machine to Machine dans le Auth0 Dashboard et autorisez-la à accéder à votre API.

2. Testez le point de terminaison public (devrait renvoyer 200 OK) :

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

3. Testez le point de terminaison protégé sans authentification (devrait renvoyer 401 Unauthorized) :

curl http://localhost:8080/api/private

4. Appelez le point de terminaison protégé avec le jeton :

curl http://localhost:8080/api/private \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Accès aux claims JWT

Accédez à des informations supplémentaires sur l’utilisateur et aux claims du jeton dans vos points de terminaison.

@GetMapping("/profile")
public ResponseEntity<Map<String, Object>> getUserProfile(Authentication authentication) {
    Auth0AuthenticationToken auth0Token = (Auth0AuthenticationToken) authentication;
    Map<String, Object> claims = auth0Token.getAuthenticationContext().getClaims();

    return ResponseEntity.ok(Map.of(
        "userId", authentication.getName(),
        "email", claims.get("email"),
        "scope", claims.get("scope"),
        "issuer", claims.get("iss"),
        "audience", claims.get("aud")
    ));
}

Autorisation basée sur les scopes

Implémentez un contrôle d’accès granulaire à l’aide des scopes JWT pour renforcer la sécurité.

1. Définissez des scopes dans votre API Auth0 :

Dans le Auth0 Dashboard → APIs → Your API → Permissions, ajoutez des scopes :

• read:users - Lire les données des utilisateurs
• write:users - Écrire des données d’utilisateur
• admin - Accès administratif

2. Configurez des stratégies d’autorisation :

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

Lorsque vous demandez un jeton d’accès, incluez le scope requis :

curl --request POST \
  --url https://YOUR_DOMAIN/oauth/token \
  --header 'content-type: application/json' \
  --data '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET","audience":"YOUR_AUDIENCE","grant_type":"client_credentials","scope":"read:users write:users admin"}'

Sécurité renforcée DPoP

Activez DPoP (Demonstration of preuve de possession) afin de renforcer la sécurité des jetons en liant les jetons d’accès à des clés cryptographiques.

Configurez la prise en charge de DPoP dans application.yml :

auth0:
  domain: "your-tenant.auth0.com"
  audience: "https://my-springboot-api"
  dpopMode: ALLOWED # DISABLED, ALLOWED (par défaut), REQUIRED
  dpopIatOffsetSeconds: 300 # 5 minutes (par défaut)
  dpopIatLeewaySeconds: 60 # marge de 1 minute (par défaut : 30s)

Modes DPoP :

• ALLOWED (par défaut) : accepte à la fois les jetons Bearer et DPoP

• REQUIRED : accepte uniquement les jetons DPoP et rejette les jetons Bearer

• DISABLED : validation JWT Bearer standard uniquement

  Pour en savoir plus sur DPoP, consultez la documentation Auth0 sur DPoP.

---

​

Problèmes courants

401 Non autorisé - audience invalide

Problème : L’API renvoie une erreur 401 même avec des jetons valides.

Solution : Assurez-vous que auth0.audience correspond exactement à l’identifiant de votre API Auth0. La revendication audience du jeton doit correspondre à cette valeur.

# ❌ INCORRECT
auth0:
  audience: "my-api"

# ✅ CORRECT
auth0:
  audience: "https://my-springboot-api"

401 Non autorisé - émetteur invalide

Problème : La validation de l’émetteur du jeton échoue.

Solution : Vérifiez que votre Domaine est correct et n’inclut pas https://. Utilisez le domaine sans le préfixe https://.

# ❌ INCORRECT
auth0:
  domain: "https://your-tenant.auth0.com"

# ✅ CORRECT
auth0:
  domain: "your-tenant.auth0.com"

Valeurs de configuration introuvables

Problème : L’application ne démarre pas en raison d’erreurs de configuration.

Solution : Vérifiez la structure de application.yml et les noms des propriétés. Assurez-vous que la section auth0 contient les valeurs de Domaine et d’Audience.

# ✅ Structure CORRECTE
auth0:
  domain: "your-tenant.auth0.com"
  audience: "https://your-api-identifier"

spring:
  application:
    name: auth0-api

Problèmes d’ordre des filtres

Problème : L’authentification ne fonctionne pas malgré une configuration correcte.

Solution : Assurez-vous que Auth0AuthenticationFilter est correctement intégré à la chaîne Spring Security. Le filtre doit être ajouté avant UsernamePasswordAuthenticationFilter.

// ✅ ORDRE DES FILTRES CORRECT
.addFilterBefore(authFilter, UsernamePasswordAuthenticationFilter.class)

Problèmes de connectivité réseau

Problème : Échec de récupération des JWKS ou délai d’expiration de connexion.

Solution : Il se peut que le pare-feu de l’entreprise bloque les points de terminaison Auth0. Autorisez les domaines Auth0 pour l’accès HTTPS :

# Règles de pare-feu requises (HTTPS/443 sortant)
*.auth0.com
*.us.auth0.com  # Pour les locataires de la région US
*.eu.auth0.com  # Pour les locataires de la région EU
*.au.auth0.com  # Pour les locataires de la région AU

Les scopes ne fonctionnent pas dans les politiques d’autorisation

Problème : Les politiques d’autorisation basées sur les scopes échouent systématiquement.

Solution : Assurez-vous que votre jeton d’accès inclut les scopes requis. Lorsque vous demandez un jeton, précisez les scopes :

curl --request POST \
  --url https://YOUR_DOMAIN/oauth/token \
  --data '{"client_id":"...","client_secret":"...","audience":"...","grant_type":"client_credentials","scope":"read:users write:users admin"}'

Vérifiez également que les scopes sont définis dans les paramètres de votre API Auth0 (Dashboard → APIs → Your API → Permissions).

---

​

Ressources supplémentaires

Documentation du SDK

Documentation complète du SDK et référence de l’API

Exemples de code

Exemples de code complets et modèles d’intégration

Documentation sur DPoP

Découvrez le renforcement de la sécurité par preuve de possession

Référence Spring Security

Documentation officielle de Spring Security

Auth0 Dashboard

Gérez vos API et applications Auth0

Forum communautaire

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

---

​

Application exemple

Une application exemple complète démontrant toutes les fonctionnalités est disponible dans le dépôt du SDK.

Application de démonstration

Comprend des points de terminaison publics et protégés, la prise en charge de DPoP et des exemples complets

Clonez et exécutez :

git clone https://github.com/auth0/auth0-auth-java.git
cd auth0-auth-java/auth0-springboot-api-playground

# Mettez à jour src/main/resources/application.yml avec votre configuration Auth0
# Puis exécutez :
./mvnw spring-boot:run

Tester avec curl :

# Tester le point de terminaison public
curl http://localhost:8080/api/public

# Obtenir un jeton d'accès (remplacer par vos informations d'identification Auth0)
curl -X POST https://YOUR_DOMAIN/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "https://my-springboot-api",
    "grant_type": "client_credentials"
  }'

# Tester le point de terminaison protégé avec un jeton Bearer
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     http://localhost:8080/api/private