Authelia 集成 Proxmox通过 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本文是一份面向运维与自托管用户的实战指南讲解如何将 Proxmox Virtual EnvironmentPVE接入 Authelia 的 OpenID Connect 1.0 提供商Provider使其登录入口统一由 Authelia 接管并受多因素认证MFA保护。读完本文你将掌握在 Authelia 配置文件中注册 Proxmox 客户端、在 Proxmox Web GUI 中创建 OpenID Connect Realm以及正确配置作用域Scopes、用户自动创建与组映射最终实现通过 Authelia 完成 Proxmox 的单点登录。文章中的配置示例与操作步骤均来自当前仓库的官方集成文档 Proxmox 集成指南并结合仓库源码与配置参考进行深度展开。测试版本Tested Versions官方集成文档明确标注了该配置示例经过验证的软件版本组合实际部署时应尽量参照这些版本或确认你的版本行为一致软件验证版本Autheliav4.39.24Proxmox Virtual Environmentv8.4.1Proxmox Backup Serverv3.4.2其中 Proxmox Virtual Environment 是本文的主要集成对象Proxmox Backup Server 同样支持 OpenID Connect 认证配置方式与 PVE 一致可作为参考。前提假设Assumptions官方集成示例基于以下环境假设配置时请将占位值替换为你自己的域名与主机名应用根 URLhttps://proxmox.example.com/Authelia 根 URLhttps://auth.example.com/Client IDproxmoxClient Secretinsecure_secretRealmauthelia注意insecure_secret仅为文档演示用途严禁在生产环境使用。下文生成安全的客户端凭据一节提供了官方推荐的生成方式。Authelia 端配置注册 OpenID Connect 客户端在 Authelia 的主配置文件通常是configuration.yml中于identity_providers.oidc.clients下注册一个客户端。官方示例配置如下来自 Proxmox 集成指南identity_providers: oidc: ## The other portions of the mandatory OpenID Connect 1.0 configuration go here. ## See: docs/content/configuration/identity-providers/openid-connect/provider.md clients: - client_id: proxmox client_name: Proxmox 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://proxmox.example.com scopes: - openid - profile - email - groups 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关键配置项解读对照 OpenID Connect 1.0 客户端配置参考上述各参数的含义与注意点如下client_id必填客户端唯一标识长度不超过 100 字符且只能包含 RFC3986 定义的保留字符之外的字符Unreserved Characters并与所有已配置客户端完全唯一。官方集成指南同时强调文档中的proxmox仅为可读性演示值不应在生产环境直接使用建议使用下文生成安全的客户端凭据一节的方式生成 64 位随机字符串。client_name可选在 Authelia 界面中展示的友好名称默认与client_id相同。client_secret视情况必填Authelia 与 Proxmox 之间共享的密钥必须与 Proxmox 端配置的 Client Key 一致。官方强烈建议在配置文件中存储哈希值而非明文明文字符串存储方式已标记为弃用未来版本不保证支持。示例中即为insecure_secret经 PBKDF2-SHA512 迭代 310000 次后的摘要。需要注意的是哈希工作因子过高可能导致客户端认证超时可参考 FAQ 中 Tuning the work factors 一节调整。public可选默认false设为false表示这是一个机密客户端confidential client可以安全保管密钥若设为true公开客户端如 SPA、CLI 工具则client_secret必须留空。authorization_policy可选默认two_factor该客户端所需的授权策略。two_factor表示必须完成多因素认证才能授权也可设置为one_factor或引用提供商级authorization_policies中自定义的命名策略。该策略仅作用于 Authorization Request与访问控制规则Access Control Rules是两个不同的概念。require_pkce可选默认false强制该客户端使用 PKCEProof Key for Code Exchange防止授权码被截获后重用。pkce_challenge_method可选强制使用的 PKCE 挑战方法合法值为空字符串、plain或S256强烈建议S256。设置此项等同于同时启用了require_pkce。redirect_uris必填允许客户端回调的 URI 列表其余回调一律视为不安全。URI 区分大小写且必须带http或https协议头。若客户端请求的 redirect URI 不在列表中授权请求将直接失败。scopes可选默认openid,groups,profile,email允许该客户端消费的作用域列表。Proxmox 需要openid profile email groups四个作用域具体含义参见 OpenID Connect 1.0 Claims 与作用域定义openid启用 OpenID Connect 1.0 语义的核心作用域负责返回 ID Tokeniss签发者与sub主体组合是规范规定的、唯一可靠的用户标识方式preferred_username与email只应用于预置新账户。profile返回用户基本资料声明如preferred_username。email返回用户邮箱声明。groups返回用户所属组供 Proxmox 做组映射与授权。response_types可选默认code该客户端支持的响应类型。官方安全建议是只使用code授权码流程其他响应类型安全性较低。grant_types可选默认authorization_code允许客户端使用的授权类型。Proxmox 采用标准授权码流程故仅配置authorization_code除非确有必要不建议额外配置。access_token_signed_response_alg可选默认noneAccess Token 的签名算法。保持none表示 Access Token 以不透明opaque形式颁发若设为其他值则按 RFC9068 编码为 JWT但 JWT Profile Access Token 只能用于资源服务器的无状态校验不能作为身份证明。userinfo_signed_response_alg可选默认noneUserInfo 响应的签名算法。Proxmox 按普通 JSON 文档读取 UserInfo因此保持none。token_endpoint_auth_method可选默认client_secret_basic客户端在 Token Endpoint 的认证方式。client_secret_basic即把 Client ID 与 Client Secret 经 HTTP Basic 认证头发送。生成安全的客户端凭据官方 FAQ How do I generate a client identifier or client secret? 给出的推荐命令如下可同时生成随机 Client ID / Client Secret 及其 PBKDF2-SHA512 哈希authelia crypto hash generate pbkdf2 --variant sha512 --random --random.length 72 --random.charset rfc3986使用 Docker 时则为docker run --rm authelia/authelia:latest authelia crypto hash generate pbkdf2 --variant sha512 --random --random.length 72 --random.charset rfc3986该命令会输出一个随机生成的密码--random.length 72字符、字符集为 RFC3986 保留字符之外的安全字符以及与之对应的$pbkdf2-sha512$...哈希值——前者填入 Proxmox 的 Client Key后者填入 Authelia 的client_secret。--random.charset rfc3986的选择也与客户端凭据只允许 RFC3986 Unreserved Characters 的约束保持一致避免特殊字符在client_secret_basic等认证机制中的 URL 编码问题。Proxmox 端配置通过 Web GUI 添加 OpenID Connect Realm在 Proxmox 侧只有一种配置方式使用 Web GUI。操作路径如下对应 Proxmox 集成指南 的步骤在 PVE Web 界面左侧导航进入Datacenter数据中心。展开Permission权限。点击Realms认证域。点击Add并选择OpenID Connect Server打开添加 OpenID Connect Server表单即上文截图所示界面。参照下表填写各项配置配置项值说明Issuer URLhttps://auth.example.comAuthelia 的根 URLProxmox 据此发现 IdP 元数据JWKS、授权与 Token 端点等Realmauthelia该 OIDC 认证源的名称用于在 Proxmox 中标识此认证域Client IDproxmox必须与 Authelia 客户端配置中的client_id完全一致Client Keyinsecure_secret必须与 Authelia 客户端配置中的client_secret明文原文完全一致生产环境请使用强随机密钥Username ClaimDefault (subject)使用 ID Token 中的sub声明作为用户名官方文档标注的默认值即subjectScopesopenid email profile groups与 Authelia 客户端scopes配置保持一致的四个作用域Autocreate Users按需启用启用后首次通过 OIDC 认证成功的用户会被自动创建到 Proxmox 本地Autocreate Groups按需启用启用后Proxmox 会根据 OIDC 响应自动创建组Groups Claimgroups声明groups为组名来源用于将用户加入 Proxmox 中已存在的组实现基于组的授权表单底部还有Default将该 Realm 设为默认认证方式、Overwrite Groups用 IdP 返回的组覆盖本地组成员关系、Prompt认证交互方式默认使用 Auth-Provider 的默认行为与Comment备注等选项可按需配置。点击Add保存。之后 Proxmox 登录页即可选择authelia认证域跳转至 Authelia 完成登录如配置了two_factor策略还需通过第二因素校验随后以sub或groups声明映射回 Proxmox 用户与权限。配置要点与常见问题凭据两端必须一致Authelia 的client_secret哈希对应的是你填入 Proxmox Client Key 的明文。若使用authelia crypto hash generate生成请把输出中的明文部分填到 Proxmox把哈希部分填到 Authelia。作用域必须匹配Proxmox 请求的openid email profile groups必须全部包含在 Authelia 客户端scopes白名单内否则授权时会因作用域不被允许而失败。需要提醒的是groups声明依赖 Authelia 端正确配置用户组信息如 users_database.template.yml 中的组定义否则无法返回组数据。用户关联以sub为准按 OpenID Connect 规范isssub是唯一可靠、且保证不变的账户关联依据。Proxmox 默认的 Username Claim 使用subject即遵循这一最佳实践避免使用email、preferred_username等可变声明做账户绑定后者可能带来账户提权风险。Redirect URI 需精确匹配Authelia 配置的redirect_uris必须与 Proxmox 实际回调的地址https://proxmox.example.com完全一致区分大小写否则授权请求会被拒绝。进一步阅读OpenID Connect 1.0 客户端配置参考本文所用客户端配置项的完整参数表与安全说明OpenID Connect 1.0 提供商配置参考identity_providers.oidc下除客户端外的必需配置OpenID Connect 1.0 集成介绍授权类型、响应类型、PKCE 等协议层面的集成说明OpenID Connect 1.0 Claims 与作用域各作用域返回的声明明细OpenID Connect 常见问题客户端凭据生成、明文密钥弃用说明、哈希工作因子调优Proxmox 集成指南本文依据的原始文档【免费下载链接】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），仅供参考