authentik 与 Proxmox VE 集成：OIDC 统一登录配置指南

如果你已经在一台内网服务器上把 authentik 跑起来，并且正在用 Proxmox VE（PVE）管理虚拟机和容器，那这一步几乎是绕不开的刚需：让 PVE 不再维护独立的账号密码，而是通过 authentik 完成身份认证。简单说，就是把 PVE 的登录框“外包”给 authentik，实现一套账号密码走遍内网所有服务。这篇文章我重点讲 authentik 与 PVE 的 OIDC 集成，覆盖从 authentik 侧创建 Provider、到 PVE 侧添加 Realm、再到用户权限落地的完整过程，同时把部署以来踩过的典型问题整理成排查清单。适合已经装好 authentik 基础实例、想给虚拟化平台做统一身份认证的同学参考。

我自己的环境是 authentik 长期版 + PVE 8.x 系列，authentik 用 Docker Compose 部署，PVE 是标准的 8006 端口 Web 界面。这一篇是基于这套实验环境反复验证过的流程，版本不同时界面字段会有细微差别，但原理一致。

1. 为什么要先想清楚“PVE 登录接 authentik”这件事

1.1 PVE 原生认证体系的痛点

PVE 默认的认证体系其实很传统：节点本地保存 /etc/pve/user.cfg，管理员手动给每个人开账号、设密码、分配权限。两三台机器的时候问题不大，可一旦宿主机数量多起来，痛点很快就浮现了。

首先是密码分散在各节点上。员工离职、实习生临时借调、外包同学需要临时查看虚拟机状态，你要么在每个节点上逐个删账号，要么留着僵尸账号天天担心安全。其次是密码策略基本等于没有，大家习惯性用同一个密码，PVE 默认又不会强制你上多因素认证。哪怕你给某个人只开了只读权限，只要密码泄露，攻击者拿到的就是一台宿主机层面可接触的合法入口。

我当时决定引入统一身份认证，核心目的不是“显得专业”，而是把“谁可以登录”“登录后能干什么”“什么时候不该能登录”这三件事收口到一个地方管。authentik 正好承担这个角色，它支持 OAuth2/OIDC、SAML、LDAP 等多种协议，后端可以对接企业微信、飞书、LDAP 目录甚至本地数据库，而且可以配置 TOTP、WebAuthn 等多因素认证，开源许可也比较友好。对家用环境是小菜一碟，对小型团队来说也完全撑得住。

1.2 两条集成路线：OIDC 还是 LDAP

PVE 内置支持多种认证 Realm，其中最常见的两条路是 LDAP 和 OIDC。很多人习惯先想到 LDAP，因为 authentik 也提供一个嵌入式 LDAP 服务，看起来“企业目录都是这么干的”。但在 PVE 这个场景下，我更推荐 OIDC，原因很实际。

LDAP 的好处是能直接同步用户列表，PVE 可以拉取 authentik 里的用户目录，用户自动出现，不用手工创建。坏处是 authentik 的嵌入式 LDAP 不在默认部署里，需要单独起一个 ldap outpost，并且要映射到 authentik 的 User 和 Group，配置链路更长；密码校验虽然走 LDAP bind，但遇到密码过期、账号锁定这类状态时，提示信息也比较简略。

OIDC 走的是标准 OAuth2 授权码模式，PVE 只看 authentik 签发的 ID Token，不直接接触密码。集成后用户在本机浏览器里被重定向到 authentik 的登录页，完成验证后拿一个认证票据跳回 PVE。这条路的突出优势是：用户密码不会经过 PVE 节点，PVE 侧连密码散列都不用存；后续如果给 authentik 开了 TOTP 和 WebAuthn，登录 PVE 时这些多因素策略会一并生效，不需要在 PVE 上重复配置。

我做的选型对比可以参考这个表：

1.3 集成后的认证链路

如果真的打算上 OIDC，心里要先有一条完整的认证链路，后面配置时才不会云里雾里。

