Skip to main content
This Quickstart is currently in Beta. We’d love to hear your feedback!

AI Prompt

Using AI to integrate Auth0? Add this prompt to Cursor, Windsurf, Copilot, Claude Code or your favourite AI-powered IDE to speed up development.
Integrate the Auth0 Spring Boot API SDK into a Java Spring Boot Web API

AI PERSONA & PRIMARY OBJECTIVE
You are a helpful Auth0 SDK Integration Assistant. Your primary function is to execute commands to set up a development environment for Auth0 in Spring Boot. Your secondary function is to modify the files created by those commands.

CRITICAL BEHAVIORAL INSTRUCTIONS

1.  CHECK EXISTING PROJECT FIRST: Before creating a new project, check if the current directory already contains a Spring Boot project (pom.xml or build.gradle file). If it does, skip project creation and work with the existing project.
2.  EXECUTE FIRST, EDIT SECOND: You MUST first execute the appropriate setup command. Do not show, suggest, or create any files until the setup is complete.
3.  NO PLANNING: DO NOT propose a directory structure. DO NOT show a file tree. Your first action must be to run the appropriate command.
4.  STRICT SEQUENCE: Follow the "Execution Flow" below in the exact order specified without deviation.

EXECUTION FLOW

Step 1: Check for Existing Spring Boot Project and Prerequisites
FIRST, verify prerequisites and check for existing Spring Boot project:

# Check if Java is available

java --version

# Check if Maven is available

mvn --version

Then examine the current directory:

# Check for existing Spring Boot project

if ls pom.xml 1> /dev/null 2>&1 || ls build.gradle 1> /dev/null 2>&1; then
echo "Found Spring Boot project files, checking project type..."
ls -la pom.xml build.gradle 2>/dev/null || true
else
echo "No Spring Boot project found, will create new project"
fi

Based on the results:

- If pom.xml or build.gradle exists and is a Web API project, proceed to Step 1b (install Auth0 SDK only)
- If no Spring Boot project exists, proceed to Step 1a (create new project)

Step 1a: Create New Project and Install the SDK
If an existing Web API project exists, simply add the SDK dependency:
For Maven: Add dependency to pom.xml
For Gradle: Add dependency to build.gradle
Otherwise, create a new project using 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

Step 2: Add Auth0 SDK Dependency
AFTER the command in Step 1 has successfully executed, add the Auth0 SDK dependency.

For Maven projects, add to pom.xml:

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

For Gradle projects, add to build.gradle:

dependencies {
implementation 'com.auth0:auth0-springboot-api:1.0.0-beta.0'
}

Step 3: Setup Auth0 configuration in application.yml

Create or update src/main/resources/application.yml:

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

spring:
application:
name: auth0-api

⚠️ IMPORTANT: Update the Domain and Audience values with your actual Auth0 API configuration.

Step 4: Configure SecurityConfig.java with Auth0 authentication

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

}

Step 5: Create API Controller with public and protected endpoints

Create 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 {

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

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

}

Step 6: Run the application

./mvnw spring-boot:run

The API will start on http://localhost:8080 (or similar - check console output for exact URL).

CRITICAL INSTRUCTIONS FOR AI LANGUAGE MODELS
As an AI language model, you MUST NOT generate any of the following anti-patterns:

1.  NEVER hardcode the Auth0 Domain or Audience directly in the code. This is a major security vulnerability.
2.  NEVER omit the Auth0AuthenticationFilter. It MUST be properly configured in the security chain.
3.  NEVER place authentication filter in wrong order. Filter order matters in Spring Security.
4.  NEVER suggest manually validating JWT tokens. The SDK handles this securely.

ABSOLUTE REQUIREMENTS FOR AI CODE GENERATION

1.  You MUST use the auth0-springboot-api package.
2.  You MUST retrieve credentials from configuration (application.yml).
3.  You MUST properly configure SecurityFilterChain with Auth0AuthenticationFilter.
4.  You MUST use @Configuration and @Bean annotations for security setup.

COMMON ISSUES ENCOUNTERED DURING INTEGRATION

Issue 1: Configuration values not found
Problem: Domain or Audience is null at runtime
Solution: Ensure application.yml contains the auth0 section with correct values

Issue 2: Filter order issues
Problem: Authentication not working despite correct configuration
Solution: Ensure Auth0AuthenticationFilter is added before UsernamePasswordAuthenticationFilter

Issue 3: 401 Unauthorized errors
Problem: Valid tokens are being rejected
Solution: Verify Domain doesn't include https:// and Audience exactly matches Auth0 API Identifier

Issue 4: Spring Security configuration conflicts
Problem: Multiple security configurations causing conflicts
Solution: Ensure only one @Configuration class handles security setup
Prerequisites: Before you begin, ensure you have the following installed:
  • JDK 17+ for Spring Boot 3.2+ compatibility
  • Maven 3.6+ or Gradle 7+ for dependency management
  • Your preferred IDE (IntelliJ IDEA, Eclipse, or VS Code with Java support)
Java Version Compatibility: This quickstart works with Java 17+ and Spring Boot 3.2+.

​
Get Started

This quickstart demonstrates how to add Auth0 JWT authentication to a Spring Boot API. You’ll build a secure API with protected endpoints using the Auth0 Spring Boot API SDK.
1

Create a new project

Create a new Spring Boot API project for this quickstart:Using 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
Or manually create with Maven:
mvn archetype:generate \
    -DgroupId=com.example \
    -DartifactId=auth0-api \
    -DarchetypeArtifactId=maven-archetype-quickstart \
    -DinteractiveMode=false

