OAuth 快速开始

本指南给出你的应用接入 OpenASA 作为 OAuth Provider 的最短路径。

协议说明：当前运行时实现的是 OAuth 2.0 Authorization Code + PKCE（S256）。

前置条件

• 应用可以访问 https://api.openasa.com。
• 你的应用已经在 OpenASA 一侧注册好 client_id、redirect_uri 与允许的 scopes。
• 你的后端能够安全处理授权码换取令牌。

步骤 1：准备授权请求参数

先准备这些字段：

• response_type=code
• client_id
• redirect_uri
• scope
• state

步骤 2：将浏览器重定向到 OpenASA authorize

你的浏览器应用把用户导向 GET /oauth/authorize。

从这一步开始，登录与授权确认界面由 OpenASA 负责。

步骤 3：在你的 redirect URI 接收回调

当用户完成登录与授权后，OpenASA 会带着以下参数回跳：

• code
• state

继续前先校验 state。

步骤 4：用 code 向 OpenASA 换取令牌

你的后端调用 POST /oauth/token，取得：

• access_token
• refresh_token
• id_token（如启用）
• expires_in

步骤 5：读取 OpenASA 用户资料

调用 GET /oauth/userinfo，并将返回的 sub 映射到你自己的本地账户模型。

API 参考

• OAuth 授权入口
• OAuth Token 换取
• OAuth 用户信息
• OAuth 公钥集合
• OAuth 撤销

常见配置错误

• 运行时使用的 redirect_uri 与注册信息不一致。
• 回调时没有传递或没有校验 state。
• 在浏览器端直接做 code 换 token，而不是走可信后端。
• 本地账户映射只依赖昵称或邮箱，而不是稳定的 sub。