用户访问 https://pve.example.local:8006 后，PVE 的 Web 界面发现当前没有有效票据，就带着自己的 Client ID 和回调地址，把浏览器重定向到 authentik 的授权端点。authentik 展示登录页，用户输入账号密码，如果开了多因素就再验证一次，然后 authentik 拿着授权码和 PVE 换取 ID Token。PVE 验证 Token 合法后，把 Token 里的用户名映射成 PVE 内部用户，例如 alice@authentik，最后给浏览器种一个 PVE ticket，整个登录过程完成。

我实际体验下来，这比想象中要快，只要两端配置正确，从点击登录到进入 PVE 面板大概 2 到 3 秒。难点不在这 3 秒，而在配置前有没有想清楚账号和权限映射。

2. 集成前的准备工作和参数规划

2.1 检查版本、网络与证书条件

在动手前，先确认两边的版本和网络条件。PVE 8.x 自带 OIDC 认证 Realm，但不同小版本在界面字段和默认配置上有细微差别，总体上建议至少是 PVE 8.1 之后的版本，我实测基于 PVE 8.2。如果你还在用 7.x，想走 OIDC 会比较别扭，建议优先考虑升级。

网络层面的要求很基础但容易忽略：PVE 节点要能访问 authentik 的地址，反过来 authentik 不一定需要主动访问 PVE，因为 PVE 会发起回调。不过我遇到过有人把 authentik 跑在 Docker 里，但 Docker 主机的防火墙只放了入站规则，没放节点到容器网络的出站规则，结果 PVE 的自动发现一直失败。别笑，这种问题排查起来能浪费一下午。

然后是证书。PVE 的 OpenID Connect 自动发现会先请求 /.well-known/openid-configuration，如果你的 authentik 是自签名证书，而 PVE 默认校验 SSL 证书，那自动发现必然失败。两个选择：要么给 PVE 节点导入 authentik 的 CA 证书，要么在 PVE 的 Realm 配置里关闭 SSL 校验。实验环境图省事可以关，生产环境还是建议把 CA 加到系统信任链里。

我自己在家庭实验环境里把 authentik 用 Let‘s Encrypt 签了正式证书，设置好泛域名，这样 PVE 侧不用处理自签信任问题，省了不少坑。

2.2 先在 authentik 侧确定资料

集成前最好先在 authentik 里创建好对应的用户或组。我习惯给每个要接的应用规划一个组，比如在 authentik 里建一个 pve-admins 组，把需要管理 PVE 的成员都拉进来。这个组的作用在 authentik 侧是代表“谁有资格访问 PVE”，真正落到 PVE 的权限还需要在 PVE 侧做一次映射，后半部分会细说。

同时记下 authentik 的对外域名，例如 https://auth.example.local，以及之后创建 Provider 时会生成的 Issuer URL 和 Client ID/Secret。PVE 侧需要用到这些参数，最好先把它们复制到一个文本文件里统一管理。

另外要确认一下 authentik 的管理员账号是可用状态。很多人在配置 Provider 或者绑定 Application 时用的不是超管，结果界面上看不到某些选项，以为是自己配置错误，其实只是权限不足。最好直接用初始的管理员账号操作。

2.3 PVE 侧先想好用户和权限模型

这是集成前最容易偷懒的一步，也是最容易返工的一步。OIDC 不会把 authentik 里的用户列表同步到 PVE，PVE 的权限体系只认识 PVE 内部的用户和组。也就是说，即使 authentik 用户 alice 能通过认证，如果 PVE 里没有 alice@authentik 这个用户，她登录进来也是一张白纸，甚至连面板都进不去。

所以要在实际登录之前就想好几个问题：哪些人需要访问 PVE？他们需要多大权限？是只要看虚拟机的 CPU 和内存，还是能开机、关机、做快照？这些角色在 PVE 里通常对应 PVEAuditor、PVEVMUser、PVEAdmin 等内置角色。先把角色规划出来，后面落到 PVE 侧时只需要批量创建用户并绑到对应组或 ACL 上。

