First Time Setup

First-Time Setup

This page covers the admin's initial configuration, a user enrolling in 2FA, passkeys, and getting native apps / TVs signed in.

---

As an admin

1. Install the plugin (see Installation) and restart Jellyfin.
2. Go to Dashboard → Plugins → Jellyfin Security.
3. Open the Settings tab and verify:
   • ✅ Enabled — master switch.
   • ✅ Require for all users — off by default. When on, every user with a password must enroll (existing trusted sessions keep working). When off, 2FA is opt-in per user.
   • ✅ LAN Bypass — skip 2FA when the request comes from a LAN IP (192.168/16, 10/8, 172.16/12 by default). Convenient, fewer prompts on local devices.
   • Email OTP — optional fallback if a user loses their authenticator. Requires SMTP (see Email / SMTP).
4. (Optional) Configure Notifications (Gotify, ntfy, or webhook) to get alerts when someone triggers a 2FA prompt.

Behind a reverse proxy

If Jellyfin sits behind Cloudflare, nginx, Caddy, or Traefik:

• Enable Trust X-Forwarded-For.
• Add your proxy IPs (or Cloudflare's IP ranges) to Trusted Proxy CIDRs.

Without this, rate limiting collapses to a single bucket because every request appears to come from the proxy's loopback address.

⚠ Don't paste broad RFC1918 ranges (e.g. 10.0.0.0/8) into Trusted Proxy CIDRs. The SEC-H3 LAN-bypass guard can't tell a "stale-XFF proxy" from a "direct LAN client in a broad range", and LAN bypass will silently refuse for every LAN client. List your proxy's actual address(es). See Troubleshooting if LAN bypass stops working.

---

As a user — enroll in 2FA

1. Sign in to Jellyfin normally (no 2FA yet).
2. Open Profile → Two-Factor Authentication (or visit https://your-jellyfin/TwoFactorAuth/Setup).
3. Click Set up Authenticator App.
4. Scan the QR code with your authenticator (Google Authenticator, Authy, 1Password, Bitwarden, etc.).
5. Enter the 6-digit code to confirm.
6. Generate recovery codes — you get 10 single-use codes. Save them in your password manager; each can sign you in if you lose your phone.
7. (Optional) Add your email under Email OTP as a backup factor.

Signing in with 2FA on the web

1. Sign in at /web with username + password as usual.
2. You're redirected to the 2FA challenge page.
3. Enter the 6-digit code from your authenticator.
4. Done — this browser is trusted for 30 days (cookie bound to your device).

---

Passkeys — Face ID / fingerprint / YubiKey

Passkeys replace the 6-digit code with a biometric or hardware tap. They're phishing-resistant (the credential is bound to your exact domain) and require no typing.

Server config first. Passkeys require HTTPS and a matching WebAuthn Relying Party ID + origin. In Settings → WebAuthn / passkeys:

• Relying Party ID — your public hostname only: jellyfin.example.com (no https://, no port, no path).
• Allowed origins — one per line, full origin incl. scheme/port: https://jellyfin.example.com (add every URL users actually hit).

Skip this and browsers refuse to register/use passkeys (Safari is strictest).

Desktop: Setup → Passkeys card → (optional label) → Add a passkey → confirm with Windows Hello / Touch ID / YubiKey.

iPhone (Safari): open your Jellyfin HTTPS URL (the configured origin, not a bare LAN IP) → sign in → Setup → Passkeys → label it → Add a passkey → confirm with Face ID/Touch ID. Saved to iCloud Keychain, syncs across your Apple devices.

Android (Chrome): open your Jellyfin HTTPS URL → sign in → Setup → Passkeys → label it → Add a passkey → confirm with fingerprint/face. Saved to Google Password Manager.

Android gotchas:

• "Add a passkey" does nothing → your phone needs a screen lock (PIN/pattern/biometric).
• "No passkey provider available" → enable Google Password Manager (or set Bitwarden/1Password as default credential provider).
• Samsung Internet sometimes hides the button — use Chrome.

Using a passkey: username + password → at the 2FA page tap 🔑 Use a passkey instead → confirm. No code typed.

Passkeys are browser-only (WebAuthn). Native apps can't use them — use device pairing below. Passkeys replace the 2FA code step, not your password.

---

Native apps / TVs (Swiftfin, Findroid, Jellyfin for Tizen, Android TV…)

Native apps don't know the 2FA flow, so the plugin uses device pairing:

1. Open the native app and sign in with username + password.
2. The app shows "Invalid" or fails to load — that's expected; the server recorded a pending pairing.
3. On an already-trusted device (laptop, phone browser) go to Setup → Devices Waiting for Approval.
4. Find the TV/app → click Trust.
5. Retry sign-in on the TV/app — it works and is remembered permanently.

Apps that can't do the pairing flow (scripts, older tools)

Use app passwords: Setup → App Passwords → Generate. You get a one-time-shown random password; use it in place of your Jellyfin password. Matched via PBKDF2 hash, bypasses the 2FA prompt, individually revocable.

Sonarr / Radarr / Overseerr / Jellyseerr

Use Jellyfin's standard API keys (Dashboard → API Keys). API-key auth bypasses user authentication, so 2FA doesn't apply.