auth0-springboot-api

Auth0 Spring Boot API Integration

Protect Spring Boot API endpoints with JWT access token validation using com.auth0:auth0-springboot-api. Features auto-configuration, scope-based authorization, and built-in DPoP (RFC 9449) support.

Agent instruction: Before providing SDK setup instructions, fetch the latest release version by running:

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

Use the returned version in all dependency lines instead of any hardcoded version below. If the API call fails (e.g., no releases yet), use 1.0.0-beta.1.

Prerequisites

• Java 17+ and Spring Boot 3.2+
• Maven 3.6+ or Gradle 7+
• Auth0 API configured (not Application — must be API resource)
• If you don't have Auth0 set up yet, use the auth0-quickstart skill first

When NOT to Use

Quick Start Workflow

Agent instruction: If the user's prompt already provides Auth0 credentials (domain, audience), use them directly — skip the bootstrap script and credential questions. Only offer setup options when credentials are missing.

1. Install 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. Create Auth0 API

You need an API (not Application) in Auth0.

STOP — ask the user before proceeding.

Ask exactly this question and wait for their answer before doing anything else:

"How would you like to create the Auth0 API resource?

1. Automated — I'll run Auth0 CLI scripts that create the resource and write the values to your application.yml automatically.
2. Manual — You create the API yourself in the Auth0 Dashboard (or via auth0 apis create) and provide me the Domain and Audience.

Which do you prefer? (1 = Automated / 2 = Manual)"

Do NOT proceed to any setup steps until the user has answered. Do NOT default to manual.

If the user chose Automated, follow the Setup Guide [blocked] for complete CLI scripts. The automated path writes application.yml for you — skip Step 3 below and proceed directly to Step 4.

If the user chose Manual, follow the Setup Guide [blocked] (Manual Setup section). Then continue with Step 3.

Quick reference for manual API creation:

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

Or create manually in Auth0 Dashboard → Applications → APIs

3. Configure application.yml

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

Important: Domain must NOT include https://. The library constructs the issuer URL automatically.

Or use application.properties:

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

4. Configure 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. Protect 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. Test API

Agent instruction: After writing all code, verify the build succeeds:

./gradlew bootRun

or ./mvnw spring-boot:run. If build fails, diagnose and fix. After 5-6 failed attempts, use AskUserQuestion to get help.

Test public endpoint:

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

Test protected endpoint (requires access token):

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

Get a test token via Client Credentials flow or Auth0 Dashboard → APIs → Test tab.

Common Mistakes

Scope-Based Authorization

See Integration Guide [blocked] for defining and enforcing scope-based access control via filter chain, @PreAuthorize, or programmatic checks.

DPoP Support

Built-in proof-of-possession token binding per RFC 9449. See Integration Guide [blocked] for configuration modes (DISABLED, ALLOWED, REQUIRED).

Related Skills

• auth0-quickstart — Basic Auth0 setup and account creation
• auth0-java — Spring Boot web apps with login UI (Regular Web Application)

Quick Reference

Configuration Properties (application.yml):

• auth0.domain — Auth0 tenant domain, no https:// prefix (required)
• auth0.audience — API Identifier from Auth0 API settings (required)
• auth0.dpop-mode — DPoP mode: DISABLED, ALLOWED (default), REQUIRED
• auth0.dpop-iat-offset-seconds — DPoP proof time window (default: 300)
• auth0.dpop-iat-leeway-seconds — DPoP proof time leeway (default: 30)

User Claims (via Auth0AuthenticationToken):

• authentication.getName() — User ID (subject / sub claim)
• token.getClaim("email") — Any specific claim by name
• token.getClaims() — All JWT claims as Map<String, Object>
• token.getScopes() — Scopes as Set<String>

Common Use Cases:

• Protect routes → requestMatchers("/path").authenticated() (see Step 4)
• Scope enforcement → hasAuthority("SCOPE_read:data") or @PreAuthorize (see Integration Guide [blocked])
• DPoP token binding → Integration Guide [blocked]
• Complete API reference → API Reference [blocked]

Detailed Documentation

• Setup Guide [blocked] — Auth0 CLI automation, environment configuration, secret management
• Integration Guide [blocked] — Scope policies, DPoP, controller patterns, error handling
• API Reference [blocked] — Complete configuration options, claims reference, testing checklist

References

• Auth0 Java Spring Security API Quickstart
• SDK GitHub Repository
• Spring Security Documentation
• Access Tokens Guide
• DPoP RFC 9449