Home

🔐 Jellyfin Security — Wiki

Comprehensive authentication and hardening for Jellyfin: TOTP, passkeys, email OTP, OIDC/SSO sign-in, brute-force IP banning, impossible-travel detection, per-user IP allowlist, device pairing, trusted-browser cookies, and a full audit log — all from one plugin.

This wiki is the task-oriented guide. For the full feature list, security posture, changelog, and project info, see the README. Per-version release notes live in Releases.

---

📖 Guides

Page	What's inside
Features	The complete feature list — factors, OIDC, enforcement, account protection, admin tools, i18n
Installation	Catalogue install, build from source, manual install, plugin paths by OS
First-Time Setup	Admin setup, enrolling in 2FA, passkeys, native apps & TVs
OIDC / SSO	Google walkthrough, other providers, role→library access, picture sync, account chooser, step-up
Account Protection	Account lockout, brute-force IP banning, impossible-travel, IP allowlist, empty-password gate
Admin Guide	The 5 dashboard tabs, settings reference, security score, encrypted config export
Email / SMTP	SMTP setup for email OTP (Gmail + generic relay)
Architecture & Security Model	Middleware pipeline, persistent state, threat model, API endpoints, limitations
Troubleshooting	Locked out, SWAG/fail2ban collision, disabling the plugin, common gotchas

---

⚡ How it works

1. Each user opts into 2FA via /TwoFactorAuth/Setup — scans a QR code and saves recovery codes.
2. On login, Jellyfin's SessionStarted event fires; the plugin checks if the user has 2FA enabled.
3. If yes, all API requests from that session are blocked until 2FA is completed via /TwoFactorAuth/Login.
4. After verification a signed __2fa_trust cookie is set — that browser is trusted for 30 days; new browsers/devices still prompt.
5. Enforcement applies to every client (web, mobile, anything that creates a session), not just the browser.

---

🆘 Quick links

• Locked out? → Troubleshooting → Recovery
• Behind a reverse proxy? → First-Time Setup → Reverse proxy and Troubleshooting → SWAG/fail2ban
• Setting up Google sign-in? → OIDC / SSO → Google walkthrough
• Report a security issue → SECURITY.md

---

❤ Support

If this plugin protects your server and you'd like to support development:

• ⭐ Star the repo — free, helps others find it
• 💖 Sponsor on GitHub
• ☕ Buy me a coffee on Ko-fi

Maintained by @ZL154. MIT licensed.