auth0-springboot-api

Auth0 Spring Boot API 集成

使用 com.auth0:auth0-springboot-api，通过 JWT 访问令牌验证来保护 Spring Boot API 端点。支持自动配置、基于 scope 的授权，以及内置 DPoP（RFC 9449）支持。

---

Agent 指令： 提供 SDK 设置说明前，请运行以下命令获取最新发布版本：

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

在所有依赖项代码行中使用返回的版本，而不要使用下方任何硬编码版本。如果 API 调用失败（例如尚无发布版本），请使用 1.0.0-beta.1。

先决条件

• Java 17+ 和 Spring Boot 3.2+
• Maven 3.6+ 或 Gradle 7+
• 已配置 Auth0 API（不是 Application——必须是 API 资源）
• 如果尚未设置 Auth0，请先使用 auth0-quickstart 技能

不适用场景

使用场景	推荐技能
服务端渲染的 Web 应用（带会话的 Spring MVC）	使用 auth0-java 构建带登录界面的 Spring Boot Web 应用
单页应用	使用 auth0-react、auth0-vue 或 auth0-angular 实现客户端身份验证
移动应用	使用 auth0-android 或 auth0-swift 构建原生移动应用
非 Spring Java API	使用 auth0-spring-security-api 实现纯 Spring Security

---

快速入门工作流

Agent 指令： 如果用户的提示中已提供 Auth0 凭据（域名、audience），请直接使用——跳过引导脚本和凭据相关问题。仅在缺少凭据时提供设置选项。

1. 安装 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. 创建 Auth0 API

你需要在 Auth0 中创建一个 API（而不是 Application）。

停止——继续之前先询问用户。

请准确询问以下问题，并等待用户回答后再进行任何其他操作：

“你希望如何创建 Auth0 API 资源？

1. 自动——我会运行 Auth0 CLI 脚本创建资源，并自动将值写入你的 application.yml。
2. 手动——你在 Auth0 Dashboard 中自行创建 API（或使用 auth0 apis create），并向我提供 Domain 和 Audience。

你倾向哪种方式？（1 = 自动 / 2 = 手动）”

在用户回答前，不要继续执行任何设置步骤。不要默认选择手动方式。

如果用户选择“自动”，请按照设置指南中的完整 CLI 脚本操作。自动流程会为你写入 application.yml——跳过下面的第 3 步，直接进入第 4 步。

如果用户选择“手动”，请按照设置指南中的“手动设置”部分操作。然后继续第 3 步。

手动创建 API 的快速参考：

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

也可以在 Auth0 Dashboard → Applications → APIs 中手动创建。

3. 配置 application.yml

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

重要： Domain 不得包含 https://。库会自动构造 issuer URL。

或者使用 application.properties：

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

4. 配置 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. 保护端点

@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. 测试 API

Agent 指令： 编写完所有代码后，请验证构建成功：

./gradlew bootRun

或运行 ./mvnw spring-boot:run。如果构建失败，请诊断并修复。连续尝试失败 5–6 次后，请使用 AskUserQuestion 寻求帮助。

测试公开端点：

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

测试受保护端点（需要访问令牌）：

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

通过 Client Credentials 流程或 Auth0 Dashboard → APIs → Test 选项卡获取测试令牌。

---

常见错误

错误	修复方法
域名包含 https://	仅使用 your-tenant.auth0.com 格式，不要加方案前缀
Audience 与 API Identifier 不匹配	必须与 Auth0 Dashboard 中设置的 API Identifier 完全一致
在 Auth0 中创建了 Application，而不是 API	必须在 Auth0 Dashboard → Applications → APIs 中创建 API 资源
SecurityConfig 中缺少 addFilterBefore	必须将 Auth0AuthenticationFilter 添加在 UsernamePasswordAuthenticationFilter 之前
使用 ID token，而不是 access token	API 身份验证必须使用 access token，而不是 ID token
以错误格式检查 scope 声明	Scope 会映射为带 SCOPE_ 前缀的权限：使用 hasAuthority("SCOPE_read:data")
Spring Boot 环境变量绑定	使用 AUTH0_DOMAIN；属性名内部不要使用下划线。Spring 会移除连字符，且不区分大小写

---

基于 Scope 的授权

请参阅集成指南，了解如何通过过滤器链、@PreAuthorize 或编程式检查定义并实施基于 scope 的访问控制。

---

DPoP 支持

内置符合 RFC 9449 的持有证明令牌绑定。请参阅集成指南，了解配置模式（DISABLED、ALLOWED、REQUIRED）。

---

相关技能

• auth0-quickstart — Auth0 基础设置和账户创建
• auth0-java — 带有登录界面的 Spring Boot Web 应用（常规 Web 应用程序）

---

快速参考

配置属性（application.yml）：

• auth0.domain — Auth0 租户域名，不带 https:// 前缀（必填）
• auth0.audience — Auth0 API 设置中的 API Identifier（必填）
• auth0.dpop-mode — DPoP 模式：DISABLED、ALLOWED（默认值）、REQUIRED
• auth0.dpop-iat-offset-seconds — DPoP 证明时间窗口（默认值：300）
• auth0.dpop-iat-leeway-seconds — DPoP 证明时间宽限值（默认值：30）

用户声明（通过 Auth0AuthenticationToken）：

• authentication.getName() — 用户 ID（subject / sub 声明）
• token.getClaim("email") — 按名称获取特定声明
• token.getClaims() — 所有 JWT 声明，类型为 Map<String, Object>
• token.getScopes() — Scope 集合，类型为 Set<String>

常见用例：

• 保护路由 → requestMatchers("/path").authenticated()（参见步骤 4）
• Scope 强制执行 → hasAuthority("SCOPE_read:data") 或 @PreAuthorize（参见集成指南）
• DPoP 令牌绑定 → 集成指南
• 完整 API 参考 → API 参考

---

详细文档

• 设置指南 — Auth0 CLI 自动化、环境配置、密钥管理
• 集成指南 — Scope 策略、DPoP、控制器模式、错误处理
• API 参考 — 完整配置选项、声明参考、测试清单

---

参考资料

• Auth0 Java Spring Security API 快速入门
• SDK GitHub 仓库
• Spring Security 文档
• Access Token 指南
• DPoP RFC 9449