SovereignID
文档目录 接入 Vaultwarden

Vaultwarden OpenID Connect SSO

接入 Vaultwarden

OIDC + PKCE

配置 Vaultwarden OIDC 单点登录、邮箱关联、PKCE 和回调地址。

Vaultwarden 通过管理后台的 OpenID Connect SSO 配置接入 SovereignID。 下文以 Vaultwarden 的公网地址作为回调地址，并使用 SovereignID 的 issuer 完成自动发现。

先确认两个公网根地址 将 <SOVEREIGNID_ISSUER_URL> 替换为 SovereignID 的公网根地址，例如 https://id.example.com；将 <VAULTWARDEN_URL> 替换为 Vaultwarden 的公网根地址，例如 https://vault.example.com。两者都不要附加末尾斜杠。

一、在 SovereignID 创建 OIDC 应用

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

配置项 建议值 说明
应用名称 Vaultwarden 便于管理员识别来源系统。
客户端类型 Confidential Vaultwarden 服务端负责保管客户端密钥。
授权方式 Authorization Code 与 Vaultwarden 的 OIDC 授权码流程和 PKCE 配置匹配。
回调地址 <VAULTWARDEN_URL>/identity/connect/oidc-signin 必须与 Vaultwarden 管理页显示的 CallBack Path 完全一致，包括协议、域名和路径。
授权范围 openid email profile 用于识别用户，并获取已验证邮箱和基础资料。 
示例：
SovereignID issuer: https://id.example.com
Vaultwarden 地址: https://vault.example.com
回调地址: https://vault.example.com/identity/connect/oidc-signin

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

二、在 Vaultwarden 配置 OpenID Connect SSO

  1. 使用 Vaultwarden 管理员令牌进入 /admin。
  2. 打开“Settings”，找到“OpenID Connect SSO settings”。
  3. 按下表填写并保存；保存后如页面提示需要重启，请重启 Vaultwarden 服务。
Vaultwarden 字段 填写内容 注意事项
Enabled 开启 启用 OpenID Connect SSO。
Only SSO login 开启 与截图配置一致。首次联调时可暂时关闭，确认 SSO 可用后再开启，避免配置错误导致用户无法登录。
Allow email association 开启 允许按邮箱关联已有 Vaultwarden 用户；SovereignID 只会为已验证邮箱完成 OIDC 授权。
Allow unknown email verification status 关闭 保持关闭，要求身份提供方明确返回可信的 email_verified。
Client ID SovereignID 应用生成的 client_id 使用 Vaultwarden 独立应用的客户端 ID。
Client Key SovereignID 应用生成的 client_secret 这是敏感值，只保存在 Vaultwarden 服务端。
Authority Server <SOVEREIGNID_ISSUER_URL> 填写 issuer 根地址，例如 https://id.example.com，不要填写 discovery 完整路径。
Authorization request scopes openid email profile 使用空格分隔，不要遗漏 openid 和 email。
Authorization request extra parameters 留空 当前接入不需要额外授权参数。
Use PKCE during Authorization flow 开启 为授权码流程启用 PKCE。
Regex for additional trusted Id token audience 留空 不额外信任其他 ID Token audience。
CallBack Path <VAULTWARDEN_URL>/identity/connect/oidc-signin 通常由 Vaultwarden 根据公网域名显示；它必须已登记到 SovereignID 应用。
Optional SSO master password policy 留空 沿用 Vaultwarden 默认策略；如组织另有密码规范再单独设置。
Use SSO only for auth not the session lifecycle 关闭 与截图配置一致，由 SSO 参与会话生命周期。
Client cache for discovery endpoint. 0 与截图配置一致；联调期间可避免旧 discovery 配置长期缓存。
Log all tokens 关闭 令牌包含敏感身份信息，生产环境不要写入日志。
启用邮箱关联前先检查重复账号 Vaultwarden 会使用 OIDC 邮箱关联已有用户。上线前应确认两端邮箱归属一致且邮箱在 SovereignID 中已经验证， 不要开启“Allow unknown email verification status”。

三、验收检查

  • Vaultwarden 保存设置后没有 discovery、issuer 或 TLS 证书错误。
  • 登录入口可以跳转到 SovereignID，授权请求包含 openid email profile。
  • 已验证邮箱的用户授权后能返回 Vaultwarden，回调地址为 /identity/connect/oidc-signin。
  • 已有同邮箱用户能按预期关联，新用户行为符合当前 Vaultwarden 的注册策略。
  • 确认 SSO 登录稳定后再开启“Only SSO login”，并保留可用的管理员应急访问方式。

四、常见排错

无法加载 OIDC 配置或提示 issuer 不一致

确认 Authority Server 只填写 SovereignID issuer 根地址，并能从 Vaultwarden 容器访问 <ISSUER>/.well-known/openid-configuration；不要混用内网 IP 与公网域名。

登录后提示 redirect_uri 不匹配

逐字比较 Vaultwarden 的 CallBack Path 与 SovereignID 应用登记地址，重点检查反向代理使用的协议、外部域名和 /identity/connect/oidc-signin 路径。

邮箱无法关联或提示邮箱未验证

确认授权范围包含 email，用户已在 SovereignID 绑定并验证邮箱，并保持“Allow unknown email verification status”关闭。

开启 Only SSO login 后无法进入系统

先恢复该选项并检查 Vaultwarden 日志和反向代理配置；排错时不要开启“Log all tokens”，避免访问令牌和 ID Token 泄露。