统一认证实践(8)Authentik 接入 AdGuard Home 统一认证与 NPM 代理
创建于 2026-11-15
更新于 2026-11-16
科技
truenas
authentik
nginx
openwrt
adguard
6441 字 · 约 22 分钟

前言

AdGuard Home 部署在 iStoreOS 上,日常通过管理页面查看查询记录、维护过滤规则和 DNS 重写。这次将管理入口接入 DoraTiger Auth,希望完成一次统一认证后直接进入后台,不再额外输入 AdGuard Home 的密码。

本次使用 AdGuard Home v0.107.79、iStoreOS 24.10.6、Authentik 2026.8.5 和 Nginx Proxy Manager(NPM)2.14.0。HTTPS 入口统一放在 NPM,复用 TrueNAS 上已有的 Proxy Outpost。

前哨部署见 统一认证实践(4)Authentik 接入 qBittorrent 与 NPM 统一认证。接入前,先确认 NPM 能通过共享 Docker 网络访问这个前哨。

一、认证结构

1.1 Forward Auth 与 Basic 凭据转发

本次使用 AdGuard Home 已支持的 HTTP Basic 认证。浏览器先经过 Authentik 的应用访问检查,再由代理向 AdGuard Home 提供后端凭据。AdGuard Home API 认证说明

text
1
2
3
4
5
浏览器 → NPM 的 AdGuard HTTPS 入口 ↓ auth_request TrueNAS Proxy Outpost ↔ 云端 Authentik 登录与 MFA ↓ 认证通过,返回后端 Basic 认证头 NPM → iStoreOS 上的 AdGuard Home 管理服务

Outpost 只处理认证子请求及相关登录路径,AdGuard Home 页面和管理 API 仍由 NPM 转发到 iStoreOS。DNS 查询继续按 AdGuard Home 原来的配置处理。

Authentik 识别访问者,AdGuard Home 接收现有后台账号的凭据。因此,这种方式不为每个 Authentik 用户建立独立的 AdGuard Home 账号;允许访问的用户最终使用同一个后端管理身份。本次只向受信任的管理员开放。

1.2 示例网络与对象

以下 IP 为文档示例地址,使用时替换为自己的 LAN 地址。

对象 示例值
云端身份服务 https://auth.example.com
NPM 所在主机 192.0.2.10
iStoreOS 主机 192.0.2.20
AdGuard 管理端口 3000,以实际配置为准
对外管理入口 https://adguard.example.com
应用 Slug istoreos-site-a-adguard
Provider doratiger-istoreos-site-a-adguard
访问组 istoreos-site-a-adguard-admins
已有前哨 doratiger-truenas-proxy
NPM 网络内的前哨别名 doratiger-authentik-outpost

服务运行在 iStoreOS,因此应用和组按 iStoreOS 部署位置命名。前哨仍按实际运行位置命名,两者不必使用相同前缀。

二、接入准备

2.1 DNS 与 HTTPS

将 adguard.example.com 解析到 NPM 所在主机,而不是直接指向 iStoreOS。检查证书覆盖这个域名,并确认 NPM 可以访问 192.0.2.20:3000。

这里已有通配 DNS 重写覆盖管理域名。尚未配置解析时,可以在 AdGuard Home 的 DNS 重写中添加域名到 NPM 地址的记录。

2.2 后端账号与备份

先确认原 AdGuard Home 管理账号可以登录,保存当前 AdGuard Home 配置,并备份相关 NPM 站点及 Authentik 配置。备份应限制读取权限。

这里需要后端账号的明文密码。AdGuard Home 配置中的密码哈希不能直接放进 Basic 认证头,也不能作为 Authentik 的属性值使用。凭据保存在受限位置,不放进公开配置或截图。

接入前可在能够访问后端的终端测试 Basic 认证:

bash
1
2
curl --user 'ADGUARD_USERNAME' \ http://192.0.2.20:3000/control/status

只在命令里填写用户名,让 curl 交互式询问密码,避免写进 shell 历史。本次原凭据访问状态接口返回 HTTP 200。该命令仅适用于示例中的受控局域网;Basic 认证的编码不提供传输加密。

三、访问组与后端凭据

3.1 创建管理员访问组

在 Authentik 的“目录 → 组 → 创建”中填写名称 istoreos-site-a-adguard-admins,不启用组的超级用户权限。保存后进入成员管理,将允许访问该 AdGuard Home 的现有账号加入,例如 admin-user。

单独使用管理员访问组,避免把所有能够登录身份中心的账号都放行到 DNS 管理后台。

