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()。
對于新項目，請務必使用新的、模塊化的依賴，而不是已經廢棄的舊版。