使用 Authelia 作为 HashiCorp Vault 的 OpenID Connect 1.0 身份提供方完整集成指南【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia本篇指南以 docs/content/integration/openid-connect/clients/hashicorp-vault/index.md 为骨架讲解如何将 HashiCorp Vault 的 JWT/OIDC 认证接入 Authelia 的 OpenID Connect 1.0 Provider实现单点登录SSO与多因素认证MFA。读完本文你将掌握在 Authelia 中为 Vault 注册 OIDC 客户端、理解每个关键配置项的取值含义与安全影响并能结合源码理解 PKCE、令牌签名、Token 端点认证等机制的底层行为。HashiCorp Vault 是业界广泛使用的密钥与机密管理工具其 UI 和 CLI 都支持通过 JWT/OIDC 认证方式接入外部身份提供方。Authelia 作为 Web 应用的 SSO 与多因素认证门户恰好可以作为 Vault 的 OpenID Connect 1.0 身份提供方Authorization Server让用户使用 Authelia 的账号体系与二次认证策略来保护 Vault 的访问。本指南基于 Authelia 官方集成文档给出经过验证的完整配置示例并深入每个配置项背后的实现细节。测试版本本指南的配置示例在以下版本组合上经过官方验证组件版本Autheliav4.38.0HashiCorp Vaultv1.8.1需要说明的是这代表该集成文档撰写时所验证的版本组合并非对版本能力的承诺在生产环境中建议参考各项目的最新发布说明确认兼容性。前置假设本示例基于以下假设展开你在实际部署时应替换为自身环境的值假设项示例值Vault 应用根 URLhttps://vault.example.com/Authelia 根 URLhttps://auth.example.com/Client IDvaultClient Secretinsecure_secret其中domain与subdomain-authelia等站点变量sitevar可以在文档页面中自动替换便于你直接复制出适合自己域名的配置。注意示例中的client_id、client_secret仅用于演示可读性绝不可直接用于生产环境。集成前提要点在开始配置前请务必确认以下几点对应源码中的{{% oidc-common %}}短代码内容见 docs/layouts/_shortcodes/oidc-common.htmlclient_id必须全局唯一仅可包含 RFC3986 Unreserved Characters字母、数字及-、.、_、~且长度不超过 100 字符。client_secret是 Authelia 与消费方应用共享的机密必须与 Vault 侧配置的明文密钥一致文档强烈建议在 Authelia 配置中存储其哈希形式见下文配置中的$pbkdf2-sha512$...示例而非明文。明文存储虽仍被支持但属于已弃用行为。本示例只给出客户端注册片段必须同时补齐 OpenID Connect 1.0 Provider 的必填配置如issuer_private_key、jwks等详见 OpenID Connect 1.0 Provider 配置文档。本示例只展示客户端配置项的一小部分完整可选项请参阅 OpenID Connect 1.0 Clients 配置文档。配置Authelia 侧注册 OIDC 客户端以下 YAML 是面向 HashiCorp Vault 的 Authelia 客户端配置 示例可直接放入configuration.yml的identity_providers.oidc.clients列表中identity_providers: oidc: ## The other portions of the mandatory OpenID Connect 1.0 configuration go here. ## See: https://www.authelia.com/c/oidc clients: - client_id: vault client_name: HashiCorp Vault client_secret: $pbkdf2-sha512$310000$c8p78n7pUMln0jzvd4aK4Q$JNRBzwAo0ek5qKn50cFzzvE9RXV88h1wJn5KGiHrD0YKtZaR/nCb2CJPOsKaPK0hjf.9yHxzQGZziziccp6Yng # The digest of insecure_secret. public: false authorization_policy: two_factor require_pkce: true pkce_challenge_method: S256 redirect_uris: - https://vault.example.com/oidc/callback - https://vault.example.com/ui/vault/auth/oidc/oidc/callback scopes: - openid - profile - groups - email response_types: - code grant_types: - authorization_code access_token_signed_response_alg: none userinfo_signed_response_alg: none token_endpoint_auth_method: client_secret_basic关键配置项逐一解析client_id: vault客户端唯一标识必须与 Vault 侧 OIDC 配置中的oidc_client_id完全一致。client_name在 Authelia 用户界面如同意授权页面中展示的友好名称默认与client_id相同此处显式设为HashiCorp Vault。client_secret配置中存储的是明文insecure_secret的 PBKDF2-SHA512 哈希。Vault 侧配置的则是明文insecure_secret。哈希存储方式避免了机密以明文形式暴露在配置文件中是官方强烈推荐的做法。生产环境应使用强随机密钥而非本文示例值。public: false声明这是一个机密confidential客户端RFC6749 Section 2.1即 Vault 后端能够安全地保管客户端凭据。机密客户端才允许配置client_secret若为true公开客户端适用于 SPA 与 CLI 工具client_secret必须留空。authorization_policy: two_factor该客户端在授权请求时应用的认证策略可选one_factor、two_factor或 Provider 级 authorization_policies 中自定义的策略名。默认即two_factor意味着用户登录 Vault 需要完成 Authelia 的双因素认证如 TOTP / WebAuthn。该策略只作用于 OIDC 授权请求与 访问控制规则 是两个不同的概念。require_pkce: true与pkce_challenge_method: S256强制该客户端使用 PKCERFC 7636。pkce_challenge_method指定强制使用的挑战方法合法值为空字符串、plain、S256官方强烈推荐S256。设置pkce_challenge_method会同时隐式启用require_pkce。这也解释了为什么文档中的 Vault 配置没有显式写require_pkce也能满足要求——实际上本例同时配置了二者require_pkce: true是显式声明pkce_challenge_method: S256则进一步把挑战方法钉死为S256。redirect_uris允许该客户端回调的 URI 白名单大小写敏感且 scheme 必须是http或https。Vault 需要两个回调地址CLI 使用的/oidc/callback与 UI 使用的/ui/vault/auth/oidc/oidc/callback。不在列表中的回调地址将被拒绝并报错。scopes允许该客户端请求的授权范围默认值为openid,groups,profile,email。此处显式列出openid、profile、groups、email与 Vault 需要的声明如用户组groups可用于 Vault 的策略绑定对应。范围与声明的对应关系可参考 OpenID Connect 1.0 Claims 文档。response_types: [code]只允许code响应类型即标准的授权码流程。官方明确建议仅使用code其余响应类型如id_token、token安全性不如授权码。grant_types: [authorization_code]该客户端允许使用的授权类型默认即authorization_code。官方提示如非必要不建议修改此项。access_token_signed_response_alg: none与userinfo_signed_response_alg: none分别表示 Access Token 与 Userinfo 响应不以 JWT 形式签名Access Token 由 Authelia 以不透明令牌形式发放Vault 通过 introspection 校验。设置为非none值会启用 RFC9068 的 jsonschema 枚举中确认。token_endpoint_auth_method: client_secret_basic该客户端访问 Token 端点时的认证方式。合法值为client_secret_basic、client_secret_post、client_secret_jwt、private_key_jwt、none。机密客户端默认即client_secret_basic规范要求即把 Client ID 与 Secret 以 HTTP Basic Auth 形式随请求发送。客户端配置的底层实现印证上述配置项在 Authelia 源码中有直接对应客户端结构体定义于 internal/configuration/schema/identity_providers.go其中RequirePKCE、PKCEChallengeMethod、AccessTokenSignedResponseAlg、UserinfoSignedResponseAlg、TokenEndpointAuthMethod、AuthorizationPolicy等字段与 YAML 键一一对应默认值在 同一文件的默认值初始化处 可见AuthorizationPolicy默认为two_factorAccessTokenSignedResponseAlg与UserinfoSignedResponseAlg默认为none与本文示例配置的取值一致。完整的客户端配置项参考包括public、redirect_uris、authorization_policy、require_pkce、token_endpoint_auth_method等全部字段的说明与默认值见 OpenID Connect 1.0 Clients 配置文档。生成生产级 Client ID 与 Client Secret文档示例中的vault/insecure_secret仅用于演示。生产环境请按 FAQ 指南 生成强随机值建议长度超过 40 字符且只包含 RFC3986 Unreserved Characters避免部分实现未正确 URL 编码凭据导致认证失败生成 72 字符的随机 Client IDauthelia crypto rand --length 72 --charset rfc3986同时生成 72 字符的随机明文密钥交给 Vault 使用及其 PBKDF2-SHA512 哈希存入 Authelia 配置的client_secretauthelia crypto hash generate pbkdf2 --variant sha512 --random --random.length 72 --random.charset rfc3986使用 Docker 部署时将authelia替换为docker run --rm authelia/authelia:latest authelia即可。Vault 侧接入 AutheliaVault 本身并不在 Authelia 仓库中其配置方式请参照 Vault 官方文档完成核心要点包括在 Vault 中启用 JWT/OIDC 认证后端vault auth enable oidc。配置 OIDC Provider 信息将 Authelia 的发现端点https://auth.example.com/.well-known/openid-configuration、oidc_client_id、oidc_client_secret、回调地址填入 Vault 的 OIDC 配置。通过bound_audiences、bound_claims与角色策略将 Vault 的访问权限绑定到 Authelia 下发的声明如groups、email实现基于 SSO 身份与用户组的细粒度授权。官方集成文档给出的参考链接为 HashiCorp Vault 的 JWT/OIDC Auth 文档 与 OpenID Connect Providers 文档详见原文的 See Also 一节。集成流程速览整个集成的工作流可以概括为用户访问 Vault 并选择 OIDC 登录被重定向到 Authelia 的授权端点。Authelia 按该客户端authorization_policy本例为two_factor要求用户完成登录与二次认证。用户同意授权后Authelia 将授权码通过redirect_uris中的回调返回给 Vault。Vault 携带授权码与 PKCE verifier 访问 Authelia 的 Token 端点使用client_secret_basic认证换取 Access Token本例为不透明令牌与 ID Token。Vault 通过 Userinfo 端点或 ID Token 获取profile、groups、email等声明按角色绑定策略授予用户相应权限。See AlsoOpenID Connect 1.0 集成介绍了解授权类型、响应类型、客户端认证方式等基础概念。OpenID Connect 1.0 Clients 配置文档全部客户端配置项的完整参考。OpenID Connect 1.0 Provider 配置文档Provider 级配置密钥、授权策略、生命周期等。HashiCorp Vault JWT/OIDC Auth 文档 与 HashiCorp Vault OpenID Connect Providers 文档Vault 侧的配置说明。OpenID Connect 1.0 FAQ客户端标识/密钥生成、明文存储弃用说明等常见问题。【免费下载链接】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），仅供参考