API de Java Spring Boot

Agrega autenticación JWT de Auth0 a una API de Spring Boot con endpoints protegidos

Esta guía de inicio rápido está actualmente en beta. ¡Nos encantaría conocer tus comentarios!

Usa IA para integrar Auth0

Si usas un asistente de programación con IA como Claude Code, Cursor o GitHub Copilot, puedes agregar autenticación de Auth0 automáticamente en minutos con agent skills.

Instalación:

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

Luego, pide a tu asistente de IA:

Add Auth0 JWT authentication to my Spring Boot API

Tu asistente de IA creará automáticamente tu API de Auth0, obtendrá las credenciales, agregará la dependencia del SDK de Auth0 para la API de Spring Boot, configurará application.yml e implementará una SecurityFilterChain con validación de JWT y endpoints protegidos. Documentación completa de agent skills →

Requisitos previos: Antes de comenzar, asegúrate de tener instalado lo siguiente:

• JDK 17+ para compatibilidad con Spring Boot 3.2+
• Maven 3.6+ o Gradle 7+ para gestionar dependencias
• Tu IDE preferido (IntelliJ IDEA, Eclipse o VS Code con soporte para Java)

Compatibilidad de versiones de Java: Esta guía de inicio rápido funciona con Java 17+ y Spring Boot 3.2+.

​

Primeros pasos

Esta guía de inicio rápido muestra cómo agregar la autenticación JWT de Auth0 a una API de Spring Boot. Creará una API segura con endpoints protegidos mediante el SDK de API de Spring Boot de Auth0.

1. Crear un nuevo proyecto

   Cree un nuevo proyecto de API con Spring Boot para esta guía de inicio rápido:

   Con 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
   

   O créelo manualmente con Maven:

   mvn archetype:generate \
       -DgroupId=com.example \
       -DartifactId=auth0-api \
       -DarchetypeArtifactId=maven-archetype-quickstart \
       -DinteractiveMode=false
   
   cd auth0-api
   
2. Añade el SDK de Auth0

   Añade el SDK de API de Auth0 para Spring Boot a las dependencias de tu proyecto:

   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. Configura la API de Auth0

   A continuación, debes crear una nueva API en tu tenant de Auth0 y agregar la configuración a tu proyecto.

   Puede hacerlo automáticamente ejecutando un comando de CLI o de forma manual a través del Dashboard:

   CLI

   Ejecuta el siguiente comando de shell en el directorio raíz de tu proyecto para crear una API de Auth0 y actualizar el archivo 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

   Antes de empezar, agrega la configuración de Auth0 a tu archivo 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. Ve a Auth0 Dashboard → Applications → APIs
   2. Selecciona Create API
   3. Ingresa los datos de tu API:
      • Name: My Spring Boot API
      • Identifier: https://my-springboot-api (esto se convierte en tu Audiencia)
      • Signing Algorithm: RS256
   4. Selecciona Create
   5. Reemplaza YOUR_AUTH0_DOMAIN en application.yml por tu dominio de la pestaña Test (por ejemplo, your-tenant.auth0.com)
   6. Reemplaza YOUR_AUTH0_API_IDENTIFIER en application.yml por tu Identifier. Por ejemplo, https://my-springboot-api.

   Tu dominio no debe incluir https://. Usa solo el dominio y la región. Por ejemplo: your-tenant.auth0.com.

   La Audiencia (API Identifier) es un identificador único para tu API y puede ser cualquier URI válida. No necesita ser una URL de acceso público.

4. Configurar la autenticación

   Crea una clase de configuración de seguridad para habilitar la autenticación con JWT de Auth0. Crea 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. Crear endpoints públicos y protegidos

   Cree endpoints de API para probar la autenticación. Cree 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 {
   
       // Endpoint público - no requiere autenticación
       @GetMapping("/public")
       public ResponseEntity<Map<String, String>> publicEndpoint() {
           return ResponseEntity.ok(Map.of(
               "message", "This endpoint is public - no authentication required"
           ));
       }
   
       // Endpoint protegido - requiere autenticación
       @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. Inicia tu API

   Inicie la aplicación Spring Boot:

   Maven:

   ./mvnw spring-boot:run
   

   Gradle:

   ./gradlew bootRun
   

   Tu API ya está en ejecución en http://localhost:8080 (consulta la salida de la consola para ver la URL exacta).

Punto de verificación

Ahora deberías tener una API protegida por Auth0 totalmente funcional ejecutándose en tu localhost

---

​

Uso avanzado

Llamar a API protegidas

Pruebe sus endpoints protegidos con un token de acceso.

1. Obtenga un token de acceso de Auth0 mediante el flujo 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"}'

Para obtener YOUR_CLIENT_ID y YOUR_CLIENT_SECRET, cree una aplicación Machine to Machine en el Auth0 Dashboard y autorícela para su API.

2. Pruebe el endpoint público (debe devolver 200 OK):

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

3. Pruebe el endpoint protegido sin autenticación (debe devolver 401 Unauthorized):

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

4. Llame al endpoint protegido con el token:

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

Acceso a claims de JWT

Acceda a información adicional del usuario y a los claims del token en sus endpoints.

@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")
    ));
}

