统一认证实践(12)Authentik 接入 Navidrome 与音乐客户端认证
创建于 2026-11-16
更新于 2026-11-18
科技
docker
truenas
authentik
nginx
navidrome
5063 字 · 约 17 分钟

前言

Navidrome 的网页和音乐客户端使用不同的登录方式。网页希望通过 DoraTiger Auth 直接进入原音乐库,手机上的 Subsonic 客户端则继续使用 Navidrome 账号。将整个域名都重定向到身份中心,会让音乐客户端收到无法处理的网页登录页面。

本次基于现有 Navidrome 0.55.2、Authentik 2026.8.5 和 NPM 配置:网页通过 Forward Auth 检查身份,再向 Navidrome 传递可信用户名;/rest/ 保留原生认证。

一、认证路径

text
1
2
网页 → NPM → Authentik 前哨检查 → 可信用户名头 → Navidrome 客户端 → NPM /rest/ → 清除外部身份头 → Navidrome 原生认证

这不是 OIDC 账号关联。Navidrome 从可信代理的请求头获取用户名,找到已有同名用户后继续使用原音乐库和权限。

本文的配置字段适用于 0.55.2:ReverseProxyUserHeader 和 ReverseProxyWhitelist。新版文档已使用 ExtAuth 配置,不能只对照最新版页面修改旧实例。版本源码

网页身份头认证不会同步 Navidrome 密码,用户名相同也不意味着音乐客户端可以输入 Authentik 密码。当前实例没有配置 OIDC 或 LDAP,/rest/ 继续使用 Navidrome 自己的凭据。选择后续方案时需单独验证 Subsonic 客户端支持,不能只用网页免密登录作为统一账号已完成的依据。

二、容器网络与原数据

2.1 原实例转换

TrueNAS 原目录应用不方便加入已有的外部 Docker 网络。本次使用 TrueNAS 的 app.convert_to_custom 将原应用转为自定义应用,保留已有镜像、运行配置和挂载,再加入 NPM 网络。

操作前导出应用配置并备份 Navidrome 数据库。转换后核对 /data 与 /music 的宿主路径、UID/GID、扫描参数和端口,不重新初始化空数据目录。转换为自定义应用后,镜像升级由自定义应用维护,不再沿用原目录应用的升级入口。

2.2 自定义配置示例

下面是已有应用所需网络与环境字段的示例,挂载路径、UID/GID 和其他原参数需从当前实例保留:

yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
services: navidrome: image: deluan/navidrome:0.55.2 restart: unless-stopped environment: ND_PORT: "30043" ND_REVERSEPROXYUSERHEADER: X-Authentik-Username ND_REVERSEPROXYWHITELIST: "192.0.2.42/32" volumes: - /mnt/pool/apps/navidrome/data:/data - /mnt/pool/media/music:/music:ro networks: npm_backend: aliases: - navidrome-web networks: npm_backend: external: true name: npm_backend

这里的 192.0.2.42/32 只是 NPM 容器来源地址的示例,必须从实际网络检查结果替换。若 NPM 通过 IPv6 连接,还需添加其精确 /128 地址,用逗号分隔。没有 ports,业务只从 NPM 网络进入。

2.3 可信来源

Navidrome 校验的是到达后端的代理来源地址,不能直接填浏览器地址、域名解析地址或整个局域网。

本次避免经过宿主机发布端口:那条路径可能让后端只看到 Docker 网关,信任网关会扩大能够注入身份头的范围。NPM 与 Navidrome 直接连接后,白名单只允许 NPM 当前 IPv4/IPv6 地址。

NPM 重建后要重新核对地址。地址变化应更新精确白名单,不为省事扩大成整个 Docker 网段。外部认证说明

三、Authentik 应用配置

3.1 访问组

在“目录 → 组”创建 truenas-navidrome-users,不启用超级用户权限,加入允许访问音乐库的用户。该组独立于其他应用,不保存或继承 AdGuard 等服务的凭据。

准备接入已有用户时,先确认 Authentik 用户名与 Navidrome 用户名一致。本例以 music-user 表示两侧已经核对的原账号。

3.2 Proxy Provider

创建 Proxy Provider,填写:

字段 配置
Name doratiger-truenas-navidrome
Mode Forward auth (single application)
External host https://music.example.com
Authentication flow doratiger-authentication
Authorization flow doratiger-provider-authorization-implicit-consent
Invalidation flow doratiger-provider-invalidation
HTTP Basic 转发 关闭
Unauthenticated paths 留空,由 NPM 单独处理客户端路径

保存后以 with existing provider 创建应用,名称 TrueNAS · Navidrome,Slug truenas-navidrome,Launch URL 填 https://music.example.com/app/,选择上述 Provider。

