管理员指南
自定义 OAuth 提供商
添加任意符合 OIDC 标准的自定义登录方式
除了内置的 OAuth 提供商外，Root 可以添加任意符合 OIDC 标准的自定义登录方式。使用 Root 账号登录后，进入系统设置页面（`/console/setting`），找到「自定义 OAuth」区域。Web 控制台与参考设计一致，正在对接中；当前演示数据与登录页通过 localStorage 联动。
添加自定义 OAuth 提供商
自定义 OAuth 提供商
配置自定义 OAuth 提供商，支持 GitHub Enterprise、GitLab、Gitea、NextCloud、Keycloak、Casdoor 等兼容 OAuth 2.0 / OpenID Connect 协议的身份提供商。 回调 URL 格式：{网站地址}/oauth/{slug}
| 图标 | 名称 | Slug | 状态 | Client ID | 操作 |
|---|---|---|---|---|---|
| 暂无自定义 OAuth 提供商 | |||||
系统设置底部「自定义 OAuth」区域示意：说明横幅、添加按钮与空列表
进入配置区域
Root 登录后进入 /console/setting ，滚动至页面底部「自定义 OAuth 提供商」卡片。与 系统设置 其它 Tab 同属 option / custom_oauth_provider 配置范畴。
添加提供商
点击「+ 添加 OAuth 提供商」打开表单，填写名称、Slug、Client ID/Secret 与 OAuth 端点。Slug 创建后不建议修改，否则需在 IdP 侧同步更新回调 URL。
回调 URL 格式
在 IdP 应用配置中将 Redirect URI 设为：
{网站地址}/oauth/{slug} 其中「网站地址」为系统设置中的 ServerAddress（如 https://ai.example.com），{slug} 与表单中 Slug 字段一致。
提供商列表
| 列 | 字段 | 说明 |
|---|---|---|
| 图标 | icon | 提供商 Logo URL 或图标标识 |
| 名称 | name | 登录按钮展示名称，如「企业 GitLab」 |
| Slug | slug | 唯一标识，用于回调路径 `/oauth/{slug}` |
| 状态 | enabled | 启用后出现在登录/注册页第三方区域 |
| Client ID | client_id | 在 IdP 注册应用后获得的客户端 ID（列表中可脱敏展示） |
| 操作 | — | 编辑、启用/禁用、删除 |
配置 Client ID / Secret
- 在 IdP（GitLab、Keycloak 等）创建 OAuth / OIDC 应用，记录 Client ID 与 Client Secret。
- 将回调 URL 配置为 `{ServerAddress}/oauth/{slug}`，slug 与 EasyAPI 中填写的 Slug 完全一致。
- 在 EasyAPI 系统设置 → 自定义 OAuth →「添加 OAuth 提供商」填写端点与 scopes；若提供 well_known 可简化端点配置。
- 保存后启用（enabled=1）；仅 enabled 的提供商会出现在 `/login` 与 `/register` 底部第三方区域。
表单字段说明
| 配置项 | 字段 | 说明 |
|---|---|---|
| 名称 | name | 必填；展示在登录按钮上 |
| Slug | slug | 必填；小写英文，全局唯一，决定回调 URL 路径 |
| 图标 | icon | 可选；图标 URL |
| Client ID | client_id | OAuth 应用 Client ID |
| Client Secret | client_secret | OAuth 应用密钥，保存后不在列表明文展示 |
| 授权端点 | authorization_endpoint | OAuth authorize URL |
| Token 端点 | token_endpoint | OAuth token URL |
| 用户信息端点 | user_info_endpoint | 获取用户 profile 的 API |
| Scopes | scopes | 默认 openid profile email，按 IdP 要求调整 |
| Well-Known | well_known | 可选；OIDC `.well-known/openid-configuration` 地址，可自动发现端点 |
| 用户 ID 字段 | user_id_field | 从 userinfo JSON 读取唯一 ID 的键，默认 sub |
| 用户名字段 | username_field | 映射为系统 username，默认 preferred_username |
| 显示名字段 | display_name_field | 映射为 nickname，默认 name |
| 邮箱字段 | email_field | 映射为 email，默认 email |
| 授权样式 | auth_style | 0=参数传递 client_secret；1=Header 传递（部分 IdP 要求） |
| 访问策略 | access_policy | 可选 JSON；限制允许登录的用户范围 |
| 拒绝提示 | access_denied_message | 策略拒绝时向用户展示的文案 |
数据表 custom_oauth_provider 字段与上述表单一一对应；slug 列有唯一索引。
端点与 scopes
- 标准 OIDC：填写
well_known后可自动解析 authorization / token / userinfo 端点 - 纯 OAuth 2.0：需手动填写 authorization_endpoint、token_endpoint、user_info_endpoint
- Scopes 示例：
openid profile email（OIDC）或read:user user:email（GitHub） - 内置 OAuth 路由：
GET /api/oauth/github、wechat等与自定义/oauth/{slug}并存，互不影响
测试 OAuth 回调
- 退出当前账号，打开 `/login`，确认底部出现新添加的 OAuth 按钮。
- 点击按钮应跳转至 IdP 授权页；授权成功后回跳 `{网站地址}/oauth/{slug}` 并完成登录或注册绑定。
- 在「个人设置 → 账户绑定」验证第三方账号是否已关联。
- 若失败，检查 Client Secret、回调 URL、scopes 及 userinfo 字段映射是否与 IdP 返回 JSON 一致。
用户侧 OAuth 登录说明见 注册与登录 文档中的「第三方 OAuth 登录」章节。