有一个小技巧：在命名 OIDC Realm 时，不要图省事叫什么 oidc，可以叫 authentik 或者更具体的 sso。因为登录后用户名会显示成 alice@authentik、alice@sso 这种格式，名称起得太泛，后面在日志和 ACL 里看的时候会分不清来源。

3. authentik 侧配置 Provider 与 Application

3.1 新建一个 OIDC Provider

进入 authentik 管理后台，在左侧菜单找到 Providers，点 Create，类型选择 OAuth2/OIDC Provider。Provider 是 authentik 对外提供认证能力的核心对象，它负责定义协议参数、签名算法、Client 凭据，以及 Token 里能携带哪些用户属性。

你需要给 Provider 起一个容易识别的名称，例如 proxmox-ve-oidc，然后设置一个 Client ID，默认可以留空由系统生成，也可以自己填一个类似 pve 的字符串。Client Secret 建议勾选自动生成，保存之后再从详情页复制出来，手工填容易出错。

关键选项里，Client Type 必须选择 Confidential，因为 PVE 是需要用 Client Secret 去换 Token 的机密客户端，如果选了 Public，后续授权码换 Token 那一步会直接失败，PVE 端只会在日志里报一个很模糊的错误。

3.2 Redirect URI 和 Outpost 是最容易翻车的两个点

很多人的集成失败，都坏在 Redirect URI 没有填对。OAuth2 授权码流程中，authentik 授权完成后只会把浏览器重定向到提前注册过的地址，如果 PVE 实际回调的地址不在白名单里，authentik 会直接拒绝。

PVE 的 OIDC 回调地址默认是 https://你的PVE地址:8006/oidc/callback，注意末尾有 /oidc/callback 路径，不要只填到 8006 端口就完事。如果你的 PVE 用域名访问并且走了反向代理，那回调地址要以最终用户地址为准，而不是 PVE 节点的内网地址。

Provider 创建页面的 Redirect URIs/Origins 里，把下面两个地址都加上：

code复制https://pve.example.local:8006/oidc/callback
https://pve.example.local:8006/

第一个是授权码回调，第二个是登录后回跳地址。虽然我把第二个作为正式配置靠的是第一个，但有几次 PVE 版本在做额外校验时也访问了根路径，加上不影响安全，只增加兼容性。

Provider 下方的 Scopes，至少把 profile 勾上，因为 PVE 默认从 ID Token 的 preferred_username 字段拿用户名，而这个字段由 profile scope 提供。如果你想在 PV E 的日志里看到完整邮箱，可以再把 email 勾上，但 PVE 本身不强制要求。

创建完成后，还有一个很多人忽略的动作，就是把 Provider 分配给 authentik 自带的 outpost。authentik 默认有一个 embedded outpost，Provider 必须绑定到某个 outpost 上，它的 Issuer URL 才是实际可访问状态。如果 Provider 没绑定任何 outpost，你在 Issuer URL 打开时大概率会看到 404 或者路由报错。在 Provider 列表点击刚创建的那条，进入编辑页，往下找到 outpost 绑定区域，直接选默认 outpost 并保存即可。

3.3 创建 Application 并绑定访问权限

Authentik 的概念稍微有点绕：Provider 负责技术协议，Application 负责业务入口。用户看到的是 Application，真正把用户和 Provider 连接起来的是 Application 上的绑定关系。

在左侧菜单 Applications -> Applications，点击 Create，填一个名称，例如 Proxmox VE，Slug 填写 pve。Slug 会出现在之后的一些 URL 里，建议保持简单。绑定 Provider 时选择刚建的 OIDC Provider，保存后，这个 Provider 和 Application 就关联起来了。

接下来要给 Application 授权给用户或组。可以进入 Application 详情页，点击 Authorize 或者直接在侧边栏配置 binding，选择之前规划好的 pve-admins 组。如果你是一个人的实验环境，也可以直接把管理员账号加进去。