3.2 添加组属性

编辑该组的 Attributes,填写:

yaml
1
2
istoreos_site_a_adguard_username: 'REPLACE_WITH_ADGUARD_USERNAME' istoreos_site_a_adguard_password: 'REPLACE_WITH_ADGUARD_PASSWORD'

替换为 AdGuard Home 的实际后台账号密码后保存。键名供 Provider 引用,不能把实际用户名误填到 Provider 的 Username Key 字段中。

Authentik 支持从用户或其所属组的属性获取后端 Basic 凭据。这里放在专用组中,便于集中维护。Authentik Header authentication

组属性包含可读取的后端凭据,需要限制查看、修改和导出权限。不要允许普通用户通过可编辑个人属性覆盖这些键,也不要将它们写进公共蓝图或 Git 仓库。

四、Proxy Provider、应用与前哨

4.1 创建 Proxy Provider

在“应用程序 → 提供者 → 创建”中选择 Proxy Provider:

字段 配置
Name doratiger-istoreos-site-a-adguard
Authentication flow doratiger-authentication
Authorization flow doratiger-provider-authorization-implicit-consent
Invalidation flow doratiger-provider-invalidation
Mode Forward auth (single application)
External host https://adguard.example.com
Cookie domain 保留默认
Unauthenticated paths 留空

三个流程分别负责登录与 MFA、应用授权和 Provider 退出。这里沿用前文创建的流程,名称不同时选择自己的对应流程。

继续配置 HTTP Basic:

字段 配置
Send / Set HTTP-Basic Authentication 开启
HTTP-Basic Username Key istoreos_site_a_adguard_username
HTTP-Basic Password Key istoreos_site_a_adguard_password
Intercept header authentication 关闭

保存 Provider。这里开启的是向后端发送 Basic 凭据;浏览器仍使用 Authentik 的正常登录流程。后端地址由 NPM 管理,不填成云端身份服务地址。

4.2 创建应用并绑定组

在“应用程序 → 应用程序”中选择 with existing provider 创建应用:

字段 配置
Name iStoreOS Site A · AdGuard Home
Slug istoreos-site-a-adguard
Provider doratiger-istoreos-site-a-adguard
Launch URL https://adguard.example.com/

保存后打开应用的“策略/组/用户绑定”,创建组绑定,选择 istoreos-site-a-adguard-admins,Order 填 0,启用绑定,Negate 关闭,然后保存。

组成员关系、应用绑定、Provider 属性引用分别解决访问身份、授权条件和后端凭据来源,三处都需要配置。

4.3 复用现有 Outpost

进入“应用程序 → 前哨”,编辑 doratiger-truenas-proxy。在应用列表中增加刚创建的 AdGuard Home 应用,保留原来关联的其他应用,保存后检查前哨连接状态。

无需在 iStoreOS 上再部署一份 Outpost。NPM 向现有前哨发起认证子请求,再把业务请求转发到另一台主机上的 AdGuard Home。NPM 与前哨的 Docker 网络及别名必须保持可用。

五、NPM 代理配置

5.1 创建 HTTPS 站点

在 NPM 的“Hosts → Proxy Hosts”中新建:

Details 字段 配置
Domain Names adguard.example.com
Scheme http
Forward Hostname / IP 192.0.2.20
Forward Port 3000
Websockets Support 本次开启

SSL 中选择覆盖该域名的证书,开启 Force SSL。以下认证配置分别位于 Advanced 和 Custom Locations。Authentik NPM 配置说明

5.2 Advanced:认证路径与登录跳转

在该站点 Advanced 中填写:

