统一认证实践(9)Authentik 接入 Jellyfin OIDC 与 LDAP 统一账号
创建于 2026-11-16
更新于 2026-11-18
科技
docker
ldap
truenas
authentik
oidc
jellyfin
11962 字 · 约 40 分钟

前言

Jellyfin 已经有自己的用户、观看进度和收藏。接入统一认证时,我希望继续使用原账号,同时让新用户直接通过 DoraTiger Auth 登录,在第一次访问时创建 Jellyfin 账号,不再单独注册。

网页登录采用 OIDC,普通用户名密码登录通过 LDAP 复用 Authentik 账号,两种方式都进入原 Jellyfin 用户。

本次使用 Jellyfin 12.4.0.0、Authentik 2026.8.5、K0lin 分支的 SSO-Auth 5.1.1 和官方 LDAP Authentication 24.0.0.0。与 Gitea 原生支持 OIDC 不同,Jellyfin 需要安装第三方认证插件。接入过程中出现过误建账号,最后修正关联,并改为沿用 Authentik 用户名。

一、认证结构

1.1 OIDC 插件与反向代理

text
1
2
3
4
5
浏览器 → NPM HTTPS → Jellyfin SSO-Auth 插件 ↕ OIDC 云端 DoraTiger Auth ↓ 应用访问组、登录流程与 MFA

NPM 继续负责 HTTPS 和业务反代,不添加 Forward Auth,TrueNAS 上的 Proxy Outpost 也不参与 OIDC。LDAP 密码登录则由单独的 LDAP Outpost 接收请求,两种前哨用途不同。Jellyfin 插件读取发现文档、处理授权回调,再建立 Jellyfin 自己的用户会话。

Authentik 管理身份和应用访问资格;媒体库权限、收藏和观看记录仍属于 Jellyfin 用户。OIDC 接入不会把影视文件传到身份服务器,也不等于把 Jellyfin 用户数据库迁到 Authentik。

原生 OIDC 的基本关系可以参考 统一认证实践(5)Authentik 接入 Gitea OIDC 与 LDAP 统一账号,但两者的账号匹配实现不同,不能照搬 Gitea 的关联行为。

1.2 插件版本

旧的 9p4/jellyfin-plugin-sso 仓库已经归档。本次选择 K0lin 维护分支的正式发行版,其 5.1 系列面向 Jellyfin 12。插件仍有 alpha 提示,升级时需要同时核对 Jellyfin ABI 和插件发行说明。

本文后面的菜单与字段按 5.1.1 编写。不要在 Jellyfin 12 中直接安装旧教程里的 10.x 插件包,也不要为了兼容自动改用 nightly。

1.3 示例对象

对象 示例
身份服务 https://auth.example.com
Jellyfin https://jellyfin.example.com
Authentik 应用 Slug truenas-jellyfin
Provider doratiger-truenas-jellyfin
普通访问组 truenas-jellyfin-users
管理员组 truenas-jellyfin-admins
插件认证源名称 DoraTiger
已有 Jellyfin 用户 media-admin

部署位置写入后台对象名称;插件认证源名称还会出现在回调路径中,改名时必须同步修改回调。

二、备份与插件安装

2.1 配置和数据库备份

在 TrueNAS 应用详情核对 Jellyfin /config 的实际宿主机挂载。以下以 /mnt/pool/apps/jellyfin/config 为示例,执行位置为 TrueNAS 宿主机,容器名先用 docker ps 确认。

暂停播放并停止应用后,备份配置、插件和用户数据库。Jellyfin 12 的数据库位于 /config/data/jellyfin.db;如目录中有 WAL 文件,一并保留。本次采用停机归档,避免复制过程中数据库继续变化。

bash
1
2
3
4
5
6
7
8
9
# 替换实际容器名和挂载路径 backup_dir=/root/jellyfin-before-sso install -d -m 700 "$backup_dir" docker stop JELLYFIN_CONTAINER umask 077 tar -czf "$backup_dir/config-and-users.tar.gz" \ -C /mnt/pool/apps/jellyfin/config config plugins data # 备份成功后启动;备份失败也应先检查并恢复服务 docker start JELLYFIN_CONTAINER

