roblox-oauth

roblox-oauth

适用场景

当任务主要涉及 Roblox Open Cloud 的 OAuth 2.0 委托授权时，请使用此技能：

• 在 Creator Dashboard 中注册或配置 OAuth 应用。
• 在机密客户端和公共客户端实现之间进行选择。
• 构建授权码流程，尤其是结合 PKCE 使用时。
• 构造授权 URL 并处理重定向回调。
• 交换授权码、刷新令牌、内省令牌或撤销会话。
• 为用户授权的集成选择最小 OAuth 作用域。
• 在用户同意后验证令牌可访问哪些资源。
• 设置 localhost 或示例应用式开发环境以测试 OAuth。
• 调试 OAuth 专属错误、重定向不匹配、令牌误用或作用域失败。

当任务主要涉及以下内容时，请勿使用此技能：

• 通用 Open Cloud 请求构造、API 密钥、Webhook 或非 OAuth 云自动化。
• 体验内脚本架构、远程对象、复制或游戏玩法代码。
• DataStore 或 MemoryStore 设计。

决策规则

• 如果集成需要用户或创作者授予委托访问权限，而不是使用服务器自有的 API 密钥，请使用此技能。
• 所有客户端都优先使用带 PKCE 的授权码流程；公共客户端必须使用 PKCE。
• 将浏览器和移动应用视为无法安全保管客户端密钥的公共客户端。
• 将配有安全后端的应用视为机密客户端，并且只在服务器端保管客户端密钥。
• 仅请求应用实际功能所需的最小作用域。
• 如果应用需要 ID 令牌，请添加 openid；只有确实需要个人资料声明时才添加 profile。
• 如果任务转向端点选择、请求构造、速率限制或 Webhook，而非 OAuth 机制，请转交给 roblox-cloud。
• 如果任务转向体验内运行时架构或持久化设计，请转交给相应的 Roblox 技能。
• 如果请求混合了 OAuth 和范围外的架构内容，只回答 OAuth 部分，并明确排除其余内容。

说明

1. 确认 OAuth 用例：
   • 由用户或创作者授权访问 Open Cloud 资源。
   • 应用类型：机密或公开。
   • 除 API 访问权限外，是否还需要身份信息。
2. 注册或检查应用配置：
   • 如果开发者需要注册并发布应用，请确保其已通过身份验证。
   • 记录客户端 ID。
   • 如果应用是机密应用，请立即安全地保存客户端密钥，因为 Roblox 只会显示一次。
   • 仅添加必要的作用域。
   • 添加用于生产环境和本地开发的精确重定向 URL。
3. 编码前设计流程：
   • 使用授权码流程。
   • 所有客户端都使用 PKCE；公开客户端必须使用 PKCE。
   • 每次授权尝试都生成新的高熵 state。
   • 每次授权尝试都生成新的 code_verifier 和 code_challenge。
   • 在需要绑定 OIDC 身份时使用 nonce。
4. 正确构建授权请求：
   • 将用户发送至 https://apis.roblox.com/oauth/v1/authorize。
   • 包含 client_id、redirect_uri、scope 和 response_type=code。
   • 使用 PKCE 时，包含 code_challenge 和 code_challenge_method=S256。
   • 不要在浏览器或移动端代码中暴露机密客户端密钥。
5. 谨慎处理回调：
   • 使用 code 前先验证返回的 state。
   • 处理成功（code）和失败（error、error_description）两种查询参数。
   • 将授权码视为短时有效且只能使用一次。
6. 在 POST /oauth/v1/token 处交换令牌：
   • 使用 application/x-www-form-urlencoded。
   • 发送授权码、客户端 ID、授权类型，以及 code_verifier 或机密客户端凭据。
   • 仅在可信的服务端系统中存储刷新令牌。
7. 明确管理令牌生命周期：
   • 访问令牌的有效期约为 15 分钟。
   • 刷新令牌的有效期约为 90 天，且刷新时只能使用一次。
   • 每次成功刷新后，以原子方式替换已存储的刷新令牌。
   • 断开应用连接时，使用 POST /oauth/v1/token/revoke 撤销会话。