绑定完成后，从 authentik 的 Application 列表里点选打开，应该能跳到 PVE 地址，或者至少能发起一次 OIDC 请求。如果跳转回报错，多半是 Redirect URI 没填全，回上一步再核对一遍。

有个细节值得单独说一句：首次通过 authentik 登录一个新的 Application 时，用户会看到一个授权确认页，提示“是否允许 Proxmox VE 使用你的账号”。这是正常的 OAuth 授权行为，确认一次之后，后面的登录通常就不会再反复问你了。如果你发现每次都弹，那是 Application 的授权策略配置成了每次都需要重新确认，可以去看 AuthenticationFlow 的设置。

4. PVE 侧添加 OIDC Realm 与权限落地

4.1 在数据中心里新建认证 Realm

PVE 侧的集中配置入口在 Datacenter -> Permissions -> Authentication。这里列出了当前所有可用的 Realm，默认有 Linux PAM 和 PVE 内置认证。点击 Add，选择 OpenID Connect Server。

弹出的表单里，有几个字段要逐一核对。Name 是 Realm 名称，我填的是 authentik，这个名称之后会出现在用户名后缀里。Issuer URL 填 authentik Provider 的地址，一般格式是：

code复制https://auth.example.local/application/o/pve/

注意末尾的斜杠建议带上。PVE 会根据这个 URL 自动追加 /.well-known/openid-configuration，如果填错了就会在自动发现阶段失败。

Client ID 和 Client Secret 填 authentik Provider 页面里生成的那两个值，粘贴时注意不要带多余的空格。Redirect URL 通常不需要手填，PVE 会根据当前服务器的地址自动生成并显示在表单下方，默认就是类似 https://pve.example.local:8006/oidc/callback 的地址。如果你之前给回调地址做了反向代理，这里可能需要手动改。

4.2 处理自动发现和 SSL 校验问题

如果 authentik 的证书是正规 CA 签发的，PVE 表单填完后直接确认就行。如果 authentik 用的是自签证书，你需要展开 Advanced 设置，找到 SSL 证书校验相关选项，把它关掉，否则添加 Realm 时会报证书验证失败。

更严谨的做法是到 PVE 节点上，把 authentik 使用的自签 CA 证书导入系统的 /usr/local/share/ca-certificates/，然后执行 update-ca-certificates，再重启 pveproxy 服务。这样 PVE 既能校验 authentik 证书，又不需要全局关闭 SSL 校验。我自己的生产习惯是优先导入 CA，只有在临时演示环境里才关校验。

表单填完后点击 Add，PVE 会立刻请求一次 authentik 的发现端点。如果状态正常，Realm 列表里会立刻多出刚创建的那一条，状态列没有报错。如果列表页没报错但在界面下方看到红灯提示，建议先回到 authentik 侧确认 Provider 的 Issuer URL 能被 PVE 访问到。

我用 CLI 验证过这个方向的连通性。在 PVE 节点上执行：

bash复制curl -I https://auth.example.local/application/o/pve/.well-known/openid-configuration

能返回 200 或 302，说明 PVE 节点到 authentik 的网络链路没有大问题。如果这条命令都失败，就不用去 PVE 界面里反复填表单了，先修网络。

4.3 用户映射与权限落地，这步比配置 Realm 更重要

Realm 添加成功后，表象上看已经可以登录，但实际会卡在“认证成功但没有权限”这一步。因为 OIDC 只负责“证明你是你”，不负责“告诉你有什么权限”，PVE 的 ACL 体系仍然只认 PVE 内部预先定义的用户和组。

例如 authentik 用户 alice 登录后，PVE 看到的用户名是 alice@authentik。但 PVE 里并不存在这个用户，所以认证通过后，Web 界面可能跳转回登录页，或者显示没有权限访问。这个问题的根源是用户映射和 ACL 没配置。

解决办法很简单，在 PVE 里手动创建同名用户，不需要设置密码。在 Datacenter -> Permissions -> Users 里点 Add，User name 填 alice，Realm 选择刚添加的 authentik，密码留空即可。或者直接用 CLI：