在应用的策略/组/用户绑定中添加 truenas-navidrome-users,Order 为 0,启用,Negate 关闭。编辑现有 TrueNAS Proxy Outpost,在列表中加入该应用并保存。

网页使用身份头,不需要把 Navidrome 明文密码交给 Provider。客户端凭据继续由 Navidrome 管理,改密码不会自动同步到其他应用。

四、NPM 路由配置

4.1 HTTPS 站点

创建或编辑 Proxy Host:域名 music.example.com,上游 http://navidrome-web:30043,启用 WebSocket 支持,配置证书并开启 Force SSL。

Advanced 中添加认证路径与登录跳转,authentik-outpost 替换为现有前哨别名:

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://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; }

这些配置按标准 HTTPS 443 编写。Authentik Nginx 模板

4.2 网页根路径

在 Custom Locations 添加 /,上游与主站一致。齿轮中的自定义配置填写:

nginx
1
2
3
4
5
6
7
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_username $upstream_http_x_authentik_username; proxy_set_header X-Authentik-Username $authentik_username; proxy_set_header Remote-User "";

用户名从认证子请求结果取得,并覆盖发给后端的同名头。不能把浏览器自行填写的 X-Authentik-Username 直接透传。

4.3 Subsonic 客户端路径

再添加 /rest/ Custom Location,上游仍为 navidrome-web:30043,自定义配置为:

nginx
1
2
3
auth_request off; proxy_set_header X-Authentik-Username ""; proxy_set_header Remote-User "";

它不经过网页登录,但仍由 Navidrome 验证原生凭据。清空身份头后,不能通过伪造头冒充已登录用户。没有在服务端全局关闭认证,也没有把全部 API 都匿名放行。

保存 NPM 配置后检查站点在线状态,确认 /rest/ 比根路径更具体,客户端请求不会落入网页认证分支。

五、账号与客户端

5.1 网页原账号

用无痕窗口访问 /app/,完成 Authentik 登录后应直接回到原用户。核对管理员状态、播放列表及收藏,再播放音乐。本次原账号进入音乐库和播放已确认正常。

源码中的身份头登录会在找不到同名用户时尝试建号;本次已有用户数据库,新身份不应被当作首次初始化管理员。不要把未使用过的空数据库与已有实例混用,开放其他用户前仍需检查账号权限。

5.2 音乐客户端

客户端继续填写 https://music.example.com 和 Navidrome 自己的用户名、密码。OIDC 或 Forward Auth 不会把 Authentik 密码自动写入 Navidrome。

先用正确凭据验证 Subsonic 请求,再用错误凭据或无凭据请求确认拒绝;还要检查仅伪造身份头不能登录。本次原生认证正反检查通过,网页和客户端分别走各自路径。

5.3 撤销权限

移出 Authentik 访问组只影响网页认证入口。用户仍可能持有 Navidrome 密码和已有会话,停用时需要在 Navidrome 同时处理;不能把组成员变化当成所有音乐客户端立即失效。

六、配置问题与解答

6.1 HTTP/2 协议错误

Q:浏览器出现 ERR_HTTP2_PROTOCOL_ERROR,是否需要关闭 HTTP/2?

本次迁移期间代理上游名称尚未可解析,NPM 曾把站点标记离线。容器网络和别名就绪后重新保存代理配置,我先用无痕窗口确认匿名请求会跳到 Authentik,再登录打开原音乐库播放一首歌。恢复访问后,NPM 仍启用 HTTP/2。

6.2 登录后仍出现 Navidrome 密码框

Q:Authentik 已通过,为什么还不能免密进入?

依次核对响应中的用户名、NPM 是否覆盖写入身份头、后端看到的代理来源是否在精确白名单内,以及两侧用户名是否一致。通过前哨只说明入口认证成功,不代表 Navidrome 接受了身份头。

6.3 手机客户端被跳转到登录页

Q:浏览器正常,客户端却报响应格式错误?

检查 /rest/ 是否错误继承网页 Forward Auth。客户端需要原生 API 响应,不能把 HTML 登录页当作 Subsonic 结果。修复路由后仍要保留 Navidrome 凭据校验。

七、备份与升级

保留原应用定义、Navidrome 数据库和 NPM 站点配置。自定义应用升级时检查镜像版本、身份头字段和网络地址,尤其不要直接把新版 ExtAuth 配置复制到 0.55.2。

回退时恢复原应用配置和 NPM 路由,保持原数据库挂载。若恢复宿主端口发布,要重新检查直接访问是否仍需要密码,不保留可伪造身份头的入口。

参考

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