这里的示例归档整个 data 目录,实际部署时可以根据版本缩小到需要的数据库和配置。影视原文件另有自己的备份;不要把整个媒体目录误当成插件配置一起打包。Authentik 数据库也应在增加 Provider 前备份。

2.2 安装 SSO-Auth

在 Jellyfin“控制台 → 插件 → 存储库”添加仓库:

text
1
https://raw.githubusercontent.com/K0lin/jellyfin-plugin-sso/manifest-release/manifest.json

名称可填 SSO-Auth (K0lin)。保存后刷新插件目录,选择兼容 Jellyfin 12 的 5.1.1 正式版本,安装并重启 Jellyfin。检查插件列表状态是否为 Active。

本次实机使用发行 ZIP 安装:核对 manifest 校验值后,解压到 /config/plugins/SSO-Auth_5.1.1/,保留 DLL 和 meta.json,文件所有者与 Jellyfin 的运行用户一致,再重启容器。目录安装和 ZIP 安装二选一,不要重复装两个版本。

插件的实际配置文件是:

text
1
/config/plugins/configurations/SSO-Auth.xml

它包含客户端密钥,不公开、不提交。建议优先从插件管理界面保存;直接改文件时必须停止服务,避免内存中的旧配置覆盖文件。

三、Authentik 应用配置

3.1 访问组与管理员组

在“目录 → 组”分别创建 truenas-jellyfin-users 和 truenas-jellyfin-admins,两组都不启用 Authentik 超级用户权限。

先把准备关联原管理员的身份加入两组。普通用户只加入 users 组。users 决定能否进入应用,admins 由插件解释为 Jellyfin 管理权限,不代表 Authentik 管理权限。

3.2 OAuth2/OpenID Connect Provider

进入“应用程序 → 提供者 → 创建”,选择 OAuth2/OpenID Connect:

字段 配置
Name doratiger-truenas-jellyfin
Authentication flow 复用 doratiger-authentication
Authorization flow doratiger-provider-authorization-implicit-consent
Invalidation flow doratiger-provider-invalidation
Client type Confidential
Grant types Authorization code
Signing key 现有签名证书
Issuer mode 每个 Provider 独立发行者
Subject mode hashed_user_id

三个流程的创建见 统一认证实践(2)Authentik DoraTiger 自建流程与默认配置清理。保存生成的 Client ID 和 Client Secret,稍后填入插件。

Redirect URI 添加下列地址,匹配方式 Strict,类型 Authorization:

text
1
https://jellyfin.example.com/sso/OID/redirect/DoraTiger

这里的 DoraTiger 必须与插件源名称一致,不能填应用 Slug。最终配置使用新路径 /redirect/,不混用旧的 /r/。

3.3 组声明映射

进入“自定义 → 属性映射 → 创建”,选择 OAuth2/OpenID Scope Mapping。名称填 doratiger-truenas-jellyfin-groups,Scope name 填 groups,表达式为:

python
1
2
3
4
5
6
7
8
return { "groups": [ group.name for group in request.user.ak_groups.filter( name__in=["truenas-jellyfin-users", "truenas-jellyfin-admins"] ) ] }

保存后编辑 Provider,在 Scope mappings 中选择标准 openid、profile、email,再加入这个 groups 映射。开启将声明包含在 ID Token 中。标准 profile 映射提供 preferred_username,它是后面创建可读用户名的来源。

3.4 应用和绑定

在“应用程序 → 应用程序”选择 with existing provider 创建应用,名称填 TrueNAS · Jellyfin,Slug 填 truenas-jellyfin,Provider 选择上面创建的对象,Launch URL 填 https://jellyfin.example.com/。

保存后,在应用详情的“策略/组/用户绑定”添加 users 组,Order 为 0,启用,Negate 关闭。应用策略引擎模式使用 ALL。

旧账号关联期间,再添加一个指向本人 Authentik 用户的临时绑定,Order 为 1。ALL 表示既要在 users 组内,又必须是当前关联的这个人。关联验证完成后移除临时用户绑定,保留组绑定。

四、Jellyfin 插件配置

4.1 OIDC 认证源

