# Configuring Oauth2 Authorization Flow

> 配置安全的 OAuth 2.0 授权流程，包括带 PKCE 的授权码流、客户端凭据和设备授权授予。本技能涵盖流程选择、PKCE 实施、令牌生命周期管理、范围设计以及符合 OAuth 2.1 安全要求。

- Skill: `killvxk/configuring-oauth2-authorization-flow` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add killvxk/configuring-oauth2-authorization-flow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/killvxk/configuring-oauth2-authorization-flow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- License: Apache-2.0
- Author: killvxk (https://skillmd.com/u/killvxk)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/killvxk/configuring-oauth2-authorization-flow

---

# 配置 OAuth 2.0 授权流程

## 概述
配置安全的 OAuth 2.0 授权流程，包括带 PKCE（Proof Key for Code Exchange）的授权码流、客户端凭据和设备授权授予。本技能涵盖流程选择、PKCE 实施、令牌生命周期管理、范围设计以及符合 OAuth 2.1 安全要求。

## 目标
- 为公共客户端和机密客户端实施带 PKCE 的授权码流
- 为机器间通信配置客户端凭据流
- 设计最小权限范围层次结构
- 实施安全的令牌存储、刷新和撤销
- 应用 OAuth 2.1 最佳实践和 RFC 9700 安全建议
- 验证令牌完整性并防止常见 OAuth 攻击

## 核心概念

### OAuth 2.0 授权类型
1. **授权码 + PKCE**：推荐用于所有客户端类型（Web、移动、SPA）。PKCE 在 OAuth 2.1 中为强制要求。
2. **客户端凭据**：无用户上下文的机器间认证。
3. **设备授权授予（RFC 8628）**：用于输入受限设备（智能电视、CLI 工具）。
4. **刷新令牌**：长期有效的令牌，无需重新认证即可获取新访问令牌。

### PKCE（授权码交换证明密钥）
PKCE（RFC 7636）防止授权码拦截攻击：
1. 客户端生成随机 `code_verifier`（43-128 个字符，不保留 URI 字符）
2. 客户端计算 `code_challenge = BASE64URL(SHA256(code_verifier))`
3. 授权请求包含 `code_challenge` 和 `code_challenge_method=S256`
4. 令牌请求包含原始 `code_verifier`
5. 服务器验证 `SHA256(code_verifier)` 与存储的 `code_challenge` 匹配

### 令牌类型
- **访问令牌**：短期有效（5-60 分钟），bearer 或 DPoP 绑定
- **刷新令牌**：长期有效，一次性使用并轮换
- **ID 令牌（OIDC）**：包含用户身份声明的 JWT

## 实施步骤

### 步骤 1：带 PKCE 的授权码流
1. 生成加密随机 code_verifier（最少 43 个字符）
2. 使用 S256 方法计算 code_challenge
3. 使用以下参数将用户重定向到授权端点：
   - response_type=code
   - client_id、redirect_uri、scope、state
   - code_challenge、code_challenge_method=S256
4. 用户进行认证和授权
5. 授权服务器使用授权码重定向
6. 在令牌端点用 code + code_verifier 交换令牌
7. 验证 state 参数与原始值匹配

### 步骤 2：范围设计
- 定义细粒度范围：`read:users`、`write:orders`、`admin:settings`
- 遵循最小权限：只请求所需的最少范围
- 在资源服务器上实施范围验证
- 记录范围层次结构和同意要求

### 步骤 3：令牌安全
- 安全存储令牌（Web 应用使用 httpOnly Cookie，移动端使用密钥链）
- 实施带轮换的令牌刷新（一次性使用刷新令牌）
- 设置适当的过期时间：访问令牌 5-15 分钟，刷新令牌 8-24 小时
- 启用 DPoP（持有证明）用于发送方约束令牌
- 实施令牌撤销端点

### 步骤 4：客户端凭据流
1. 注册服务客户端，包含 client_id 和 client_secret
2. 请求令牌：POST /oauth/token，参数 grant_type=client_credentials
3. 包含所需权限的 scope
4. 安全存储 client_secret（保险库、环境变量，而非代码中）
5. 为更高保障级别实施基于证书的客户端认证

### 步骤 5：安全加固
- 对所有授权码流强制执行 PKCE
- 使用精确的重定向 URI 匹配（无通配符）
- 使用 state 参数实施 CSRF 保护
- 启用刷新令牌轮换，并在检测到重用时撤销
- 应用 RFC 9700 安全最佳实践
- 阻止隐式授予和 ROPC（在 OAuth 2.1 中已移除）

## 安全控制
| 控制项 | NIST 800-53 | 描述 |
|---------|-------------|-------------|
| 访问控制 | AC-3 | 基于令牌的访问执行 |
| 认证 | IA-5 | 客户端凭据管理 |
| 会话管理 | SC-23 | 令牌生命周期管理 |
| 审计 | AU-3 | 记录所有令牌颁发和撤销 |
| 加密保护 | SC-13 | PKCE 和令牌签名 |

## 常见陷阱
- 使用隐式授予（OAuth 2.1 中已移除）而非授权码 + PKCE
- 将令牌存储在 localStorage（容易受 XSS 攻击）而非 httpOnly Cookie
- 未验证 state 参数，使 CSRF 攻击成为可能
- 使用通配符重定向 URI，允许开放重定向利用
- 未实施刷新令牌轮换，导致令牌盗窃持续有效

## 验证
- [ ] 带 PKCE 的授权码流成功完成
- [ ] 在令牌端点验证了 PKCE code_challenge
- [ ] state 参数防止了 CSRF
- [ ] 访问令牌在配置的生命周期内过期
- [ ] 刷新令牌轮换在每次使用时颁发新的刷新令牌
- [ ] 令牌撤销使访问令牌和刷新令牌都失效
- [ ] 客户端凭据流适用于服务间调用
- [ ] 资源服务器正确执行范围