Authelia OpenID Connect 集成指南为 Vaultwarden 配置单点登录SSO【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia导读本指南完整讲解如何将开源密码管理器 Vaultwarden 接入 Authelia 的 OpenID Connect 1.0 Provider实现基于 Authelia 身份源的统一登录SSO与基于用户组的角色下发。你将掌握 Authelia 侧identity_providers.oidc客户端、definitions.user_attributes表达式、claims_policies自定义声明的完整配置方法以及 Vaultwarden 侧SSO_*环境变量的标准与 Docker Compose 两种配置方式并可参照仓库源码理解其底层实现原理。测试版本与适用范围本集成方案在以下版本组合上经过验证仓库 docs/content/integration/openid-connect/clients/vaultwarden/index.md 记录Autheliav4.39.24Vaultwarden1.35.0使用 OIDCWarden 的 SSO 实现该集成属于社区支持级别support.level: community意味着其配置随上游应用变化可能存在差异升级时建议核对双方版本兼容性。前提假设以下示例默认采用如下约定你可以按实际环境替换项目默认值说明应用根 URLhttps://vault.example.com/决定了重定向 URI 的形态见下Authelia 根 URLhttps://auth.example.com/OIDC Provider 的 issuer 地址Client IDvaultwardenAuthelia 侧 OIDC 客户端标识Client Secretinsecure_secret仅用于示例生产环境务必更换注意应用根 URL 直接决定了回调地址。Vaultwarden 的 OIDC 回调 URI 固定为https://vault.example.com/identity/connect/oidc-signin 因此只要修改了应用根 URL就必须同步更新 Authelia 客户端配置中的redirect_uris否则授权码流程无法完成。另外本指南中的一些值域名、子域名对应文档系统的 sitevar 变量在真实部署中请替换为你的实际域名。集成原理概览整个登录链路如下用户访问 Vaultwarden 登录页并选择 SSO 登录Vaultwarden 将用户重定向至 Authelia 的授权端点Authelia 完成身份认证本示例为two_factor双因素策略Authelia 签发授权码并回调…/identity/connect/oidc-signinVaultwarden 用授权码换取 ID Token 与 Access TokenAuthelia 按claims_policy在 ID Token / UserInfo 中附加vaultwarden_roles声明Vaultwarden 读取该声明将用户映射为admin、user或空角色。其中第 6 步是本次集成的关键Vaultwarden 的 SSO 依赖 Token 中的角色声明来决定用户是管理员还是普通用户。配置 Authelia 侧1. 定义用户属性表达式definitions.user_attributesAuthelia 的definitions.user_attributes允许用通用表达式语言Common Expression LanguageCEL基于用户信息如groups、username、email等派生自定义属性。在 config.template.yml 中可以看到该配置块的标准形态# definitions: ## The user attribute definitions. # user_attributes: ## The name of the definition. # definition_name: ## The common expression language expression for this definition. # expression: 针对 Vaultwarden 的集成我们需要把用户组映射为角色definitions: user_attributes: vaultwarden_roles: expression: vaultwarden_admins in groups ? [admin] : vaultwarden_users in groups ? [user] : []该表达式的语义若用户的组groups包含vaultwarden_admins属性值为[admin]否则若包含vaultwarden_users属性值为[user]否则属性值为[]。在源码层面groups是内置的属性键见 internal/expression/const.go 中的AttributeUserGroups用户详情通过 UserDetailer 接口的GetGroups()等方法提供自定义属性最终由 UserAttributeResolver 在认证时求值。这意味着你完全可以按自己的组名设计映射规则比如把admins组直接映射为[admin]。2. 配置 Claims Policyclaims_policiesclaims_policies用于定义某个客户端在 ID Token 与 UserInfo 中暴露哪些声明含自定义声明。在 internal/configuration/schema/identity_providers.go 中IdentityProvidersOpenIDConnectClaimsPolicy包含id_token列表与custom_claims字典其中custom_claims的每个条目可用attribute字段绑定到上一步定义的用户属性参见 config_oidc_claims.yml 的等价用法示例。identity_providers: oidc: ## 其余 OpenID Connect 1.0 必填配置hmac_secret、jwks、issuer 等在此处补充。 ## 详见 docs/content/configuration/identity-providers/openid-connect/provider.md claims_policies: vaultwarden: id_token: [vaultwarden_roles] custom_claims: vaultwarden_roles: {}说明id_token: [vaultwarden_roles]把该属性放入 ID Token 的顶层声明custom_claims.vaultwarden_roles: {}注册一个名为vaultwarden_roles的自定义声明未显式指定attribute时默认解析同名用户属性。3. 定义 Scopescopes为了让 Vaultwarden 通过vaultwardenscope 请求到角色声明需要注册该 scope 并声明其携带的 claimsscopes: vaultwarden: claims: [vaultwarden_roles]4. 配置 OIDC 客户端clients: - client_id: vaultwarden client_name: Vaultwarden client_secret: $pbkdf2-sha512$310000$c8p78n7pUMln0jzvd4aK4Q$JNRBzwAo0ek5qKn50cFzzvE9RXV88h1wJn5KGiHrD0YKtZaR/nCb2CJPOsKaPK0hjf.9yHxzQGZziziccp6Yng # 明文 insecure_secret 的哈希摘要。 public: false authorization_policy: two_factor require_pkce: true pkce_challenge_method: S256 claims_policy: vaultwarden redirect_uris: - https://vault.example.com/identity/connect/oidc-signin scopes: - openid - offline_access - profile - email - vaultwarden response_types: - code grant_types: - authorization_code - refresh_token access_token_signed_response_alg: none userinfo_signed_response_alg: none token_endpoint_auth_method: client_secret_basic关键字段解读完整字段说明见 clients.md字段取值作用client_secretPBKDF2-SHA512 摘要存储明文密码的哈希而非明文示例摘要对应明文insecure_secretpublicfalse机密客户端需要通过客户端凭据认证authorization_policytwo_factor登录必须完成双因素认证require_pkce/pkce_challenge_methodtrue/S256强制 PKCE防止授权码截获claims_policyvaultwarden绑定上文定义的声明策略response_typescode仅授权码流程grant_typesauthorization_coderefresh_token支持刷新令牌配合offline_accessscopetoken_endpoint_auth_methodclient_secret_basic令牌端点使用 HTTP Basic 认证安全提醒示例中的insecure_secret仅供本地测试。生产环境请使用强随机密钥并优先考虑 Authelia 支持的哈希存储方式避免明文落盘。配置 Vaultwarden 侧Vaultwarden 侧只有一种配置方式环境变量。以下两种形态任选其一。方式一标准.env文件SSO_ENABLEDtrue SSO_ONLYfalse SSO_AUTHORITYhttps://auth.example.com SSO_SCOPESprofile email offline_access vaultwarden SSO_PKCEtrue SSO_CLIENT_IDvaultwarden SSO_CLIENT_SECRETinsecure_secret SSO_ROLES_ENABLEDtrue SSO_ROLES_DEFAULT_TO_USERtrue SSO_ROLES_TOKEN_PATH/vaultwarden_roles方式二Docker Composeservices: vaultwarden: image: vaultwarden/server:latest environment: - SSO_ENABLEDtrue - SSO_ONLYfalse - SSO_AUTHORITYhttps://auth.example.com - SSO_SCOPESprofile email offline_access vaultwarden - SSO_PKCEtrue - SSO_CLIENT_IDvaultwarden - SSO_CLIENT_SECRETinsecure_secret - SSO_ROLES_ENABLEDtrue - SSO_ROLES_DEFAULT_TO_USERtrue - SSO_ROLES_TOKEN_PATH/vaultwarden_roles环境变量逐项说明变量示例值含义SSO_ENABLEDtrue启用 SSO 登录入口SSO_ONLYfalse是否只允许 SSO 登录设为true将禁用主密码登录请谨慎评估影响SSO_AUTHORITYhttps://auth.example.comAuthelia 的 OIDC issuer 地址不含尾部斜杠SSO_SCOPESprofile email offline_access vaultwarden空格分隔的 scope 列表vaultwarden必须包含用于获取角色声明SSO_PKCEtrue启用 PKCE与 Authelia 侧require_pkce: true对应SSO_CLIENT_IDvaultwarden与 Authelia 客户端client_id一致SSO_CLIENT_SECRETinsecure_secret与 Authelia 客户端对应的明文密钥SSO_ROLES_ENABLEDtrue启用基于 Token 声明的角色映射SSO_ROLES_DEFAULT_TO_USERtrue未匹配到任何角色时默认将用户视为普通user避免新建用户无权限SSO_ROLES_TOKEN_PATH/vaultwarden_roles角色声明在 Token 中的 JSON 路径指向我们自定义声明的名称关键对应关系SSO_ROLES_TOKEN_PATH/vaultwarden_roles必须与 Authelia 侧custom_claims中注册的声明名vaultwarden_roles完全一致SSO_SCOPES必须包含vaultwarden对应 Authelia 侧scopes.vaultwarden。任一侧不匹配都会导致角色解析失败。角色映射行为验证结合前文配置完整的角色流转逻辑为用户在 Authelia 中被分到vaultwarden_admins组 →vaultwarden_roles属性求值为[admin]用户在 Authelia 中被分到vaultwarden_users组 → 求值为[user]用户不在上述任何组 → 求值为[]此时 Vaultwarden 因SSO_ROLES_DEFAULT_TO_USERtrue将其视为普通用户该值经claims_policies.vaultwarden写入 ID Token 顶层声明Vaultwarden 通过SSO_ROLES_TOKEN_PATH/vaultwarden_roles读取。如需验证声明是否正确下发可检查 ID Token 的解码内容其中应包含vaultwarden_roles: [admin]之类的字段也可以参考仓库中的 claims 配置测试样例 config_oidc_claims.yml 与 definitions_test.go 理解校验器的约束例如表达式必须可编译、引用的属性必须存在。常见问题与排查建议登录回调失败 / redirect_uri 不匹配确认redirect_uris与https://vault.example.com/identity/connect/oidc-signin完全一致协议、域名、端口、路径。登录后没有角色 / 所有人都是空角色检查SSO_SCOPES是否包含vaultwarden、SSO_ROLES_TOKEN_PATH是否等于vaultwarden_roles并核对 Authelia 的claims_policy是否已挂载到客户端。PKCE 相关报错确认 Authelia 侧require_pkce: true与pkce_challenge_method: S256Vaultwarden 侧SSO_PKCEtrue。secret 不匹配确认 Vaultwarden 的SSO_CLIENT_SECRET明文与 Authelia 中client_secret哈希对应的明文一致。延伸阅读OpenID Connect 1.0 集成总览docs/content/integration/openid-connect/introduction.mdAuthelia OIDC 客户端完整字段说明docs/content/configuration/identity-providers/openid-connect/clients.mdAuthelia OIDC Provider 全局配置docs/content/configuration/identity-providers/openid-connect/provider.md用户属性表达式源码实现internal/expression/types.go、internal/expression/const.goClaims / 自定义声明配置测试样例internal/configuration/test_resources/config_oidc_claims.yml【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考