230 lines
10 KiB
Markdown
230 lines
10 KiB
Markdown
---
|
||
tags: [sso, oauth2, auth]
|
||
create time: 2026-07-13 10:03
|
||
---
|
||
|
||
# OAuth 2.0 授权码模式
|
||
|
||
## 概述
|
||
|
||
假设你在开发一个「周报助手」应用，需要读取用户的 Google 日历来自动安排会议。你不可能让用户把 Google 密码告诉你——这既不安全，也不合理。你需要的只是**有限度地访问用户的日历数据**。
|
||
|
||
**OAuth 2.0（RFC 6749）** 就是解决这个问题的框架：让用户**授权**第三方应用访问自己的部分资源，而不需要交出密码。
|
||
|
||
> [!info] 认证（Authentication）vs 授权（Authorization）
|
||
> 这是两个经常混淆的概念：
|
||
> - **认证**：证明「你是谁」→ 比如出示身份证，回答「我是张三」
|
||
> - **授权**：决定「你能干什么」→ 比如张三可以查看日历，但不能删除日历
|
||
>
|
||
> **OAuth 2.0 只解决授权**。它能拿到你的日历数据，但不知道（也不关心）登录的用户是张三还是李四。后来 OIDC 在 OAuth 2.0 之上补了认证，才实现了完整的 SSO。
|
||
|
||
## 核心角色
|
||
|
||
OAuth 2.0 定义了四个角色（比 SSO 主文档多了一个 Resource Server）：
|
||
|
||
| 角色 | 说明 | 生活类比 |
|
||
|------|------|----------|
|
||
| **Resource Owner** | 资源的拥有者，就是用户本人 | 房子的主人 |
|
||
| **Client** | 请求访问资源的第三方应用 | 要借住的朋友 |
|
||
| **Authorization Server** | 授权服务器，负责认证用户、颁发 Token | 物业管理处 |
|
||
| **Resource Server** | 存放资源的 API 服务 | 你的房子 |
|
||
|
||
> [!tip] 为什么 Authorization Server 和 Resource Server 要分开？
|
||
> 在小型系统中它们通常是同一个服务。但在大型架构中，认证是一个独立的基础设施（如 Keycloak），业务 API 可能有几十个。分离后，所有 API 共享同一个认证中心。
|
||
|
||
## 授权码模式完整流程
|
||
|
||
这是 OAuth 2.0 中最安全、最常用的模式。我们用「周报助手访问 Google 日历」这个场景来走一遍：
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant U as 用户 (浏览器)
|
||
participant App as 周报助手 (Client)
|
||
participant Google as Google 授权服务器
|
||
participant Cal as Google 日历 API
|
||
|
||
U->>App: 1. 点击「关联 Google 日历」
|
||
App->>U: 2. 浏览器跳转到 Google 登录页
|
||
Note right of App: URL 携带 client_id、scope、<br/>redirect_uri、state 参数
|
||
U->>Google: 3. 登录 Google 账号
|
||
Google->>U: 4. 展示授权页面：「周报助手想要读取你的日历」
|
||
U->>Google: 5. 点击「允许」
|
||
Google->>U: 6. 浏览器跳回周报助手的回调地址
|
||
Note left of Google: URL 携带一次性授权码 code 和 state
|
||
U->>App: 7. 周报助手收到 code
|
||
App->>Google: 8. 后端用 code + client_secret 换 Token
|
||
Note right of App: 这一步是后端直连 Google，<br/>不经过浏览器
|
||
Google-->>App: 9. 返回 access_token（+ 可选的 refresh_token）
|
||
App->>Cal: 10. 用 access_token 请求日历数据
|
||
Cal-->>App: 11. 返回日历事件
|
||
```
|
||
|
||
**为什么这么绕？关键设计：**
|
||
|
||
1. **步骤 2-7 走浏览器跳转**（用户能看到）—— 让用户亲自在 Google 页面登录和授权，密码不会经过第三方应用
|
||
2. **步骤 8-9 走后端直连**（用户看不到）—— `code` 换 `token` 的过程在后端完成，`token` 不会暴露在浏览器地址栏中
|
||
3. **`code` 只能用一次**，有效期通常 < 10 分钟，即使被截获也无法使用
|
||
|
||
### 关键参数说明
|
||
|
||
步骤 2 的跳转 URL 大致长这样：
|
||
|
||
```
|
||
https://accounts.google.com/o/oauth2/v2/auth
|
||
?client_id=abc123 ← 你在 Google 注册的应用 ID
|
||
&redirect_uri=https://app.example.com/callback ← 回调地址（注册时填好的）
|
||
&scope=https://www.googleapis.com/auth/calendar.readonly ← 请求的权限范围
|
||
&state=xyz789 ← 防 CSRF 的随机字符串
|
||
&response_type=code ← 告诉 Google 我要授权码模式
|
||
```
|
||
|
||
| 参数 | 说明 |
|
||
|------|------|
|
||
| `client_id` | 应用在授权服务器注册时获得的 ID，类似「应用的身份证号」 |
|
||
| `client_secret` | 应用密钥，只有后端知道，绝不能暴露到前端 |
|
||
| `redirect_uri` | 授权完成后浏览器跳回的地址，必须和注册时完全一致 |
|
||
| `scope` | 请求的权限范围，如「只读日历」「读写日历」。范围越小，用户越信任 |
|
||
| `state` | 随机字符串，用于防 CSRF 攻击。回调时 Google 会原样返回，你比对一下就知道是不是你发起的请求 |
|
||
| `code` | 一次性授权码，用来换 Token，用完即废 |
|
||
|
||
## Access Token vs Refresh Token
|
||
|
||
授权服务器通常返回两个 Token：
|
||
|
||
```mermaid
|
||
graph LR
|
||
A[用户授权] --> B[授权服务器]
|
||
B -->|颁发| C[Access Token]
|
||
B -->|颁发| D[Refresh Token]
|
||
C -->|有效期短<br/>5-30 分钟| E[调用 API]
|
||
D -->|有效期长<br/>几天到几个月| F[换新的 Access Token]
|
||
F -.->|每次刷新，旧的 RT 作废| D
|
||
```
|
||
|
||
| Token | 用途 | 有效期 | 存储建议 |
|
||
|-------|------|--------|----------|
|
||
| **Access Token** | 调用 API 时放在 Header 里 | 短（5-30 分钟） | 内存中，或 HttpOnly Cookie |
|
||
| **Refresh Token** | Access Token 过期后用来续期 | 长（天 ~ 月） | 后端存储，或 HttpOnly Secure Cookie |
|
||
|
||
> [!tip] Refresh Token Rotation（轮换机制）
|
||
> 每次用 Refresh Token 换新 Token 时，授权服务器会同时颁发一个新的 Refresh Token，并使旧的失效。这样即使某个 Refresh Token 泄露，攻击者也只能用一次，第二次就会被发现。
|
||
|
||
## 四种授权模式对比
|
||
|
||
除了授权码模式，OAuth 2.0 还定义了其他几种模式。了解它们的适用场景：
|
||
|
||
| 模式 | 一句话解释 | 适用场景 | 安全性 |
|
||
|------|-----------|----------|--------|
|
||
| **授权码模式** | 用户授权 → 拿到一次性 code → 后端换 Token | Web 后端应用、SSO | 最高 |
|
||
| **授权码 + PKCE** | 在授权码基础上加一个动态验证码，防止 code 被截获 | SPA（前端单页应用）、移动端 | 高 |
|
||
| **客户端凭证** | 没有用户参与，应用直接用自己的身份换 Token | 服务间调用（M2M），如定时任务调 API | 中 |
|
||
| ~~隐式模式~~ | Token 直接返回到浏览器地址栏 | **已弃用**，仅遗留系统 | 低 |
|
||
|
||
> [!warning] 什么是 PKCE？
|
||
> PKCE（Proof Key for Code Exchange，发音 "pixy"）解决的是 SPA 和移动端无法安全存储 `client_secret` 的问题。
|
||
>
|
||
> 原理：客户端先生成一个随机的 `code_verifier`，对其做哈希得到 `code_challenge`。授权请求时带上 `code_challenge`，换 Token 时带上原始的 `code_verifier`。授权服务器验证哈希是否匹配。即使攻击者截获了 `code`，没有 `code_verifier` 也换不到 Token。
|
||
>
|
||
> **新项目做 SPA/移动端，一律用 PKCE，不要用隐式模式。**
|
||
|
||
## Go 实现示例
|
||
|
||
使用标准库 `golang.org/x/oauth2` 实现完整的授权码流程：
|
||
|
||
```go
|
||
import (
|
||
"context"
|
||
"crypto/rand"
|
||
"encoding/hex"
|
||
"golang.org/x/oauth2"
|
||
)
|
||
|
||
// 1. 配置 OAuth2 客户端（通常从环境变量或配置文件读取）
|
||
conf := &oauth2.Config{
|
||
ClientID: "your-client-id",
|
||
ClientSecret: "your-client-secret",
|
||
// scope：请求哪些权限。这里请求读取用户基本信息
|
||
Scopes: []string{"profile", "email"},
|
||
Endpoint: oauth2.Endpoint{
|
||
AuthURL: "https://idp.example.com/oauth/authorize",
|
||
TokenURL: "https://idp.example.com/oauth/token",
|
||
},
|
||
// 授权完成后，IdP 会把浏览器重定向到这个地址
|
||
RedirectURL: "https://app.example.com/callback",
|
||
}
|
||
|
||
// 2. 处理「登录」按钮点击 — 生成授权 URL 并跳转
|
||
func handleLogin(w http.ResponseWriter, r *http.Request) {
|
||
// 生成随机 state 防 CSRF，存入 session 以便回调时比对
|
||
state := generateRandomState()
|
||
session, _ := store.Get(r, "session")
|
||
session.Values["oauth_state"] = state
|
||
session.Save(r, w)
|
||
|
||
// AccessTypeOffline 表示我们需要 Refresh Token（默认只给 Access Token）
|
||
authURL := conf.AuthCodeURL(state, oauth2.AccessTypeOffline)
|
||
http.Redirect(w, r, authURL, http.StatusFound)
|
||
}
|
||
|
||
// 3. 处理回调 — 用 code 换 Token
|
||
func handleCallback(w http.ResponseWriter, r *http.Request) {
|
||
// 校验 state，防止 CSRF 攻击
|
||
session, _ := store.Get(r, "session")
|
||
expectedState := session.Values["oauth_state"].(string)
|
||
if r.URL.Query().Get("state") != expectedState {
|
||
http.Error(w, "state mismatch: possible CSRF attack", http.StatusBadRequest)
|
||
return
|
||
}
|
||
|
||
// 用一次性授权码交换 Token（后端直连 IdP，不经过浏览器）
|
||
code := r.URL.Query().Get("code")
|
||
token, err := conf.Exchange(context.Background(), code)
|
||
if err != nil {
|
||
http.Error(w, "token exchange failed: "+err.Error(), http.StatusInternalServerError)
|
||
return
|
||
}
|
||
|
||
// token.AccessToken — 用来调 API 的短期令牌
|
||
// token.RefreshToken — 用来续期的长期令牌（如果请求了 AccessTypeOffline）
|
||
// token.Expiry — Access Token 的过期时间
|
||
|
||
// 用 Token 请求用户信息
|
||
client := conf.Client(context.Background(), token)
|
||
resp, _ := client.Get("https://idp.example.com/userinfo")
|
||
defer resp.Body.Close()
|
||
// ... 解析用户信息 ...
|
||
}
|
||
|
||
// 辅助函数：生成随机 state
|
||
func generateRandomState() string {
|
||
b := make([]byte, 16)
|
||
rand.Read(b)
|
||
return hex.EncodeToString(b)
|
||
}
|
||
```
|
||
|
||
## 常见陷阱与最佳实践
|
||
|
||
### CSRF 攻击：必须使用 state 参数
|
||
|
||
**攻击场景**：攻击者构造一个恶意链接 `https://app.example.com/callback?code=ATTACKER_CODE`，诱导用户点击。如果没有 `state` 校验，你的应用会拿攻击者的 code 去换 Token，攻击者就能冒充用户。
|
||
|
||
**防御**：生成随机 `state` 存入 session，回调时比对一致性。不一致就拒绝。
|
||
|
||
### Token 存储安全
|
||
|
||
| 位置 | 安全性 | 建议 |
|
||
|------|--------|------|
|
||
| `localStorage` | ❌ 任何 JS 代码（含 XSS）都能读取 | **不要用** |
|
||
| `sessionStorage` | ❌ 同上 | **不要用** |
|
||
| HttpOnly Cookie | ✅ JS 无法读取 | 推荐（后端设置） |
|
||
| 内存变量 | ✅ 页面刷新就丢失 | 适合短期使用 |
|
||
|
||
### redirect_uri 必须严格匹配
|
||
|
||
授权服务器对 `redirect_uri` 的校验是**精确匹配**——不支持通配符，不支持路径前缀。这是防止 Token 被发送到攻击者控制的地址。
|
||
|
||
### scope 最小化原则
|
||
|
||
只请求你真正需要的权限。用户在授权页面看到的权限列表越少，越愿意点击「允许」。`scope: "all"` 是最差的做法。
|