使用原管理员进入“控制台 → 插件 → SSO-Auth”,在 OpenID 配置中增加名为 DoraTiger 的认证源:

字段/配置键 最终配置
Enabled 开启
OidEndpoint https://auth.example.com/application/o/truenas-jellyfin/
OidClientId / OidSecret Provider 对应的 Client ID / Secret
OidScopes openid、profile、email、groups
RoleClaim groups
Roles truenas-jellyfin-users
AdminRoles truenas-jellyfin-admins
EnableAuthorization 开启
DefaultUsernameClaim preferred_username
SchemeOverride https
NewPath 开启

Issuer 填发行者地址,不把 Authentik 登录页当作发现地址。保存后可以检查下面的发现文档是否正常返回 JSON:

text
1
https://auth.example.com/application/o/truenas-jellyfin/.well-known/openid-configuration

HTTPS、发行者名称和端点校验保持开启,不使用“跳过验证”处理回调配置问题。

4.2 媒体库与管理员权限

本次 EnableAllFolders=true,进入应用的普通用户可访问全部媒体库;如果只开放部分库,应关闭该选项并填写允许的库,而不是把访问组等同于分库权限。

PreserveAdminPermissions=true 用于保留原管理员兜底。它也意味着移除 admins 组不会自动剥夺既有管理员权限,需要同时在 Jellyfin 中降权。

直播访问采用角色控制:开启 EnableLiveTvRoles,在 LiveTvRoles 和 LiveTvManagementRoles 中填 admins 组,保留原管理员的直播权限;默认直播访问和管理关闭。下载权限不强制重写。保存后重新打开配置核对,避免字段默认值覆盖原账号权限。

4.3 登录页入口

在 Jellyfin 的品牌设置中找到 Login disclaimer,保留原内容后追加:

html
1
2
3
4
5
<form action="/sso/OID/start/DoraTiger"> <button class="raised block emby-button button-submit"> DoraTiger Auth 登录 </button> </form>

在 Custom CSS 中追加:

css
1
2
3
.disclaimerContainer { display: block; }

保存后用无痕窗口检查按钮和原密码表单均存在。这里使用插件提供的原生入口,不修改 Jellyfin Web 的编译产物。

五、旧账号关联与误建账号修正

5.1 关联操作

先用原 Jellyfin 密码登录,再在同一浏览器、同一域名打开:

text
1
https://jellyfin.example.com/SSOViews/linking

在 DoraTiger 下点击 Link account,确认跳转的是自己的 Authentik 身份,完成认证后回到 Jellyfin。重新查看关联列表,核对用户仍是原账号,观看进度、收藏和管理员入口都存在。

关联入口和登录页的“DoraTiger Auth 登录”用途不同。未建立映射时直接执行普通 SSO 登录,可能进入自动建号路径。

5.2 本次误建账号

第一次认证后出现了长用户名,检查发现 OIDC 身份指向新建用户,原账号仍然存在。当时使用的是 DefaultUsernameClaim=sub,长字符串就是不透明身份标识,而不是原用户名。

这包含两个问题:身份关联目标不对,以及用户名来源不适合日常使用。只把长用户名改成原用户名,不能修复原用户 ID 的归属,也不能自动合并观看记录。

处理时先保存插件配置,再核对三个值:原账号 ID、新账号 ID、CanonicalLinks 中这个身份对应的用户 ID。确认两侧身份归属后,通过插件配置接口将该项目标改回原账号。没有复制或覆盖原数据库。

管理员维护接口为:

text
1
2
GET /Plugins/505ce9d1-d916-42fa-86ca-673ef241d7df/Configuration POST /Plugins/505ce9d1-d916-42fa-86ca-673ef241d7df/Configuration

读取完整配置、只修改目标认证源中的 CanonicalLinks、保留其他字段再保存。该响应包含客户端密钥,不能直接贴进终端日志或聊天。操作需要相应管理权限;权限不足时使用管理员界面,不通过改库绕过。

5.3 关联验证

修正后用新的无痕窗口重新执行 SSO 登录,已经回到原账号,原记录和播放正常。旧窗口可能还持有误建账号的会话,不能据此判断修正无效。

