New API 通过系统设置中的 OIDC 配置接入 SovereignID。配置时统一使用当前环境的 SovereignID 外部访问地址作为 OIDC issuer，不要写死某个部署域名。
一、准备 OIDC 应用
使用管理员账号登录 SovereignID 后，进入账号页，再打开
/accounts/applications/ 的“应用管理 / OIDC 应用”，为 New API 新建一个应用。
| 配置项 | 建议值 | 说明 |
|---|---|---|
| 应用名称 | New API |
便于管理员识别来源系统。 |
| 客户端类型 | Confidential |
New API 后端会保存客户端密钥。 |
| 授权方式 | Authorization Code |
New API 的 OIDC 登录流程使用授权码模式。 |
| 回调地址 | <NEW_API_URL>/oauth/oidc |
New API 的“配置 OIDC”区域会提示当前实例的主页链接和重定向 URL，以该提示为准。 |
| 授权范围 | openid profile email |
用于登录、用户名和邮箱同步。 |
示例：
SovereignID issuer: https://id.example.com
New API 地址: https://api.example.com
回调地址: https://api.example.com/oauth/oidc
保存应用后，复制 SovereignID 生成的 客户端 ID 和 客户端密钥，
用于填写 New API 的 OIDC 配置。客户端密钥只在创建成功或重置密钥后的页面显示一次；
离开或刷新页面后无法再次查看，只能重新生成。
二、在 New API 配置 OIDC
- 使用 New API 管理员账号登录。
- 进入“系统设置”，打开“系统设置”标签页。
- 找到“配置 OIDC”区域，按下表填写字段。
- 确认无误后点击“保存 OIDC 设置”。
| New API 字段 | 填写内容 | 注意事项 |
|---|---|---|
| Well-Known URL | <SOVEREIGNID_ISSUER_URL>/.well-known/openid-configuration |
例如 https://id.example.com/.well-known/openid-configuration。填写后 New API 会自动获取 OIDC 配置，下方各 Endpoint 可不填。 |
| Client ID | SovereignID 应用详情页生成的 client_id |
从 New API 对应的 OIDC 应用复制，不要和其他系统共用。 |
| Client Secret | SovereignID 应用详情页生成的 client_secret |
只在 New API 服务器侧保存，不会回显到前端，不要写入公开文档或代码仓库。 |
| Authorization Endpoint | <SOVEREIGNID_ISSUER_URL>/oauth/authorize |
仅在未使用 Well-Known URL 自动发现时手动填写。 |
| Token Endpoint | <SOVEREIGNID_ISSUER_URL>/oauth/token |
同上。 |
| User Info Endpoint | <SOVEREIGNID_ISSUER_URL>/oauth/userinfo |
同上。 |
三、开启 OIDC 登录
在“系统设置”标签页的“配置登录注册”区域，勾选“允许通过 OIDC 进行登录”并保存。 保存后 New API 登录页会出现 OIDC 登录入口。
四、验收检查
- New API 能保存 OIDC 设置，没有 discovery 或证书错误。
- New API 登录页出现 OIDC 登录入口。
- 点击登录后跳转到 SovereignID 登录页。
- 已验证邮箱的用户登录后能回到 New API，并自动创建或绑定账号。
五、常见排错
检查 New API 服务器是否能访问 <SOVEREIGNID_ISSUER_URL>/.well-known/openid-configuration，并确认反向代理 HTTPS 证书可信。
确认 SovereignID 应用登记的回调地址与 New API“配置 OIDC”区域提示的重定向 URL 完全一致，包括协议、域名和 /oauth/oidc 路径。
这是预期行为。手机号账号会看到“绑定邮箱并继续”入口；完成绑定验证后会安全返回原授权地址。