最近在给博客的 MCP 服务升级认证系统时，我深入研究了 OAuth 2.0 协议。这个过程让我意识到，OAuth 2.0 虽然被广泛使用，但很多人（包括之前的我自己）对它的理解还停留在"会用"的层面。今天我想以项目的 OAuth 实现为例，深入聊聊 OAuth 2.0 的协议细节、核心流程，以及如何在实际项目中正确实现它。 ## 什么是 OAuth 2.0？ OAuth 2.0（Open Authorization 2.0）是一个**授权框架**，注意是"授权"而不是"认证"。它允许第三方应用在用户授权的情况下，获取有限权限访问用户在另一服务上的资源。 ### 核心概念 OAuth 2.0 引入了几个核心概念： - **Resource Owner（资源拥有者）**：能够授权访问受保护资源的实体，通常是用户 - **Client（客户端）**：代表资源拥有者请求访问受保护资源的第三方应用 - **Authorization Server（授权服务器）**：验证用户身份并颁发访问令牌 - **Resource Server（资源服务器）**：托管受保护资源的服务器 - **Access Token（访问令牌）**：用于访问受保护资源的凭证可以用一个简单的图来表示这些角色之间的关系： ```mermaid graph LR A[User
资源拥有者] --授权--> B[Client
第三方应用] B --请求授权--> C[Authorization Server
授权服务器] C --颁发 Access Token--> B B --携带 Token 请求资源--> D[Resource Server
资源服务器] D --验证 Token--> C D --返回资源--> B B --展示资源--> A ``` ## OAuth 2.0 的授权流程 OAuth 2.0 定义了四种授权模式，适用于不同的场景： ### 1. 授权码模式（Authorization Code Grant）这是最安全、最完整的授权流程，适用于有后端服务器的 Web 应用。 ```mermaid sequenceDiagram participant User as 用户 participant Client as 客户端 participant Auth as 授权服务器 participant Resource as 资源服务器 User->>Client: 1. 访问应用 Client->>Auth: 2. 重定向到授权页面
（带 client_id, redirect_uri, scope） Auth->>User: 3. 显示授权页面 User->>Auth: 4. 用户同意授权 Auth->>Client: 5. 重定向回应用
（带 authorization code） Client->>Auth: 6. 用 code 换取 access_token
（带 client_secret, code_verifier） Auth->>Client: 7. 返回 access_token Client->>Resource: 8. 携带 token 访问资源 Resource->>Client: 9. 返回受保护资源 ``` **关键步骤说明**： 1. **授权请求**：客户端将用户重定向到授权服务器，携带以下参数： - `response_type=code`：表示使用授权码模式 - `client_id`：客户端标识符 - `redirect_uri`：授权完成后的回调地址 - `scope`：请求的权限范围 - `state`：防 CSRF 的随机值（推荐） - `code_challenge`：PKCE 挑战码（推荐，见下文） 2. **用户授权**：用户在授权服务器上登录并同意授权 3. **获取授权码**：授权服务器将用户重定向回 `redirect_uri`，并带上授权码 4. **换取令牌**：客户端后端用授权码换取 access_token，需要验证： - 授权码的有效性 - `redirect_uri` 是否匹配 - PKCE `code_verifier` 是否匹配 `code_challenge` 5. **访问资源**：使用 access_token 访问受保护资源 ### 2. 客户端凭证模式（Client Credentials Grant）适用于服务器到服务器的认证，没有用户参与。 ```mermaid sequenceDiagram participant Client as 客户端应用 participant Auth as 授权服务器 participant Resource as 资源服务器 Client->>Auth: 1. 请求 token
（grant_type=client_credentials） Auth->>Auth: 2. 验证客户端身份 Auth->>Client: 3. 返回 access_token Client->>Resource: 4. 携带 token 访问资源 Resource->>Client: 5. 返回资源 ``` 在我们的项目中，当用户已经拥有有效 Token 时，可以使用这种方式获取新的 OAuth Token： ```typescript async function handleClientCredentialsGrant(request: NextRequest) { const token = getTokenFromRequest(request.headers); const user = await validateToken(token); // 返回 OAuth 2.0 标准响应 return { access_token: token, token_type: 'Bearer', expires_in: expiresIn, scope: 'read write' }; } ``` ### 3. 简化模式和密码模式 - **简化模式（Implicit Grant）**：已不推荐使用，安全性较差 - **密码模式（Resource Owner Password Credentials Grant）**：仅适用于高度信任的应用，需要用户直接提供密码 ## PKCE：防止授权码拦截 PKCE（Proof Key for Code Exchange，RFC 7636）是 OAuth 2.0 的安全扩展，专门用于防止授权码拦截攻击。 ### 为什么需要 PKCE？在传统的授权码流程中，如果攻击者能够拦截授权码（通过恶意应用注册的 URI），他们就能用它来换取 access_token。 ### PKCE 的工作原理 ```mermaid sequenceDiagram participant Client as 客户端 participant Auth as 授权服务器 Note over Client: 1. 生成 code_verifier (随机字符串) Client->>Client: 2. 计算 code_challenge = BASE64URL(SHA256(code_verifier)) Client->>Auth: 3. 授权请求（带 code_challenge, code_challenge_method=S256） Note over Auth: 4. 存储 code_challenge Auth->>Client: 5. 返回授权码 Client->>Auth: 6. 换取 token（带 code_verifier） Auth->>Auth: 7. 计算 SHA256(code_verifier) == code_challenge? Auth->>Client: 8. 验证通过，返回 token ``` ### 项目中的实现 ```typescript // 1. 客户端生成 code_verifier 和 code_challenge const codeVerifier = generateRandomString(); const codeChallenge = base64url(sha256(codeVerifier)); // 2. 发起授权请求 GET /authorize? response_type=code& client_id=xxx& redirect_uri=xxx& code_challenge={codeChallenge}& code_challenge_method=S256 // 3. 服务端验证 async function handleAuthorizationCodeGrant(code, client_id, code_verifier) { const authCodeData = await redis.get(`oauth:auth_code:${code}`); if (authCodeData.code_challenge) { // 计算 code_challenge 并验证 const computedChallenge = createHash('sha256') .update(code_verifier) .digest('base64url'); if (computedChallenge !== authCodeData.code_challenge) { throw new Error('Invalid code verifier'); } } // ... 继续生成 token } ``` ## 项目的 OAuth 实现 ### 整体架构我们的 MCP 服务实现了完整的 OAuth 2.0 认证系统，支持多种认证方式： ```mermaid graph TB subgraph "认证方式" A1[OAuth 2.0 Bearer Token] A2[长期 Token LTK_] A3[自定义 Headers 已弃用] end subgraph "认证适配器" B[authenticateMcpRequestEnhanced] end subgraph "Token 存储" C1[(Redis
user:token)] C2[(Redis
token:token)] C3[(Database
long_term_token)] end subgraph "OAuth 端点" D1[/.well-known/oauth-protected-resource] D2[/.well-known/oauth-authorization-server] D3[/token] D4[/revoke] D5[/introspect] end A1 --> B A2 --> B A3 --> B B --> C1 B --> C2 B --> C3 D1 --> B D2 --> B D3 --> B ``` ### 多重认证适配器我们实现了一个灵活的认证适配器，支持多种认证方式，并保持向后兼容： ```typescript export async function authenticateMcpRequestEnhanced(headers: Headers) { const token = getTokenFromRequest(headers); // 1. OAuth 2.0 Bearer Token（标准） const user = await validateToken(token); if (user) return user; // 2. 长期 Token（LTK_ 前缀） if (token.startsWith('LTK_')) { const userId = await validateLongTermToken(token); if (userId) { return await getUserById(userId); } } // 3. 向后兼容：自定义 Headers（带警告） const account = headers.get('x-mcp-account'); const password = headers.get('x-mcp-password'); if (account && password) { console.warn('[MCP] ⚠️ 使用已弃用的自定义头部认证'); const result = await login(account, password); if (result) return result.userInfo; } throw new Error("Invalid token"); } ``` ### Token 管理我们支持三种 Token： | Token 类型 | 格式 | 存储 | 过期时间 | 用途 | |-----------|------|------|---------|------| | 普通 Token | UUID | Redis | 7天（默认） | 日常登录 | | 长期 Token | `LTK_` + UUID | Database | 可配置/永久 | API 客户端 | | OAuth Token | `MCP_TOKEN_` + hex | Redis | 可配置 | OAuth 客户端 | ```prisma model LongTermToken { id String @id @default(uuid()) token String @unique // LTK_ 开头 userId Int expiresAt DateTime? // null = 永久 description String createdAt DateTime @default(now()) lastUsed DateTime? user TbUser @relation(fields: [userId], references: [id]) @@index([token]) } ``` ### 标准 OAuth 端点我们实现了完整的 OAuth 2.0 端点，符合 RFC 标准： #### Protected Resource Metadata（RFC 8707） ```typescript GET /.well-known/oauth-protected-resource Response: { "issuer": "http://localhost:3000", "authorization_endpoint": "http://localhost:3000/authorize", "token_endpoint": "http://localhost:3000/token", "revocation_endpoint": "http://localhost:3000/revoke", "introspection_endpoint": "http://localhost:3000/introspect", "scopes_supported": ["read", "write", "admin"], "grant_types_supported": ["client_credentials", "authorization_code"], "code_challenge_methods_supported": ["plain", "S256"] } ``` #### Token 端点支持 `application/json` 和 `application/x-www-form-urlencoded` 两种格式： ```bash # 客户端凭证模式 POST /token Content-Type: application/json Authorization: Bearer LTK_xxx { "grant_type": "client_credentials" } # 响应 { "access_token": "LTK_xxx", "token_type": "Bearer", "expires_in": 604800, "scope": "read write" } ``` #### Token 内省端点（RFC 7662）验证 Token 的有效性并返回元数据： ```bash POST /introspect Content-Type: application/json { "token": "LTK_xxx" } # 响应 { "active": true, "username": "admin", "scope": "read write", "client_id": "mcp-client-1", "token_type": "Bearer", "exp": 1737936000 } ``` #### Token 撤销端点（RFC 7009）主动撤销 Token： ```bash POST /revoke Content-Type: application/json { "token": "LTK_xxx" } # 响应 { "success": true } ``` ## 安全最佳实践基于项目的实现经验，这里总结一些 OAuth 2.0 的安全最佳实践： ### 1. 使用 HTTPS 所有 OAuth 通信必须通过 HTTPS，防止 Token 被拦截。 ### 2. Token 存储 - **Access Token**：存储在内存或安全的存储中（如 httpOnly cookie） - **不要**将 Token 存储在 URL、localStorage 或 sessionStorage 中 ### 3. State 参数授权请求时使用 `state` 参数防止 CSRF 攻击： ```typescript // 生成 state const state = generateRandomString(); sessionStorage.setItem('oauth_state', state); // 授权请求 const authUrl = `/authorize?state=${state}&...`; // 回调验证 if (request.state !== sessionStorage.getItem('oauth_state')) { throw new Error('Invalid state'); } ``` ### 4. Token 过期和刷新 - 设置合理的 Token 过期时间 - 实现 Refresh Token 机制 - 在服务端主动验证 Token 有效性 ### 5. 最小权限原则 `scope` 参数应该遵循最小权限原则，只请求必要的权限。 ```typescript // 只请求读权限 GET /authorize?scope=read // 而不是 GET /authorize?scope=read,write,admin // ❌ 过度授权 ``` ### 6. 错误处理不要在错误响应中泄露敏感信息： ```typescript // ❌ 不好 return { error: 'Invalid password for user@example.com' }; // ✅ 好 return { error: 'invalid_grant', error_description: 'Invalid credentials' }; ``` ## 与 Claude Code CLI 集成我们实现 OAuth 2.0 的主要目标是兼容 Claude Code CLI。配置流程很简单： ```bash # 1. 生成长期 Token # 访问 http://localhost:3000/c/user/info # 2. 配置 Claude Code CLI claude mcp add MyBlog http://localhost:3000/api/mcp \ --header "Authorization: Bearer LTK_xxx" # 3. 验证连接 claude mcp list ``` Claude Code CLI 会自动发现 OAuth 元数据，验证 Token，并在 Token 失效时提示重新认证。 ## 常见问题 ### Q: OAuth 2.0 和 OpenID Connect 有什么区别？ OAuth 2.0 是**授权**框架，而 OpenID Connect（OIDC）是在 OAuth 2.0 之上构建的**认证**层。OIDC 添加了 `id_token`，用于验证用户身份。 ### Q: 什么时候用授权码模式，什么时候用客户端凭证模式？ - **授权码模式**：需要代表用户操作，如访问用户的 GitHub 仓库 - **客户端凭证模式**：服务间调用，不需要用户参与 ### Q: PKCE 是必须的吗？对于公共客户端（如移动应用、SPA），PKCE 是必须的。对于保密客户端（有后端服务器），强烈推荐使用但不强制。 ### Q: Token 存在哪里？ - Access Token 应该存储在内存或安全存储中 - Refresh Token 可以持久化存储，但必须加密 - 不要在 URL 中传递 Token ## 总结 OAuth 2.0 是一个强大但复杂的安全框架。在实际项目中实现时，需要注意： 1. **遵循标准**：严格按照 RFC 规范实现 2. **安全第一**：使用 PKCE、HTTPS、State 参数 3. **向后兼容**：提供平滑的迁移路径 4. **完善监控**：记录认证日志，监控异常行为我们的实现支持多种认证方式，既保持了标准兼容性，又照顾了旧客户端。这种设计思路值得借鉴。希望这篇文章能帮助你更好地理解 OAuth 2.0。如果有什么问题或建议，欢迎在评论区讨论！ ## 参考资料 - [RFC 6749: OAuth 2.0 授权框架](https://datatracker.ietf.org/doc/html/rfc6749) - [RFC 7636: PKCE](https://datatracker.ietf.org/doc/html/rfc7636) - [RFC 8707: 资源指示器](https://datatracker.ietf.org/doc/html/rfc8707) - [RFC 7662: Token 内省](https://datatracker.ietf.org/doc/html/rfc7662) - [RFC 7009: Token 撤销](https://datatracker.ietf.org/doc/html/rfc7009) - [OAuth 2.0 安全最佳实践](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics)

分类: 技术随笔

深入理解 OAuth 2.0：从原理到实践