确认原账号可用后,再处理误建账号。此前尝试禁用重复用户的策略 API 返回 403,因此没有将请求成功与实际禁用混为一谈;后续用户列表复核时,重复账号已不在列表中。

六、新用户自动注册与用户名映射

6.1 自动建号与组限制

此插件没有独立的 Auto Register 开关。允许身份完成 SSO、又找不到用户关联时,会尝试查找同名用户或创建用户。因此本文通过 Authentik 应用授权控制开放范围。

原账号验收后,删除应用上的临时本人绑定,只保留 users 组绑定。新成员开通顺序为:

  1. 在 Authentik 创建或邀请用户。
  2. 核对用户名不会冒用已有 Jellyfin 用户,再加入 truenas-jellyfin-users。
  3. 用户点击 DoraTiger Auth 登录。
  4. 插件收到身份和组声明,首次登录创建 Jellyfin 用户,随后回到同一账号。

加入组本身不会立即创建 Jellyfin 用户。没有加入组时,Authentik 的应用授权被拒绝,不能通过这条入口自动注册。

6.2 从 sub 改为 preferred_username

最终将 DefaultUsernameClaim 改为 preferred_username,新用户直接使用 Authentik 用户名。现有原账号的 CanonicalLinks 也同步从旧 sub 键迁移到 Authentik 用户名键,值仍为原 Jellyfin 用户 ID。

配置 原方案 最终方案
用户名声明 sub preferred_username
新用户名称 不透明标识 Authentik 用户名
已有用户关联键 原 sub 对应 Authentik 用户名
已有用户 ID 原用户 ID 保持原用户 ID

Authentik Provider 的 Subject mode 仍是 hashed_user_id,没有修改协议本身的 sub。改变的是插件选择哪个声明作为本地用户名和关联键。

6.3 用户名变更与权限撤销

该插件把用户名同时用作关联依据,与 Gitea 按外部身份关联的行为并不完全相同。Authentik 用户改名时,需要同步迁移 CanonicalLinks;不要把已使用过的用户名重新分配给无关人员。对于既有 Jellyfin 用户,先核对归属,再开放同名 Authentik 用户访问。

从访问组移除成员只能限制后续 OIDC 授权,不会删除其 Jellyfin 数据,也不能保证电视端已存在的会话立即失效。停用用户时还要在 Jellyfin 处理会话和账号状态。

七、LDAP 密码认证

7.1 绑定流程与查询账号

LDAP 接收用户名和密码,无法展示网页上的输入、Passkey 或跳转阶段。进入 Authentik“流程和阶段”,新建专用身份认证流程,名称 DoraTiger LDAP authentication,Slug doratiger-ldap-authentication,Designation 选择 Authentication。

在阶段列表新建以下对象,再进入流程的“阶段绑定”添加:

对象 类型与配置 绑定位置
doratiger-ldap-password Password,启用用户数据库标准密码与应用程序密码后端 由识别阶段引用
doratiger-ldap-identification Identification,用户字段选 username,Password stage 选择上面的密码阶段 流程 Order 10
doratiger-ldap-login User Login,完成身份登录 流程 Order 30

密码阶段由识别阶段调用,不再作为独立流程绑定重复执行。已有相同 LDAP 流程时可复用;浏览器原来的 MFA 流程保持不变。本次 LDAP Provider 的 MFA support 关闭,普通客户端使用 Authentik 密码,不代表该路径执行了网页 MFA。

在“目录 → 用户”创建服务账号 svc-example-jellyfin-reader,使用独立随机密码,账号类型为 Service account,不授予超级管理员权限。它只用于目录查询,不是实际观看影片的用户。

7.2 LDAP Provider 与应用绑定

在“应用程序 → 提供者”创建 LDAP Provider:

字段 配置
Name doratiger-truenas-jellyfin-ldap
Bind flow/Authorization flow doratiger-ldap-authentication
Invalidation flow 现有 doratiger-provider-invalidation
Base DN ou=jellyfin,dc=ldap,dc=example,dc=com
Bind mode / Search mode Direct
TLS server name ldap.example.internal
Certificate SAN 包含上述名称的服务证书
MFA support 关闭

