SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场jellyfin-security-plugin

jellyfin-security-plugin

安全与审计

查看项目

更新于 10-15 17:01

技能介绍

用途

JellyfinSecurity 是一个面向 Jellyfin 媒体服务器（10.11+）的服务端认证与加固插件，属于 ara.so 的 Security Skills 集合。它在服务端统一为所有 Jellyfin 客户端（Web、Android、iOS、Roku、Fire TV、Kodi）以及 Sonarr、Radarr、Tautulli 等服务集成提供认证增强与安全防护，用户端无需修改代码。

主要能力

  • 多因素认证：TOTP（Authy/Google Authenticator）、Passkeys（WebAuthn/FIDO2）、邮件 OTP、恢复码。
  • 单点登录：OIDC 提供商集成（Authentik、Authelia、Keycloak、Pocket ID 等）。
  • 暴力破解防护：基于 IP 的速率限制与封禁，阈值可配置。
  • 设备管理：通过二维码进行电视设备配对、受信任浏览器令牌。
  • 网络控制：LAN 绕过、按用户 IP 允许列表、不可能旅行检测。
  • 审计日志：完整的登录/登出/配置变更事件跟踪。
  • 二次验证（Step-up）：在执行敏感管理操作前重新验证 TOTP/Passkey/IdP。

安装方式

通过 Jellyfin 管理后台（推荐）：

  1. 打开 Jellyfin → Admin Dashboard → Plugins → Repositories。
  2. 添加仓库：Name 为 JellyfinSecurity，URL 为 https://raw.githubusercontent.com/ZL154/JellyfinSecurity/main/manifest.json。
  3. 进入 Catalog → 搜索 "Security" → Install。
  4. 重启 Jellyfin 服务器。

手动安装：

RELEASE_URL="https://github.com/ZL154/JellyfinSecurity/releases/latest/download/JellyfinSecurity.zip"
PLUGIN_DIR="/var/lib/jellyfin/plugins/JellyfinSecurity"

mkdir -p "$PLUGIN_DIR"
curl -L "$RELEASE_URL" -o /tmp/jellyfin-security.zip
unzip /tmp/jellyfin-security.zip -d "$PLUGIN_DIR"
chown -R jellyfin:jellyfin "$PLUGIN_DIR"

systemctl restart jellyfin

验证安装：

journalctl -u jellyfin | grep "JellyfinSecurity"
# 应看到: "JellyfinSecurity v2.5.8 loaded"

配置

在 Dashboard → Plugins → JellyfinSecurity → Settings 中配置。

核心认证：可启用/禁用 TOTP、Passkeys、邮件 OTP、恢复码；可配置 OIDC/SSO 提供商（Name、ClientID、ClientSecret、Authority、Scopes、AllowPrivateEndpoints）。

暴力破解防护：BruteForceEnabled、MaxFailedAttempts、LockoutDuration、PermanentBanThreshold。

LAN 绕过：LANBypassEnabled、LANBypassCIDRs、TrustedProxyCIDRs。注意：不要在 TrustedProxyCIDRs 中设置过宽范围（如 10.0.0.0/8），否则 SEC-H3 守卫会拒绝直接客户端的 LAN 绕过；应使用 /32 或紧凑的 /24 子网。

设备配对：TVPairingEnabled、PairingCodeExpiration。

二次验证：StepUpLevel（如 AllConfigChanges）。

使用方式

  • 终端用户 TOTP 注册：User → Profile → Two-Factor Authentication → Enable TOTP → 扫描二维码 → 输入 6 位验证码 → 保存 8 个恢复码。插件在中间件层拦截 /Users/AuthenticateByName。
  • 电视设备配对：TV 应用请求配对码（POST /JellyfinSecurity/PairDevice），返回 pairingCode 与 qrCodeUrl；用户在 Admin Dashboard → Pending Pairs 批准；TV 轮询 GET /JellyfinSecurity/CheckPairingStatus?code=...；批准后使用返回的 token 于 X-Device-Token 头。
  • 受信任浏览器令牌：2FA 登录成功后设置签名 Cookie（JellyfinSecurity-TrustedDevice），后续登录可跳过 2FA（默认 90 天，可配置），令牌绑定 User-Agent + IP 子网。
  • OIDC 登录流程：GET /JellyfinSecurity/OIDC/Authorize?providerId=... → 用户跳转 IdP 登录 → GET /JellyfinSecurity/OIDC/Callback?code=...&state=... → 插件交换令牌、创建/关联 Jellyfin 用户、设置认证 Cookie 并重定向。
  • 按用户 IP 允许列表：在 Admin Dashboard → JellyfinSecurity → Users → Edit User 中配置 AllowedIPs。
  • 程序化 API 访问：Option 1 为 API Key 绕过（APIKeyBypassEnabled，使用 X-Emby-Token 头）；Option 2 为设备令牌（配对一次后使用 X-Device-Token 头）。

代码示例

插件提供 C# 集成示例，包括自定义中间件（ISessionVerifier 检查令牌是否通过 2FA）、审计日志查询（IAuditLogStore）、邮件 OTP 服务配置（EmailOTPConfiguration）、HIBP 密码泄露检查（IHIBPService，k-匿名模型，仅发送 SHA-1 哈希前 5 字符）。

常见工作流

  • 用户被锁定（忘记 TOTP 设备）：管理员在 Dashboard → JellyfinSecurity → Users → Reset 2FA；或用户使用恢复码自助恢复。
  • 不可能旅行告警：ImpossibleTravelEnabled、ImpossibleTravelThreshold（km/h）；检测到后自动阻止登录、发送管理员邮件通知、记录审计日志，需管理员手动解封 IP。
  • 仅 SSO 部署：ShowBuiltIn2FAButton: false、ShowBuiltInPasskeyButton: false，登录页仅显示 SSO 按钮。

故障排查

  • LAN 绕过不生效：检查日志中 SEC-H3 消息；若在反向代理后，确保设置 X-Forwarded-For 头；若直接 LAN 访问，收紧 TrustedProxyCIDRs。
  • 二次验证弹窗不出现：升级到 v2.5.8+。
  • OIDC 重定向 URI 不匹配：检查 Jellyfin BaseUrl 与 IdP 中注册的重定向 URI（https://jellyfin.example.com/JellyfinSecurity/OIDC/Callback），并验证 X-Forwarded-Proto 头。
  • 服务器重启后设备令牌过期：升级到 v2.5.7+（令牌持久化到 verified-tokens.json）。
  • TOTP 验证码被拒绝：检查服务器时间（timedatectl），启用 NTP，或增大 TOTPTimeSkew。
  • 审计日志导致高 CPU：启用日志轮转（AuditLogRotation、AuditLogMaxSize、AuditLogMaxAge），排除高频事件。

安全考量

防护范围：凭据填充、钓鱼、未授权 LAN 访问、密码泄露、会话劫持、权限提升。

不防护范围：Jellyfin 核心服务端漏洞、客户端 XSS、TLS/证书问题、服务器物理访问、插件依赖的供应链攻击。

推荐部署加固：提供 Nginx 反向代理配置（HSTS、X-Frame-Options、X-Content-Type-Options、Referrer-Policy、X-Forwarded-For/Proto/Real-IP）与 Docker Compose 只读文件系统配置。

限制

资料未提供插件的收费、价格、平台兼容性细节、性能指标或效果保证等信息。