快捷入口

客户端集成说明（OAuth 2.0，非完整 OIDC）

本 AS 基于 Spring Authorization Server，对外暴露标准 OAuth 端点；与常见 OIDC 客户端库的默认假设并不完全一致，集成前请先阅读本节。

协议定位

Scope 约定（常见踩坑）

• OAuth 2.0 不规定 scope 必须叫什么；但 authorize 请求的每一个 scope都必须在管理端为该 Client 预先登记，否则回调为 ?error=invalid_scope。
• 管理端「授权 Scope」通常选客户端租户下的角色名（与 RS 验权一致），不会自动包含 openid、profile、offline_access。
• openid：仅在使用 OIDC / 需要 id_token 时按需登记；不是授权码流程的必选项。
• profile、offline_access：OIDC 常见 scope，均为可选；未登记却请求 → invalid_scope。
• 若只需 access_token 调业务 API：authorize 的 scope 填 Client 已登记的角色名即可，不必照搬 OIDC 库默认三件套。
• 多个 scope 用空格分隔（URL 中可为 +），不要用逗号。

Scope 携带建议

authorize 的 scope 只能是该 Client 在管理端已登记 scope 的子集。集成前请与OAuth Client 登记人（管理端 → OAuth 客户端）确认下表所列名称后再编码到客户端。

1. 角色 scope（业务主路径，通常必带）

管理端创建 Client 时，「授权 Scope」下拉来自客户端租户（默认 tenantId=1）下已定义的角色名称。authorize 应携带与 RS 业务 API @RequireScope 一致的角色 scope。

协作建议：Client 登记人导出该 Client 的「授权 Scope」列表 → 客户端开发按列表配置 authorize；不要自行假设 OIDC 默认 scope 已登记。

2. 可选标准 scope（按需登记后再携带）

下列为 OIDC / OAuth 生态常见 scope 名；仅当管理端已为该 Client 勾选/登记时才能在 authorize 中请求。

3. 常见组合示例

access_token（JWT）除 scope 外还含 role_codes（用户在该租户下的实际角色），RS 上 @RequireRole 看 role_codes，@RequireScope 看 token 中的 scope；两者可能同时存在，集成时请与后端约定。

推荐集成步骤

1. 管理端 OAuth 客户端 新建 PKCE 公开客户端，填写实际 redirect_uri，勾选需要的「授权 Scope」。
2. 客户端 authorize 的 scope 与上一步登记完全一致（或为其子集）。
3. 浏览器打开 /oauth2/authorize?... → 登录（/oauth2/login）→ 按需 consent → 回调带 code。
4. POST /oauth2/token（grant_type=authorization_code + PKCE）换取 access_token（及默认启用的 refresh_token；scope 含 openid 时另有 id_token）。
5. （可选）GET /.well-known/openid-configuration 读取 Discovery；GET /oauth2/userinfo 携带 Authorization: Bearer {access_token} 获取身份 Claims。

Discovery / UserInfo 示例

curl -s http://127.0.0.1:8080/.well-known/openid-configuration

curl -s http://127.0.0.1:8080/oauth2/userinfo \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: application/json"

UserInfo 要求 access_token 授权 scope 含 openid；profile/email/phone claims 须对应 scope 已登记且 authorize 已携带。

authorize 链接示例

GET /oauth2/authorize
  ?response_type=code
  &client_id={管理端创建的 client_id}
  &redirect_uri={须与 Client 登记完全一致，需 URL 编码}
  &scope={与 Client 登记的 scope 一致，空格分隔}
  &state={随机串}
  &code_challenge={S256 挑战码}
  &code_challenge_method=S256

OAuth Client

发行版不预置演示 Client。请先在管理端 OAuth 客户端 中新建 PKCE 公共客户端，redirect_uri 可填示例： http://127.0.0.1:8080/demo/callback，再按上文拼接 /oauth2/authorize 链接进行验收。

用户反馈（C 端跳转提交）

业务 App 在用户本地已登录后，携带 client_id 与 email 跳转至 AS 内置反馈页，无需在授权服务器再次登录即可提交文字与图片。提交成功后按 OAuth Client 配置的「反馈通知邮箱」异步发信；管理端可只读查阅历史反馈。

跳转 URL

GET /oauth2/feedback?client_id={clientId}&email={urlEncodedEmail}&returnUrl={可选}

email 由业务 App 从本地登录态读取并自行 URL 编码（如 encodeURIComponent）。示例（将 {client_id} 换为管理端已创建的 Client ID）：

http://127.0.0.1:8080/oauth2/feedback?client_id={client_id}&email=user%40example.com&returnUrl=http%3A%2F%2F127.0.0.1%3A8080%2Fdemo%2Fcallback

集成要点

• 免登录：反馈页不检查 AS Cookie，不重定向 /oauth2/login。
• returnUrl 可选；非空时其 scheme + authority 须与 Client 任一 redirect_uri 一致，否则忽略（不展示返回链接，不阻断提交）。
• 图片须先由宿主提供 POST /file/upload，将响应中的文件名随 POST /oauth2/feedback 表单提交（字段 imageUrls）。
• 邮件通知：管理端 OAuth 客户端表单填写「反馈通知邮箱」；服务端须配置 spring.mail.*。未配置邮箱或 SMTP 时反馈仍落库，仅跳过发信。
• 管理端查阅：部署后导入 管理端默认菜单.csv，侧栏打开 用户反馈（/client/feedback）；API 为 POST /manage/feedback/list、POST /manage/feedback/detail/{id}（只读）。

PKCE 参数（换 token 时使用）

{state=LxR1y4Q7lO1WeAWrunybaA, code_verifier=yCyYq6kiZ9a2-GD-GFZ__VvQN-IiSVEuwEBqqCcRrxc, code_challenge=z0ttY_KgMnsxucHPpsz3LXNp72jijNk7t6PecdifjDU}

管理端 UC 登录示例

curl -X POST http://127.0.0.1:8080/user/login \
  -H "Content-Type: application/json" \
  -d '{"tenantId":"2","userCode":"admin","password":"123456"}'

预置说明

• 管理端：执行 sql/03-tenant-seed.sql 后使用 admin / 123456（tenantId=2）
• OAuth Client：须在管理端创建（见 README「管理端侧栏菜单」）
• 管理端 Web UI：须先构建 admin-ui，见 admin-ui/README.md