用途:该技能用于在 Opensteer 项目中配置与测试第三方集成的 OAuth 授权。触发场景包括注册集成 OAuth 应用、配置托管或自定义授权同意、测试集成授权流程。
主要能力:
- 注册规范:要求先阅读 docs/integration-oauth.md、packages/integration-catalog 中的供应商定义和 apps/control-plane/.env.example,并按运行中服务实际提供的回调地址与目录声明的权限范围注册;不得从开发端口臆造重定向地址;供应商发布或组织审批需另外办理。
- 托管应用配置:按环境变量示例独立配置 OPENSTEER_HOSTED_OAUTH_STATE_KEY 与 OPENSTEER_HOSTED_OAUTH_ENCRYPTION_KEY;为 GOOGLE、MICROSOFT、SLACK、DISCORD、GITHUB 设置完整的 OPENSTEER_HOSTED_OAUTH__CLIENT_ID、_CLIENT_SECRET、_REVISION 组,并与目录资质修订版本匹配;整组省略即禁用,部分设置会导致配置失败;GitHub 还需 _INSTALLATION_URL(https://github.com/apps/<app-slug>/installations/new);回调中继不需要托管供应商凭据。
- 自定义应用:凭据通过所有者应用设置保存并显式选择该来源;存在有效 Account 链接时,所有自定义应用都注册 Host 显示的精确 Account 中继回调(独立 HTTPS Host 亦然),无 Account 时注册显示的直接 Host 回调;已有连接与刷新继续可用,仅新的授权同意或重连使用新重定向;需提示用户在供应商控制台添加显示的精确 URI;中继不接触客户端密钥或令牌,但其可用性是新授权的前提,不得回退到直连回调。
- MCP:保留 Account 的静态客户端元数据文档,或以精确的 Account HTTPS 重定向使用服务器现有 DCR 流程;校验已注册重定向、issuer 和 PKCE 固定。
- 各供应商注册形态:Slack 用机密 Web OAuth,而非桌面 PKCE 机器人同意;Microsoft 用机密 Web,面向组织/个人账户的 /common v2,使用显式委托作用域;Discord 用机密授权码模式且不带 PKCE;GitHub Apps 启用过期用户令牌、安装期间禁用 OAuth、注册修订版本的安装 URL,并分别授权用户与选择仓库。
使用方式:按变更范围运行聚焦检查,如 pnpm exec vitest run packages/integration-auth/src/oauth.test.ts 等;API 密钥修复使用指定集成测试;以目标成员/来源验证真实供应商同意、持久完成、获授权时刷新及断开/撤销通知;通过同一 Account 路径测试远程与本地发起;验证错误账户/浏览器/供应商、回调重放、双设备并发、取消、交换期间解链/重链均不产生凭据;验证换源与缺权限拒绝不切换账户;停止启动的服务,受阻的供应商访问应报告而非绕过。
适用场景:Opensteer 集成 OAuth 的配置、迁移、排障与验证。
限制:不编造重定向地址;不得以假令牌端点作为供应商注册合格依据;不支持的预注册应用应给出可操作的不兼容提示,而非另一回调路径。