SovereignID
文档目录 接入 Portainer

Portainer Custom OAuth

接入 Portainer

OAuth + OIDC

配置 Portainer 自定义 OAuth、OIDC 端点、自动用户创建和回调地址。

Portainer Community Edition 通过自定义 OAuth Provider 接入 SovereignID。 Portainer 不使用 OIDC 自动发现，需要在认证设置中分别填写授权、Token 和 UserInfo 端点。

先确认两个公网根地址 将 <SOVEREIGNID_ISSUER_URL> 替换为 SovereignID 的公网根地址，例如 https://id.example.com；将 <PORTAINER_URL> 替换为 Portainer 的公网根地址，例如 https://portainer.example.com。Portainer 的 Redirect URL 需要保留末尾斜杠。

一、在 SovereignID 创建 OIDC 应用

使用管理员账号登录 SovereignID，进入账号页的“应用管理 / OIDC 应用”，为 Portainer 创建独立应用。 不要与 Gitea、New API、Vaultwarden 或其他系统共用客户端 ID 和客户端密钥。

配置项 建议值 说明
应用名称 Portainer 便于管理员识别来源系统。
客户端类型 Confidential Portainer 服务端负责保管客户端密钥。
授权方式 Authorization Code Portainer 的自定义 OAuth 登录使用授权码流程。
回调地址 <PORTAINER_URL>/ 必须与 Portainer 的 Redirect URL 完全一致，包含协议、域名和末尾斜杠。
授权范围 openid profile email groups 用于登录，并读取用户名、邮箱和用户组声明。 
示例：
SovereignID issuer: https://id.example.com
Portainer 地址: https://portainer.example.com
回调地址: https://portainer.example.com/

保存后立即复制生成的 客户端 ID 和 客户端密钥。客户端密钥只在创建成功或重置后的页面显示一次， 离开或刷新页面后无法再次查看，只能重新生成。

二、选择 OAuth 和自定义 Provider

  1. 使用 Portainer 管理员账号登录。
  2. 进入 Settings，打开 Authentication。
  3. 在 Authentication method 中选择 OAuth。
  4. 开启 Use SSO。
  5. 如需首次登录时自动创建用户，开启 Automatic user provisioning；自动创建的用户默认使用标准用户角色。
  6. 在 Provider 中选择 Custom。
先保留内部管理员登录 首次联调时不要让 OAuth 成为唯一可用的管理员入口。Portainer Community Edition 无法隐藏内部认证提示， 应保留一个强密码内部管理员账号，确认 SSO 稳定后再收紧日常登录策略。

三、填写 OAuth Configuration

Portainer 字段 填写内容 注意事项
Client ID SovereignID 应用生成的 client_id 使用 Portainer 独立应用的客户端 ID。
Client secret SovereignID 应用生成的 client_secret 这是敏感值，只保存在 Portainer 服务端。
Authorization URL <SOVEREIGNID_ISSUER_URL>/oauth/authorize 例如 https://id.example.com/oauth/authorize。
Access token URL <SOVEREIGNID_ISSUER_URL>/oauth/token 由 Portainer 服务端用授权码换取令牌。
Resource URL <SOVEREIGNID_ISSUER_URL>/oauth/userinfo Portainer 从 UserInfo 响应读取用户标识和资料。
Redirect URL <PORTAINER_URL>/ 填写 Portainer 公网首页地址并保留末尾斜杠，同时登记到 SovereignID 应用。
Logout URL 留空 当前接入不配置统一登出端点；退出 Portainer 不会同时退出 SovereignID。
User identifier preferred_username 与截图配置一致，使用 OIDC UserInfo 中的稳定用户名字段。
Scopes openid profile email groups 使用空格分隔，不要遗漏 openid。
Auth Style Auto Detect 让 Portainer 自动选择客户端凭据的提交方式。

确认所有字段无误后，点击 Save settings 保存认证设置。

四、验收检查

  • Portainer 保存认证设置时没有 OAuth 端点或 TLS 证书错误。
  • 登录页出现 OAuth/SSO 入口，点击后能跳转到 SovereignID 登录页。
  • 已验证邮箱的用户授权后能返回 Portainer，且显示正确的 preferred_username。
  • 开启自动用户创建后，新用户能以标准用户角色创建；再按最小权限原则分配环境、团队和角色。
  • 退出 Portainer 后确认会话行为符合预期，并验证内部管理员应急入口仍然可用。

五、常见排错

登录后提示 redirect_uri 不匹配

逐字比较 Portainer 的 Redirect URL 与 SovereignID 应用登记地址，重点检查 HTTPS、公网域名和末尾斜杠。

授权成功后无法读取用户信息

确认 Resource URL 为 <ISSUER>/oauth/userinfo，Scopes 包含 openid profile email，用户已经绑定并验证邮箱。

无法创建用户或登录后没有环境权限

检查是否开启 Automatic user provisioning。自动创建只提供标准用户身份，仍需在 Portainer 中按团队或角色授予所需环境权限。

Portainer 无法访问 OAuth 端点

从 Portainer 容器或主机检查三个端点的 DNS、网络和 TLS 证书，不要在公网 issuer 与内网 IP 之间混用地址。