roblox-oauth

roblox-oauth

何时加载

当任务涉及 Roblox Open Cloud 的 OAuth 2.0 委托授权时，加载此技能，例如应用注册、使用 PKCE 的授权码流程、令牌交换／刷新／撤销、范围选择或 OAuth 特定错误调试。对于 API 密钥自动化、体验内脚本或常规 Open Cloud 端点工作，请跳过此技能（改用 roblox-cloud）。

快速参考

流程选择

• 授权码 + PKCE — 公共客户端（浏览器／移动端）必须使用，建议所有客户端使用。
• 机密客户端 — 后端持有 client_secret；切勿在前端代码中公开。
• 公共客户端 — 无密钥；必须使用 PKCE。

PKCE 要点

• 生成 code_verifier（43–128 个字符的随机值）+ code_challenge（SHA-256，base64url）。
• 在授权请求中发送 code_challenge + code_challenge_method=S256；在令牌交换中发送 code_verifier。
• 每次授权尝试使用一个独立的验证值。

授权 URL

GET https://apis.roblox.com/oauth/v1/authorize 参数：client_id、redirect_uri、scope、response_type=code、code_challenge、code_challenge_method=S256、state、可选的 nonce。

令牌交换

POST /oauth/v1/token — application/x-www-form-urlencoded 参数：grant_type=authorization_code、code、client_id、code_verifier（公共客户端）或 client_secret（机密客户端）。

令牌生命周期

• 授权码 — 有效期为数秒，且只能使用一次；应立即交换。
• 访问令牌 — 约 15 分钟；以 Bearer 方式使用。
• 刷新令牌 — 约 90 天；每次刷新只能使用一次。每次刷新后，以原子方式替换存储的令牌。
• 撤销：断开连接时调用 POST /oauth/v1/token/revoke。

范围选择

• 选择与实际端点需求相匹配的最小范围。
• openid → ID 令牌；仅在需要个人资料声明时才使用 profile。
• 中／高／严重风险 = 最小权限审查信号。
• 更改范围需要重新授权。

验证端点

• GET /oauth/v1/userinfo — 身份声明。
• POST /oauth/v1/token/introspect — 令牌状态（不用于资源授权）。
• POST /oauth/v1/token/resources — 资源级访问权限。

关键规则

• 使用返回的授权码前，先验证 state。
• 刷新令牌：仅限服务端使用。
• 即使机密客户端也要使用 PKCE。
• 不要混用 API 密钥和 OAuth。 需要更多细节？ 加载 references/full.md，查看包含代码示例、API 表格和边缘情况的完整参考。