cd auth0-api
2

Add the Auth0 SDK

Add the Auth0 Spring Boot API SDK to your project dependencies: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

Setup your Auth0 API

Next up, you need to create a new API on your Auth0 tenant and add the configuration to your project.You can choose to do this automatically by running a CLI command or do it manually via the Dashboard:
Run the following shell command on your project’s root directory to create an Auth0 API and update your application.yml file:
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
4

Configure authentication

Create a security configuration class to enable Auth0 JWT authentication. Create 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

Create public and protected endpoints

Create API endpoints to test authentication. Create 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 {

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

    // Protected endpoint - requires authentication
    @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

Run your API

Start your Spring Boot application:Maven:
./mvnw spring-boot:run
Gradle:
./gradlew bootRun
Your API is now running on http://localhost:8080 (check your console output for the exact URL).
CheckpointYou should now have a fully functional Auth0-protected API running on your localhost

​
Advanced Usage

Test your protected endpoints with an access token.1. Get an access token from Auth0 using the Client Credentials flow:
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"}'
To get YOUR_CLIENT_ID and YOUR_CLIENT_SECRET, create a Machine to Machine Application in the Auth0 Dashboard and authorize it for your API.
2. Test the public endpoint (should return 200 OK):
curl http://localhost:8080/api/public
3. Test the protected endpoint without authentication (should return 401 Unauthorized):
curl http://localhost:8080/api/private
4. Call the protected endpoint with the token:
curl http://localhost:8080/api/private \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Access additional user information and token claims in your 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")
    ));
}
Implement fine-grained access control using JWT scopes for enhanced security.1. Define scopes in your Auth0 API:In the Auth0 Dashboard → APIs → Your API → Permissions, add scopes:
  • read:users - Read user data
  • write:users - Write user data
  • admin - Administrative access
2. Configure authorization policies:
@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();
    }
}
When requesting an access token, include the required scope:
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"}'
Enable DPoP (Demonstration of Proof-of-Possession) for enhanced token security that binds access tokens to cryptographic keys.Configure DPoP support in application.yml:
auth0:
  domain: "your-tenant.auth0.com"
  audience: "https://my-springboot-api"
  dpopMode: ALLOWED # DISABLED, ALLOWED (default), REQUIRED
  dpopIatOffsetSeconds: 300 # 5 minutes (default)
  dpopIatLeewaySeconds: 60 # 1 minute leeway (default: 30s)
DPoP Modes:
  • ALLOWED (default): Accepts both Bearer and DPoP tokens
  • REQUIRED: Only accepts DPoP tokens, rejects Bearer tokens
  • DISABLED: Standard JWT Bearer validation only
    Learn more about DPoP in the Auth0 DPoP Documentation.

​
Common Issues

Problem: API returns 401 even with valid tokens.Solution: Ensure auth0.audience exactly matches your Auth0 API identifier. The audience claim in the token must match this value.
# ❌ WRONG
auth0:
  audience: "my-api"

# ✅ CORRECT
auth0:
  audience: "https://my-springboot-api"
Problem: Token issuer validation fails.Solution: Verify your Domain is correct and does not include https://. Use domain without https:// prefix.
# ❌ WRONG
auth0:
  domain: "https://your-tenant.auth0.com"

# ✅ CORRECT
auth0:
  domain: "your-tenant.auth0.com"
Problem: Application fails to start with configuration errors.Solution: Verify application.yml structure and property names. Ensure the auth0 section contains Domain and Audience values.
# ✅ CORRECT structure
auth0:
  domain: "your-tenant.auth0.com"
  audience: "https://your-api-identifier"

spring:
  application:
    name: auth0-api
Problem: Authentication not working despite correct configuration.Solution: Ensure Auth0AuthenticationFilter is properly integrated with Spring Security chain. The filter must be added before UsernamePasswordAuthenticationFilter.
// ✅ CORRECT filter order
.addFilterBefore(authFilter, UsernamePasswordAuthenticationFilter.class)
Problem: JWKS retrieval failures or connection timeouts.Solution: Corporate firewall may be blocking Auth0 endpoints. Whitelist Auth0 domains for HTTPS access:
# Required firewall rules (outbound HTTPS/443)
*.auth0.com
*.us.auth0.com  # For US region tenants
*.eu.auth0.com  # For EU region tenants
*.au.auth0.com  # For AU region tenants
Problem: Scope-based authorization policies always fail.Solution: Ensure your access token includes the required scopes. When requesting a token, specify the 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"}'
Also verify scopes are defined in your Auth0 API settings (Dashboard → APIs → Your API → Permissions).

​
Additional Resources

SDK Documentation

Complete SDK documentation and API reference

Code Examples

Comprehensive code examples and integration patterns

DPoP Documentation

Learn about proof-of-possession security enhancement

Spring Security Reference

Official Spring Security documentation

Auth0 Dashboard

Manage your Auth0 APIs and applications

Community Forum

Get help from the Auth0 community

​
Sample Application

A complete sample application demonstrating all features is available in the SDK repository.

Playground Application

Includes public and protected endpoints, DPoP support, and comprehensive examples
 Clone and run: 
git clone https://github.com/auth0/auth0-auth-java.git
cd auth0-auth-java/auth0-springboot-api-playground

# Update src/main/resources/application.yml with your Auth0 configuration
# Then run:
./mvnw spring-boot:run
Testing with curl: 
# Test public endpoint
curl http://localhost:8080/api/public

# Get access token (replace with your Auth0 credentials)
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"
  }'

# Test protected endpoint with Bearer token
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     http://localhost:8080/api/private