Autorización basada en alcances

Implemente un control de acceso detallado mediante los alcances de JWT para mejorar la seguridad.

1. Defina alcances en su API de Auth0:

En Auth0 Dashboard → APIs → Your API → Permissions, agregue alcances:

• read:users - Leer datos de usuario
• write:users - Escribir datos de usuario
• admin - Acceso administrativo

2. Configure políticas de autorización:

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

Al solicitar un token de acceso, incluya el alcance requerido:

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

Seguridad mejorada con DPoP

Habilite DPoP (Demonstration of Proof-of-Possession) para reforzar la seguridad de los tokens al vincular los tokens de acceso a claves criptográficas.

Configure la compatibilidad con DPoP en application.yml:

auth0:
  domain: "your-tenant.auth0.com"
  audience: "https://my-springboot-api"
  dpopMode: ALLOWED # DISABLED, ALLOWED (predeterminado), REQUIRED
  dpopIatOffsetSeconds: 300 # 5 minutos (predeterminado)
  dpopIatLeewaySeconds: 60 # 1 minuto de margen (predeterminado: 30 s)

Modos de DPoP:

• ALLOWED (predeterminado): Acepta tokens Bearer y DPoP

• REQUIRED: Solo acepta tokens DPoP; rechaza tokens Bearer

• DISABLED: Solo validación estándar de JWT Bearer

  Obtenga más información sobre DPoP en la documentación de DPoP de Auth0.

---

​

Problemas comunes

401 Unauthorized - Audiencia no válida

Problema: La API devuelve un 401 incluso con tokens válidos.

Solución: Asegúrate de que auth0.audience coincida exactamente con el identificador de tu API en Auth0. La reclamación audience del token debe coincidir con este valor.

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

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

401 Unauthorized - Emisor no válido

Problema: La validación del emisor del token falla.

Solución: Verifica que tu dominio sea correcto y que no incluya https://. Usa el dominio sin el prefijo https://.

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

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

No se encontraron los valores de configuración

Problema: La aplicación no se inicia debido a errores de configuración.

Solución: Verifica la estructura de application.yml y los nombres de las propiedades. Asegúrate de que la sección auth0 contenga los valores de dominio y audiencia.

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

spring:
  application:
    name: auth0-api

Problemas con el orden de los filtros

Problema: La autenticación no funciona a pesar de que la configuración es correcta.

Solución: Asegúrate de que Auth0AuthenticationFilter esté correctamente integrado en la cadena de Spring Security. El filtro debe agregarse antes de UsernamePasswordAuthenticationFilter.

// ✅ ORDEN DE FILTRO CORRECTO
.addFilterBefore(authFilter, UsernamePasswordAuthenticationFilter.class)

Problemas de conectividad de red

Problema: Fallos al recuperar JWKS o tiempos de espera de conexión.

Solución: Es posible que el firewall corporativo esté bloqueando los endpoints de Auth0. Agrega los dominios de Auth0 a la lista permitida para el acceso por HTTPS:

# Reglas de firewall requeridas (HTTPS/443 saliente)
*.auth0.com
*.us.auth0.com  # Para inquilinos de la región de EE. UU.
*.eu.auth0.com  # Para inquilinos de la región de la UE
*.au.auth0.com  # Para inquilinos de la región de AU

Los alcances no funcionan en las políticas de autorización

Problema: Las políticas de autorización basadas en alcances siempre fallan.

Solución: Asegúrate de que tu token de acceso incluya los alcances necesarios. Al solicitar un token, especifica los alcances:

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

También verifica que los alcances estén definidos en la configuración de tu API de Auth0 (Dashboard → APIs → Tu API → Permissions).

---

​

Recursos adicionales

Documentación del SDK

Documentación completa del SDK y referencia de la API

Ejemplos de código

Amplia colección de ejemplos de código y patrones de integración

Documentación de DPoP

Más información sobre la mejora de seguridad mediante prueba de posesión

Referencia de Spring Security

Documentación oficial de Spring Security

Auth0 Dashboard

Administre sus API y aplicaciones de Auth0

Foro de la comunidad

Obtenga ayuda de la comunidad de Auth0

---

​

Aplicación de ejemplo

En el repositorio del SDK hay disponible una aplicación de ejemplo completa que muestra todas las funciones.

Aplicación de entorno de pruebas

Incluye endpoints públicos y protegidos, compatibilidad con DPoP y ejemplos completos

Clone y ejecute:

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

# Actualiza src/main/resources/application.yml con tu configuración de Auth0
# Luego ejecuta:
./mvnw spring-boot:run

Prueba con curl:

# Probar el endpoint público
curl http://localhost:8080/api/public

# Obtener token de acceso (reemplazar con tus credenciales de 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"
  }'

# Probar el endpoint protegido con token Bearer
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     http://localhost:8080/api/private