Spring Security OAuth2 组件

我们来系统地讲解一下 Spring Security OAuth2 这个强大的组件。我会从概念、作用、核心组件，以及实际应用场景来为你剖析。

1. 什么是 Spring Security OAuth2？

简单来说，Spring Security OAuth2 是 Spring Security 框架的一个模块，专门用来帮助你在 Spring 应用中轻松实现 OAuth 2.0 和 OpenID Connect 1.0 (OIDC) 协议。

它的核心目标不是传统的用户名密码认证，而是授权委托 (Delegated Authorization)。

2. 为什么要用 OAuth2？（一个经典比喻）

想象一下这个场景：

你入住了一家酒店，你想让酒店的保洁服务帮你打扫房间，但你又不想把你的钱包和身份证（最高权限）直接给保洁员。

你会怎么做？

你会去前台，验证你的身份后，前台会给你一张房卡。这张房卡有以下特点：

权限有限：只能打开你的房间门，不能打开其他房间，也不能去酒店金库。
有有效期：通常只在你入住期间有效。
可以吊销：如果你丢失了房卡，可以去前台挂失，让旧卡失效。

在这个比喻中：

你 (Resource Owner)：资源的所有者（你的房间）。
保洁服务 (Client)：想要访问你资源的第三方应用。
酒店前台 (Authorization Server)：负责认证你的身份，并给你授权（发房卡）的认证中心。
你的房间 (Resource Server)：存放着受保护的资源（需要用房卡才能进入）。
房卡 (Access Token)：一个带有时效和特定权限的“令牌”。

OAuth2 就是这个“发房卡”的标准化流程。它允许用户（你）授权一个第三方应用（保洁服务）去访问他们存储在另一个服务（你的房间）上的私有资源，而无需将用户的凭证（用户名和密码）直接暴露给第三方应用。

3. Spring Security OAuth2 的核心组件（现代架构）

在现代 Spring Boot 应用中（Spring Boot 2.x 及以上），Spring Security OAuth2 的功能被清晰地拆分成了几个独立的组件。这一点非常重要，因为网上很多旧的教程已经过时。

历史演进（重要！）

旧版 (spring-security-oauth2-autoconfigure)：曾提供 @EnableAuthorizationServer、@EnableResourceServer 等注解，将授权服务器、资源服务器等功能耦合在一起。这个库现在已经废弃，不推荐在新项目中使用。
新版（推荐）：功能被拆分，更加清晰和专注。
- 授权服务器 (Authorization Server)：独立为一个新项目 Spring Authorization Server。当你需要自己构建一个认证中心（比如自家的“统一登录平台”）时使用。
- 客户端 (Client)：由 spring-boot-starter-oauth2-client 提供。
- 资源服务器 (Resource Server)：由 spring-boot-starter-oauth2-resource-server 提供。

在绝大多数业务场景中，我们主要使用 客户端 和 资源服务器 这两个角色。

4. 两大核心应用场景及实现

场景一：作为客户端 (OAuth2 Client)

目的：让你的应用去访问一个受 OAuth2保护的资源，或者实现“通过第三方登录”的功能。

例子：

你的网站需要一个“使用 GitHub/Google 账号登录”的功能。
你的后端服务需要调用 GitHub API 来获取用户的仓库列表。

如何实现？

添加依赖：

<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-oauth2-client</artifactId>
</dependency>

content_copydownload

Use code with caution.Xml

配置 application.yml：
在这里配置第三方认证服务商（如 GitHub）提供给你的信息。
```
spring:security:oauth2:client:registration:github: # "github" 是一个自定义的注册IDclient-id: your-github-client-idclient-secret: your-github-client-secretscope: read:user # 想要获取的权限
```
content_copydownload
Use code with caution.Yaml
Spring Boot 已经为常见的服务商（Google, GitHub, Facebook, Okta）预设了很多配置，你只需要提供 client-id 和 client-secret 即可。
配置安全规则 SecurityFilterChain：
```
@Configuration
@EnableWebSecurity
public class SecurityConfig {@Beanpublic SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {http.authorizeHttpRequests(authorize -> authorize.anyRequest().authenticated() // 所有请求都需要认证).oauth2Login(Customizer.withDefaults()); // 启用 OAuth2 登录流程return http.build();}
}
```
content_copydownload
Use code with caution.Java
仅仅添加 .oauth2Login()，Spring Security 就会自动为你完成以下所有事情：
- 创建一个默认的登录入口 /oauth2/authorization/github。
- 当用户访问受保护的页面时，自动重定向到 GitHub 的授权页面。
- 用户在 GitHub 授权后，处理回调请求（redirect-uri）。
- 用授权码（Authorization Code）换取访问令牌（Access Token）。
- 使用 Access Token 去获取用户信息。
- 将用户信息包装成一个 Authentication 对象，放入 SecurityContextHolder，完成登录。