bash复制pveum user add alice@authentik

然后给这个用户分配权限。如果只是希望她拥有基础虚拟机权限，可以绑定到虚拟机池上，也可以直接在根路径上给角色。我的建议是先给最小权限，逐步放大，避免一上来就给 Administrator，等出问题才发现权限太宽。

bash复制pveum aclmod / -user alice@authentik -role PVEAuditor

如果用户很多，一个个创建也不是长久之计。我会先在 PVE 里创建组，把用户批量加入组，再对组授权。比如：

bash复制pveum group add pve-admins
pveum usermod alice@authentik -group pve-admins
pveum aclmod / -group pve-admins -role Administrator

我建议的 PVE 角色映射如下：

这里有一个容易踩的误区：OIDC 用户不能像 LDAP 那样自动同步组，authentik 里 pve-admins 组和 PVE 里 pve-admins 组虽然名字一样，但没有任何自动关联。你必须先在 PVE 组里添加 OIDC 用户，组权限才生效。想完全自动化，要通过脚本定期调用 PVE API 和 authentik API 做同步，这部分我会在第 6 节展开。

5. 实际登录验证与高频问题排查

5.1 走一遍完整的端到端登录流程

配置完成后，用无痕窗口验证最靠谱，避免浏览器里已有的 authentik 会话干扰判断。打开 PVE 登录页，正常会看到 PVE 自己的登录框，下方有 Realm 下拉框，选择 authentik，然后把用户名和密码填到对应的输入框。

这里要注意：在 PVE 的登录框里切换 Realm 到 authentik 后，你填的账号密码会先发给 PVE，PVE 再把它重定向到 authentik 的登录页。有的版本会直接把浏览器送到 authentik，如果 authentik 里已经有会话，可能不需要重复输密码，直接回到 PVE。如果没会话，就进入 authentik 的登录界面，正常输入 authentik 的账号密码。

认证通过后，浏览器回到 PVE，这时右上角显示的用户名应该是类似 alice@authentik 的格式。注意看是否有权限进入资源树，如果没有，对照第 4.3 节检查用户和角色。

验证完成后，我建议在 PVE 的工具栏点击退出，再重复登录一次，确认流程稳定。如果退出后立刻再登录没有出现密码框，那不是 bug，是 authentik 的会话仍然有效，它属于单点登录的预期行为。

5.2 常见错误速查表

我整理过这段时间遇到的高频问题，按出错阶段分类如下：

5.3 快速定位问题的几条命令

如果登录失败且界面上没有任何有效提示，可以先去看 PVE 的访问日志。我的习惯是在 PVE 节点上执行：

bash复制tail -f /var/log/pveproxy/access.log

然后用无痕窗口再触发一次登录，观察是否有带 oidc 或 openid 的请求，以及返回状态码是 302、401 还是 403。302 通常是重定向到 authentik，401 多数是凭据或 Client 配置问题，403 则是权限不足。

如果 PVE 日志里看不到有效信息，再到 authentik 侧看事件日志。如果是 Docker Compose 部署的 authentik，在部署目录下执行：

bash复制docker compose logs -f server

反复触发登录时，auth 相关请求会打出来。如果发现 authentik 侧根本收不到请求，问题在网络链路；如果收到了但返回了错误，响应体里通常会带有 error 和 error_description，这个描述比 PVE 界面的提示准确得多。

我自己的破案顺序是：先看 authentik 日志确认是否有请求进来，再看 PVE 的 access log 确认回调是否成功，最后看 PVE 的认证日志确认用户映射是否成功。按这个顺序排查，五分钟内基本能定位到问题。

5.4 一个容易被忽略的“退出”坑

PVE 右上角的退出按钮，只负责清除 PVE 自己的 ticket。它不会把 authentik 里的会话一并注销，所以用户点退出后，再次访问 PVE 时可能直接被 authentik 的现存会话带回来，看起来就像“退出无效”。