Base DN 是目录中的命名空间,不要求对应公网 DNS。多个 LDAP Provider 共用前哨时,各自使用不同 Base DN。服务证书从“系统 → 证书”管理,导入证书及私钥;客户端只安装用于验证的证书,不复制私钥。

选择 with existing provider 新建应用,Slug 为 truenas-jellyfin-ldap,引用此 LDAP Provider。原 OIDC 应用保留。新应用的策略引擎模式设为 ANY,在“策略/组/用户绑定”分别绑定 truenas-jellyfin-users 和查询账号,Order 0、1,均启用、不取反。这里允许组内用户认证,也允许服务账号查询,两者取其一。

在 RBAC 角色中创建 doratiger-jellyfin-ldap-search。对这个 LDAP Provider 授予 Search full LDAP directory 对象权限,再把查询账号加入该角色。不要授予整个身份系统的管理权限。查询账号可以读取目录,因此客户端仍需明确填写访问组过滤条件。

7.3 本地 LDAP 前哨

在“应用程序 → 前哨”新建 LDAP 类型前哨,或给已有 LDAP 前哨增加上述 Provider。本次复用本地前哨,保留其他应用 Provider。手动部署的最小 Compose 示例为:

yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
services: ldap: image: ghcr.io/goauthentik/ldap:2026.8.5 restart: unless-stopped env_file: ./outpost.env networks: jellyfin: aliases: - ldap.example.internal networks: jellyfin: external: true name: YOUR_JELLYFIN_NETWORK

在 TrueNAS 的自定义应用中使用该 Compose 时,把 env_file 改为宿主机绝对路径;网络名从实际 Jellyfin 容器检查结果填写。若与其他应用共用前哨,在原配置中增加网络,不覆盖已有网络。凭据文件权限设为 600,内容如下,占位符替换为前哨页面给出的 token:

dotenv
1
2
3
AUTHENTIK_HOST=https://auth.example.com AUTHENTIK_INSECURE=false AUTHENTIK_TOKEN=REPLACE_WITH_OUTPOST_TOKEN

此部署不发布宿主机端口。Jellyfin 经同一 Docker 网络访问 ldap.example.internal:6636;3389 为 LDAP,6636 为 LDAPS。前哨还必须能访问云端 Authentik。NPM 的普通 HTTPS 代理保持原样。

7.4 Jellyfin LDAP 插件

进入“控制台 → 插件 → 目录”,从官方仓库安装与 Jellyfin 12 兼容的 LDAP Authentication 24.0,暂停播放后重启,确认 LDAP-Auth 为 Active。打开插件设置:

字段 配置
LdapServer / LdapPort ldap.example.internal / 6636
UseSsl / UseStartTls true / false
SkipSslVerify false
LdapRootCaPath /config/plugins/configurations/doratiger-ldap.crt
LdapBindUser cn=svc-example-jellyfin-reader,ou=users,ou=jellyfin,dc=ldap,dc=example,dc=com
LdapBindPassword 查询账号独立密码
LdapBaseDn / LdapAdminBaseDn ou=users,ou=jellyfin,dc=ldap,dc=example,dc=com
LdapSearchFilter (memberOf=cn=truenas-jellyfin-users,ou=groups,ou=jellyfin,dc=ldap,dc=example,dc=com)
LdapAdminFilter (memberOf=cn=truenas-jellyfin-admins,ou=groups,ou=jellyfin,dc=ldap,dc=example,dc=com)
LdapSearchAttributes / LdapUsernameAttribute cn / cn
LdapUidAttribute uid
CreateUsersFromLdap true
AllowPassChange false
EnableAllFolders true,按实际媒体库授权调整

将服务端证书的信任材料保存到表中的容器路径,文件必须可由 Jellyfin 读取。自签证书需明确导入并验证,不用跳过校验代替。插件实际配置文件名为 LDAP-Auth.xml,其中有查询密码,应限制权限并纳入受保护备份。

保存后执行插件的服务器连接测试、用户与管理员过滤测试,再搜索原用户名。连接和绑定都应成功,管理员集合应属于允许用户集合。Authentik 的 cn 是用户名,uid 是稳定标识,不能把 uid 当作可读用户名。

7.5 原账号与 OIDC 共用