场景二：作为资源服务器 (Resource Server)

目的：保护你的 API，只允许持有有效令牌（Access Token）的客户端访问。

例子：

你有一个前后端分离的项目，前端（如 Vue/React）在登录后获取一个 Token。
前端每次请求后端的 API 时，都必须在请求头中携带这个 Token。
你的后端（Spring Boot 应用）需要验证这个 Token 的有效性。

如何实现？

添加依赖：

<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>

content_copydownload

Use code with caution.Xml

配置 application.yml：
你需要告诉资源服务器如何验证 Token。最常见的方式是使用 JWT (JSON Web Token)。你需要提供授权服务器的公钥地址（jwk-set-uri），以便验证 JWT 的签名。
```
spring:security:oauth2:resourceserver:jwt:# 你的授权服务器（如 Keycloak, Auth0, 或自建的 Spring Authorization Server）的 JWK Set URIjwk-set-uri: https://your-auth-server.com/.well-known/jwks.json
```
content_copydownload
Use code with caution.Yaml
配置安全规则 SecurityFilterChain：
```
@Configuration
@EnableWebSecurity
public class SecurityConfig {@Beanpublic SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {http.authorizeHttpRequests(authorize -> authorize.requestMatchers("/api/public").permitAll() // 公开API.anyRequest().authenticated() // 其他API需要认证)// 启用 OAuth2 资源服务器功能，并指定使用 JWT 进行验证.oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults())); return http.build();}
}
```
content_copydownload
Use code with caution.Java
添加 .oauth2ResourceServer() 后，Spring Security 会：
- 自动配置一个过滤器，检查所有进来的请求的 Authorization 请求头。
- 期望的格式是 Authorization: Bearer <your-jwt-token>。
- 如果找到 Token，它会使用配置的 jwk-set-uri 来获取公钥，并验证 Token 的签名、有效期（exp）、颁发者（iss）等信息。
- 如果验证通过，它会从 Token 中解析出用户权限（scope 或 scp），并创建一个 Authentication 对象，授权访问。
- 如果 Token 无效或不存在，则拒绝访问（返回 401 Unauthorized）。

5. 整体流程示例（前后端分离应用）

一个典型的现代 Web 应用流程如下：

用户在前端应用（Client）上点击“登录”。
前端应用将用户重定向到授权服务器（如 Auth0, Keycloak, 或自建的 Spring Authorization Server）。
用户在授权服务器上输入用户名和密码。
授权服务器验证成功后，将用户重定向回前端应用，并附带一个 Access Token (通常是 JWT)。
前端应用存储这个 Token（例如，在 localStorage 中）。
当用户要访问后端受保护的 API 时，前端应用在 HTTP 请求的 Authorization 头中携带这个 Token：Authorization: Bearer <token>。
Spring Boot 后端（Resource Server）接收到请求。
Spring Security 的 oauth2ResourceServer 过滤器拦截请求，提取 Token。
它根据 jwk-set-uri 配置，从授权服务器获取公钥，验证 Token 的签名和声明。
验证成功：请求被放行到对应的 Controller 方法，业务逻辑继续执行。
验证失败：请求被拦截，返回 401 错误。

总结

Spring Security OAuth2 是实现 OAuth 2.0 协议栈的官方 Spring 模块，用于构建安全的、基于令牌的授权系统。
它解决了授权委托问题，避免了密码的直接共享。
现代架构下，其功能主要分为客户端 (Client) 和资源服务器 (Resource Server)，而授权服务器 (Authorization Server) 是一个独立的项目。
作为 Client (spring-boot-starter-oauth2-client)：用于实现“第三方登录”或调用外部受保护的 API。核心配置是 .oauth2Login()。
作为 Resource Server (spring-boot-starter-oauth2-resource-server)：用于保护你自己的 API，验证外部传入的 Token。核心配置是 .oauth2ResourceServer()。
对于新项目，请务必使用新的、模块化的依赖，而不是已经废弃的旧版。