Spring Boot + Auth0 实现 API 安全与授权：OAuth2 与 RBAC 完整指南

一. 引言

了解如何使用 Spring Boot、Java 和 Auth0 为 API 添加授权功能，确保其安全性和功能完整性。本文将通过实践示例，讲解如何在 Spring Boot API 中实现 OAuth2 授权和基于角色的访问控制（RBAC）。

二. Web 上的身份验证与授权

1. 身份验证 vs 授权

身份验证：验证用户身份，确认用户是否为其声称身份。
授权：赋予用户访问特定资源的权限。

2. OAuth 2.0

OAuth 2.0 是一种授权框架，通过访问令牌来授权访问受保护资源。访问令牌通常包含访问范围（scope）和有效期，资源服务器验证令牌后决定是否允许访问。
OAuth 2.0 定义了以下角色及流程：

资源所有者（Resource Owner）
资源服务器（Resource Server）
客户端（Client）
授权服务器（Authorization Server）

客户端通过授权服务器请求资源访问，并获得访问令牌。

3. OpenID Connect

OpenID Connect 建立在 OAuth2 之上，通过返回 JWT 格式的 ID 令牌，提供身份验证信息。客户端向 OpenID 提供者发送请求，验证用户身份后，返回 ID 令牌和访问令牌。

三. 在 Spring Boot API 中实现授权

假设您已有一个 Spring Boot 菜单 API，需要确保只有授权用户才能访问端点。

1. 克隆 API 存储库

git clone https://github.com/oktadev/spring-menu-api.git

存储库包含两个项目文件夹：“start”和“demo”。

start：未配置安全性的基础项目
demo：包含完整安全配置，可直接运行

2. 注册 API 并配置作用域

使用 Auth0 CLI 注册 API，并定义作用域：

auth0 apis create \
  --name "Menu API" \
  --identifier https://menu-api.okta.com \
  --scopes "create:items,update:items,delete:items" \
  --offline-access=false

3. 添加依赖项

在 build.gradle 文件中添加：

dependencies {
  implementation 'com.okta.spring:okta-spring-boot-starter:3.0.6'
}

4. 配置 OAuth2 资源服务器

在 application.properties 中添加：

okta.oauth2.issuer=https://YOUR_OKTA_DOMAIN/oauth2/default
okta.oauth2.audience=https://menu-api.okta.com

5. 测试 API 授权

运行 API 并测试未授权访问：

curl -i localhost:8080/api/menu/items

如果未提供访问令牌，将返回 HTTP 401。
使用 Auth0 CLI 获取访问令牌：

auth0 test token -a https://menu-api.okta.com -s openid

带令牌访问 API：

ACCESS_TOKEN=<your_token>
curl -i --header "Authorization: Bearer $ACCESS_TOKEN" localhost:8080/api/menu/items

四. 从单页应用程序（SPA）测试身份验证

auth0 apps create \
  --name "WHATABYTE client" \
  --description "Single-Page Application for menu items CRUD" \
  --type spa \
  --callbacks https://dashboard.whatabyte.app/home \
  --logout-urls https://dashboard.whatabyte.app/home \
  --origins https://dashboard.whatabyte.app \
  --web-origins https://dashboard.whatabyte.app

1. 配置 CORS

在 Spring Boot 控制器中允许跨域请求：

@CrossOrigin(origins = "https://dashboard.whatabyte.app")
@RestController
@RequestMapping("/api/menu/items")
public class ItemController {
  // 控制器代码
}

五. 基于角色的访问控制（RBAC）

RBAC 通过角色分配权限，实现细粒度的授权。

1. 创建和分配角色

在 WHATABYTE 客户端启用 RBAC，创建角色“菜单管理员”，并将角色分配给用户：

auth0 users roles assign

2. 将角色映射到令牌声明

使用 Auth0 动作（Actions）将角色映射到访问令牌：

exports.onExecutePostLogin = async (event, api) => {
  const namespace = 'https://menu-api.okta.com';
  if (event.authorization) {
    api.accessToken.setCustomClaim(${namespace}/roles, event.authorization.roles);
  }
};

3. 启用 RBAC

为 API 启用 RBAC 并分配权限：

auth0 api patch "resource-servers/" \
  --data '{ "enforce_policies": true, "token_dialect": "access_token_authz" }'

auth0 roles permissions add

六. 在 Spring Boot API 中实现 RBAC

在 application.properties 添加角色映射：

okta.oauth2.groupsClaim=permissions

使用 @PreAuthorize 注解定义端点权限：

@PreAuthorize("hasAuthority('create:items')")
@PostMapping
public ResponseEntity createItem(@Valid @RequestBody Item item) {
  // 创建逻辑
}

启用全局方法安全性：

@Configuration
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class SecurityConfig {
  @Bean
  public SecurityFilterChain configure(HttpSecurity http) throws Exception {
    return http.oauth2ResourceServer(oauth2ResourceServer -> oauth2ResourceServer.jwt()).build();
  }
}

重启 API，用户即可根据角色权限访问资源。