处理办法是在 authentik 的 Provider 高级设置里配置合法的退出后跳转地址，把 PVE 的地址加到退出白名单。但由于 PVE 的退出按钮并不会主动调用 authentik 的注销端点，这类设置只能部分缓解。我的建议是在内网环境里接受这个行为，只要 authentik 的会话超时策略设置得合理，安全性不会有大问题。真正需要完全退出时，可以直接访问 authentik 的退出页面。

6. 补充操作与进阶扩展建议

6.1 把 authentik 的 MFA 策略加到 PVE 登录链路上

OIDC 集成带来的最大安全收益是可以直接用 authentik 的多因素认证。在 authentik 后台把某个用户组的 MFA 策略设置成强制启用后，用户登录 PVE 时会被要求先输入一次 TOTP 验证码，或者用 WebAuthn 硬件钥匙。

要注意的是，这些 MFA 策略作用于 authentik 的登录流程，所以用户在 authentik 登录过一次之后，短时间内再次跳转 PVE 可能不会触发第二次 MFA。这其实是合理的，说明 authentik 已经帮你管理好了会话风险等级。如果希望每次访问 PVE 都重新验证多因素，需要在 authentik 的 Provider 绑定关系里配置更严格的会话策略，但那样会牺牲一部分用户体验，我建议按系统分级来处理。

6.2 保留一个应急通道，别把所有入口都收口

这一步极其重要。当 authentik 服务因为升级、容器异常、网络配置变化而不可用时，依赖 OIDC 登录 PVE 的所有用户都会被困在门外。如果 PVE 节点本身还启用了防火墙，只能通过 Web 界面管理，那情况会非常尴尬。

所以一定要保留一个 PVE 内置认证或 Linux PAM 的管理员账号，例如 root@pam，并确保这个账号不在 OIDC Realm 的覆盖范围内。它平时不要用，只在 authentik 故障时作为应急通道。我在配置好 OIDC 后，专门测试过一次关闭 authentik 容器再登录 PVE 的场景，确认 root@pam 能独立登录才放心。生产环境中，这个账号的密码应该由核心管理员保管，并记录在安全的地方。

6.3 把 PVE 用户和 ACL 纳入自动化管理

如果管理的 PVE 节点数量变多，手动在每台 PVE 上创建用户和维护权限会再次变成负担。OIDC 能解决认证，但解决不了授权数据分散在多个节点的问题。

我的做法是用一个小脚本，每天从 authentik API 拉取指定组的成员列表，然后调用 PVE API 批量同步用户和 ACL。流程大致是：先把 authentik 里 pve-admins 组的用户列表读取出来，再在每台 PVE 上调用 pveum user add 把新成员创建好，最后调用 ACL 接口把这些用户统一加到某个组或角色下。删除成员时同理，只是把用户从 PVE 组里移除。

如果不想自己造轮子，可以用 Ansible 加 PVE 的 API 模块来做。这个方案的好处是权限模型收敛到代码里，人员变动时只要改 authentik 侧的组，几十台 PVE 的权限会在下一轮同步中自动对齐。刚开始搭可能觉得多此一举，但当你真的被“为什么这台机器上 alice 还能登录”折磨过一次后，就会明白自动化同步的价值。

最后再分享一点我的经验体会

这套集成我前后搭过三次，第一次失败在 Redirect URI 没带 /oidc/callback，第二次失败在 PVE 里忘了预创建用户，第三次才顺利走通全流程。所以如果你照着操作第一次没成功，不要怀疑方向，大概率是某个参数没对齐。

我个人的建议是，先把 authentik 侧的 Provider 和 Application 配好后，不要急着去 PVE 里填参数，先用 curl 验证一下 issuer 地址和回调地址是否能互相匹配。配置完 PVE Realm 后，也别急着批量导入用户，先用一个测试账号走一遍完整登录，确认权限模型符合预期后，再逐步推广到所有成员。毕竟身份认证这块，稳定比速度重要得多。