技能介绍

你要解决什么问题

当 AI agent 需要接入外部 API（Google、GitHub、Auth0 等）时，认证往往是最先卡住的一环。OAuth 2.0 规范本身不难读，但落地时坑很多：授权码被拦截、state 参数缺失导致 CSRF、令牌写进 localStorage 被 XSS 偷走、refresh token 轮换时并发请求互相使对方失效……这些不是文档读一遍就能避开的错误。

技能如何工作

这个技能的核心是让 agent 根据应用场景选择正确的 grant type，并产出完整实现：

Grant 选择：面向用户的应用用 authorization code + PKCE；机器间通信用 client_credentials；无浏览器环境（CLI、智能电视）用 device code flow。隐式流已废弃，明确不推荐。
应用注册与回调处理：在提供方开发者控制台注册应用，精确配置 redirect_uri；回调时先校验 state 再交换令牌。
PKCE 实现：生成随机 code_verifier（43-128 字符），用 SHA-256 派生 code_challenge，请求中附带 code_challenge_method=S256。
令牌管理：access token 存服务端会话或 HTTP-only cookie，绝不暴露给前端 JS；refresh token 服务端保存并处理轮换——每次刷新后用新的替换旧的，重放旧令牌视为会话泄露。
刷新逻辑：每次 API 调用前检查过期窗口（约 60 秒），用 refresh token 换取新令牌；遇到 invalid_grant 时销毁会话，要求用户重新授权。

适用边界与注意点

令牌永不写入 URL 参数或日志——访问日志和错误消息里出现 token 是常见漏洞。
并发刷新需要互斥或 single-flight 模式，否则多个线程各自刷新、互相使对方令牌失效。
过期判断要加时钟缓冲（30-60 秒），应对服务器与提供方之间的时钟偏差。
redirect_uri 必须逐字符匹配，包括协议、端口和末尾斜杠——不匹配是最常见的配置错误。
支持 Auth0、Google、GitHub、Microsoft Entra ID、Okta、AWS Cognito、Keycloak 等提供方，覆盖 Express.js、FastAPI、Django、Spring Security、ASP.NET Core 等框架。