Java Springboot API - Auth0 Docs

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

Use AI to integrate Auth0

If you use an AI coding assistant like Claude Code, Cursor, or GitHub Copilot, you can add Auth0 authentication automatically in minutes using agent skills.Install:

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

Then ask your AI assistant:

Add Auth0 JWT authentication to my Spring Boot API

Your AI assistant will automatically create your Auth0 API, fetch credentials, add the Auth0 Spring Boot API SDK dependency, configure application.yml, and implement a SecurityFilterChain with JWT validation and protected endpoints. Full agent skills documentation →

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.

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

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

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:

CLI
Dashboard

Run the following shell command on your project’s root directory to create an Auth0 API and update your application.yml file:

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"

Before you start, add Auth0 configuration to your src/main/resources/application.yml file

src/main/resources/application.yml

auth0:
  domain: "YOUR_AUTH0_DOMAIN"
  audience: "YOUR_AUTH0_API_IDENTIFIER"

spring:
  application:
    name: auth0-api

Go to Auth0 Dashboard → Applications → APIs
Choose Create API
Enter your API details:
- Name: My Spring Boot API
- Identifier: https://my-springboot-api (this becomes your Audience)
- Signing Algorithm: RS256
Choose Create
Replace YOUR_AUTH0_DOMAIN in application.yml with your Domain from the Test tab (e.g., your-tenant.auth0.com)
Replace YOUR_AUTH0_API_IDENTIFIER in application.yml with your Identifier. For example https://my-springboot-api.

Your Domain should not include https://. Use only the domain and region. For example: your-tenant.auth0.com.The Audience (API Identifier) is a unique identifier for your API and can be any valid URI. It doesn’t need to be a publicly accessible URL.

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

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

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

Calling Protected APIs

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'

Accessing JWT Claims

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

Scope-Based Authorization

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

DPoP Enhanced Security

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

401 Unauthorized - Invalid audience

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"

401 Unauthorized - Invalid issuer

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"

Configuration values not found

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

Filter order issues

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)

Network connectivity issues

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

Scopes not working in authorization policies

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

​Get Started

​Advanced Usage

​Common Issues

​Additional Resources

SDK Documentation

Code Examples

DPoP Documentation

Spring Security Reference

Auth0 Dashboard

Community Forum

​Sample Application

Playground Application

Get Started

Advanced Usage

Common Issues

Additional Resources

Sample Application