安装插件不会自动把原账号改为 LDAP 用户。在“控制台 → 用户”编辑原用户的 Authentication provider,选择 LDAP 提供者并保存,其他权限保持原样。已有用户与 Authentik 用户须先核对身份归属和用户名,不能只凭同名合并账号。

本次还在 LDAP 插件配置的 LdapUsers 中明确关联了目录 UID 和原 Jellyfin 用户 ID。界面没有暴露关联列表时,可通过管理员插件配置接口读取完整配置,仅增加对应映射后保存:

text
1
2
GET /Plugins/958aad66-3784-4d2a-b89a-a7b6fab6e25c/Configuration POST /Plugins/958aad66-3784-4d2a-b89a-a7b6fab6e25c/Configuration

LdapUsers 的单项结构如下,两个 ID 必须来自实际查询,不能照抄或使用用户名代替:

json
1
2
3
4
5
{ "LinkedJellyfinUserId": "EXISTING_JELLYFIN_USER_ID", "LdapUid": "ACTUAL_LDAP_UID", "ProfileImageHash": "" }

这是完整插件配置中的数组元素,不是可单独 POST 的配置。保留原数组其他项目,接口响应含查询密码,不输出到公开日志。原账号 ID 不变,观看记录和收藏仍归属于原用户。

随后进入 SSO-Auth 的 DoraTiger 配置,将 Set default Provider / DefaultProvider 设为:

text
1
Jellyfin.Plugin.LDAP_Auth.LdapAuthenticationProviderPlugin

这样 OIDC 登录后仍保留 LDAP 密码认证。CanonicalLinks、preferred_username 和原用户 ID 不改。新用户从 OIDC 先登录时也会获得 LDAP 提供者;从 LDAP 先登录时按 cn 建号。新成员仍需检查首次建号及两条路径的同账号归属,不把管理员成功当作普通用户测试。

7.6 登录验收与延迟

我先用 LDAP 密码登录,退出后用 OIDC 登录,再退出并用密码登录。三次都回到原账号,之前的播放记录仍在。密码登录现在输入 Authentik 密码,原 Jellyfin 本地密码不再用于这个用户的普通登录。

接入后感受到登录比原来慢。当前路径为:

text
1
客户端 → Jellyfin → 本地 LDAP Outpost → 云端 Authentik

Direct 模式下本地前哨仍需访问云端,并不是离线密码库。新增网络往返可以解释一部分耗时,但目前没有分段测量,不能把所有延迟都归因于网络,也没有为了提速开启缓存模式。已有播放会话使用 Jellyfin 自己的会话,不会对每个视频分片重新进行 LDAP 密码认证。

支持 Quick Connect 的客户端仍可从已登录浏览器授权。电视、手机逐型号兼容性和 Quick Connect 尚未逐一验证。客户端说明

备份覆盖 LDAP 与 SSO 插件配置、用户数据库和 Authentik 对象。回退时先恢复原用户的认证提供者及 SSO DefaultProvider,再停用 LDAP;不要整库恢复覆盖新增观看记录。移除访问组限制后续登录,已有会话还需在 Jellyfin 撤销。共用前哨的证书续期应同时更新各客户端信任材料。

八、配置问题与解答

8.1 插件已加载,但没有认证源

Q:为什么 SSO-Auth 为 Active,GetNames 却返回空列表?

本次最初按命名空间猜测了 XML 文件名,插件没有读取。实际文件是 SSO-Auth.xml。修正后源列表出现 DoraTiger,完整授权链能够到达 Authentik 登录流程。配置文件名应以运行版本为准。

8.2 品牌接口返回 405

Q:能读取品牌设置,为什么保存失败?

本次读取 /Branding/Configuration 成功,但向同一路径 POST 返回 405。实际写入使用 /System/Configuration/branding,返回 204。通过控制台配置时无需手写接口;自动化维护应核对运行版本的读写路径。

8.3 已有账号登录成功是否等于新用户验证完成

Q:是否已经证明所有用户都能自动注册?

原账号关联、插件自动建号和普通用户权限是三个不同检查。本次误建账号证明建号路径曾运行,修正后原账号登录成功;这不能代替普通新身份的完整权限测试。

参考

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