nginx
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
port_in_redirect off; set $ak_http_host $host; location /outpost.goauthentik.io { proxy_pass http://doratiger-authentik-outpost:9000; proxy_set_header Host $ak_http_host; proxy_set_header X-Original-URL $scheme://$ak_http_host$request_uri; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-For $remote_addr; proxy_pass_request_body off; proxy_set_header Content-Length ""; } location @goauthentik_proxy_signin { internal; add_header Set-Cookie $auth_cookie; return 302 /outpost.goauthentik.io/start?rd=$scheme://$ak_http_host$request_uri; }

/outpost.goauthentik.io 交给前哨处理,包含认证检查和登录所需的路径。它不能再次被自己的认证子请求保护。命名 location 处理未登录结果,并保留返回地址。

本例对外使用标准 HTTPS 443,因此采用 $host。非标准端口部署应按官方模板保留包含端口的外部 Host。前哨别名也要替换为自己的实际网络名称。

5.3 Custom Locations:页面保护与 Basic 转发

在 Custom Locations 新增 /:

字段 配置
Location /
Scheme http
Forward Hostname / IP 192.0.2.20
Forward Port 3000

点击该行齿轮,在自定义配置中填写:

nginx
1
2
3
4
5
6
7
8
auth_request /outpost.goauthentik.io/auth/nginx; error_page 401 = @goauthentik_proxy_signin; auth_request_set $auth_cookie $upstream_http_set_cookie; add_header Set-Cookie $auth_cookie; auth_request_set $authentik_auth $upstream_http_authorization; proxy_set_header Authorization $authentik_auth;

不再外包一层 location / {},也不重复填写 proxy_pass,这些由 NPM 根据表单生成。

前两行要求请求先通过前哨检查;中间两行处理认证 Cookie;最后两行读取前哨响应中的 Basic 认证头并交给 AdGuard Home。这里的 Authorization 来自认证子请求,不能直接信任浏览器随意提供的身份头。

5.4 保存与检查

保存整个 Proxy Host,确认状态为 Online。重新打开编辑界面,检查 Advanced 和 / 自定义 location 的配置仍在。

通过 NPM 界面保存配置,避免直接修改容器中会被重新生成的文件。

管理 API 也应受相同认证检查,不为 /control/ 创建匿名例外。若另有自定义 location 直连同一管理后端,需要逐项检查是否绕过根路径的保护。

六、登录验证与维护

6.1 验证结果

配置完成后,用无痕窗口访问 https://adguard.example.com/,先跳转到 Authentik,完成登录和 MFA 后直接进入 AdGuard Home,没有再出现第二次密码输入。原来的 DNS 查询正常,过滤和重写配置保持原样。

非成员访问和单点退出还没有单独测试,后续再检查前哨与后端会话的退出情况。

6.2 管理入口与 DNS 服务

NPM 的 HTTPS 入口保护的是管理页面和管理 API。普通 DNS 查询仍按 AdGuard Home 原配置工作;本次也未把 DoH 等其他入口纳入这一代理站点。

直接访问 iStoreOS 的管理 IP 和端口时,仍由 AdGuard Home 要求输入原账号密码。

6.3 凭据维护与回退

修改 AdGuard Home 后台密码后,同步修改 Authentik 组属性,并重新认证验证。属性在向代理认证时读取,已有会话可能继续使用旧值。

回退时先移除 NPM 的认证配置,恢复直接代理管理页,此时继续由 AdGuard Home 要求输入原账号密码。再从共享前哨中移除这个应用,保留其他应用关联,不停掉仍被其他服务使用的 Outpost。

七、配置问题与解答

7.1 通过 Authentik 后仍出现后端登录页

Q:统一认证已经成功,为什么还要输入 AdGuard Home 密码?

检查 Provider 的 Basic 发送开关、用户名和密码属性键、当前用户的组成员关系,以及 NPM 转发 Authorization 的两行配置。再用原凭据单独测试后端 Basic 认证。只有身份检查成功,而没有向后端提供可用凭据,就无法消除第二次登录。

7.2 应用在 iStoreOS,为什么前哨在 TrueNAS

Q:前哨必须与被保护的服务装在同一台主机吗?

本例 NPM 与前哨在同一 Docker 网络,方便认证子请求调用;NPM 通过局域网访问 iStoreOS 后端。前哨所在位置不决定应用所在位置,关键是代理到前哨、代理到后端、前哨到身份服务的网络均可达。

7.3 新增用户与后台权限

Q:Authentik 新增用户,会自动创建 AdGuard Home 用户吗?

本方案不做用户同步或自动注册。Authentik 应用组控制谁能访问,代理使用组属性中的既有 AdGuard Home 管理账号。增加组成员相当于允许其使用这个后台管理身份,应按管理员权限处理。

7.4 需要在 NPM 新建 Authentik 插件吗

Q:NPM 界面里找不到 Authentik 开关。

无需插件。配置位于 Proxy Host 的 Advanced,以及 Custom Locations 的 / 齿轮内。站点 Details 仍填写 AdGuard Home 的后端地址,不能为了接入认证把普通业务转发目标改为云端 Authentik。

参考

手机扫码阅读
本文作者: 有次元袋的 tiger
本文链接: https://www.superheaoz.top/2026/11/62482/
版权声明: 本站点所有文章除特别声明外,均采用 CC BY-NC-SA 4.0 许可协议。转载请注明来自 我的个人天地!