API Java Spring Boot

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.

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

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'
}

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
Dashboard

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
Windows (PowerShell)

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

$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"

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

Accédez à Auth0 Dashboard → Applications → APIs
Sélectionnez Create API
Entrez les renseignements de votre API :
- Name : My Spring Boot API
- Identifier : https://my-springboot-api (cela devient votre Audience)
- Signing Algorithm : RS256
Sélectionnez Create
Remplacez YOUR_AUTH0_DOMAIN dans application.yml par votre Domaine à partir de l’onglet Test (par exemple, your-tenant.auth0.com)
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.

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();
    }
}

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()
        ));
    }
}

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érificationVous 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

​Pour commencer

​Utilisation avancée

​Problèmes courants

​Ressources supplémentaires

Documentation du SDK

Exemples de code

Documentation sur DPoP

Référence Spring Security

Auth0 Dashboard

Forum communautaire

​Application exemple

Application de démonstration

Pour commencer

Utilisation avancée

Problèmes courants

Ressources supplémentaires

Application exemple