8. 验证令牌的实际权限：
   • 使用 GET /oauth/v1/userinfo 获取身份声明。
   • 应用必须确认用户授予的资源级访问权限时，使用 POST /oauth/v1/token/resources。
   • 仅在检查令牌活动状态和声明时使用 POST /oauth/v1/token/introspect；它不能替代资源授权检查。
9. 严格控制作用域和风险：
   • 根据实际端点和资源所有权需求选择作用域。
   • 在设计和审查时，将中风险、高风险和严重风险端点类别视为最小权限原则的警示信号。
   • 避免将技能扩展为通用 Open Cloud 端点实现。
10. 确保响应不偏离范围：

• 专注于应用注册、授权流程设计、令牌、作用域、本地开发和 OAuth 特定错误。
• 不要偏向以 API 密钥为首选的云集成、游戏玩法架构或数据服务设计。

使用参考资料

• 首先打开 references/oauth-overview.md，了解角色、授权类型选择和 OIDC 基础知识。
• 如果任务涉及 Creator Dashboard 设置、重定向 URL 规则、私密模式限制或应用审核，请打开 references/oauth-registration.md。
• 如果要实现 PKCE、授权 URL、回调处理或令牌存储，请打开 references/oauth-development-guide.md。
• 有关确切的 OAuth 端点、令牌有效期、令牌验证辅助工具和发现元数据，请打开 references/oauth-reference.md。
• 有关 localhost 设置、环境变量模式以及示例应用如何串联整个流程，请打开 references/oauth-sample-app.md。
• 将应用行为映射到最低必需权限范围时，请打开 references/scopes-reference.md。
• 需要在请求高权限范围前判断端点敏感性时，请打开 references/risk-level-reference.md。
• 根据 Open Cloud 错误模式排查 OAuth 和令牌相关故障时，请打开 references/cloud-auth-related-error-guidance.md。

检查清单

• 任务确实需要委托式 OAuth 访问，而非基于 API 密钥的自动化。
• 正确将客户端归类为机密客户端或公开客户端。
• 已包含 PKCE；如果公开客户端尝试跳过 PKCE，则拒绝该设计。
• 重定向 URL 完全匹配，并且对目标环境有效。
• 请求的权限范围最小化，且与集成的实际行为一致。
• 仅在需要身份数据或 ID 令牌时才包含 openid。
• 在回调中生成、存储并验证 state。
• 及时且仅一次交换授权码。
• 访问令牌和刷新令牌的存储位置不应是非可信客户端。
• 刷新时通过替换已存储的刷新令牌来处理刷新令牌轮换。
• 应用按各自用途使用 userinfo、introspect 和 token/resources。
• 不涉及通用 Open Cloud 请求机制、游戏脚本和数据架构。

常见错误

• 未先选择身份验证模式，就混用 API 密钥和 OAuth。
• 在前端或移动端代码中发布机密客户端密钥。
• 跳过 PKCE，尤其是公开客户端。
• 忘记在回调中验证 state。
• 误以为成功刷新后刷新令牌可以重复使用多次。
• 忘记授权码很快就会过期，且只能使用一次。
• 未请求 openid 就请求 profile。
• 开发期间请求过宽的权限范围，而不是最低必需范围。
• 误以为令牌内省能够证明资源所有权或已获同意的资源覆盖范围。
• 添加或更改权限范围时未让用户重新授权。
• 将非 OAuth 的 Open Cloud 问题纳入此技能的处理范围，而不是转交给 roblox-cloud。

示例

公开的 Web 或移动应用

• 使用带 PKCE 的授权码流程。
• 不要将任何密钥放在客户端。
• 验证 state；尽可能在可信后端交换授权码，并安全存储刷新令牌。

机密服务器应用

• 注册应用、妥善存储机密，并仍然使用 PKCE。
• 使用服务器交换授权码、刷新令牌，并通过 bearer token 调用 Open Cloud。

本地开发

• 添加 http://localhost:<port>/oauth/callback 作为重定向 URL。
• 将客户端 ID 和密钥存储在环境变量中。
• 在请求更多权限范围或提交审核前，测试完整的登录、回调、令牌交换、刷新以及注销或撤销流程。