Security Model

Security Model

This plugin is the login path for your Jellyfin server, so it is built to fail closed: anything the plugin cannot positively verify is rejected, never waved through. This page describes the protections implemented today; it grows as the hardening program continues.

This page covers the login path — the invariants that keep a sign-in fail-closed. Its complement is the Threat Model page, which models the AI-assisted delivery pipeline that produces the plugin (a STRIDE model of the agent, its configuration, and the CI/release pipeline). Together they cover both what the plugin does and how it is built.

Identity binding (anti account-takeover)

An SSO login is bound to the identity provider's stable identifier — OpenID sub / SAML NameID — recorded as a canonical link. A first login whose name merely matches a pre-existing, unlinked Jellyfin account is refused (HTTP 403), not silently adopted, unless an administrator explicitly enables AllowExistingAccountLink for that provider. This prevents a user whose provider-supplied name equals an existing account (e.g. admin) from taking that account over.

An administrator can revoke a user's SSO access with POST /sso/Unregister/<username> (elevated privileges required; the request body names the authentication provider the account switches back to). The user's canonical links are removed across every configured provider and the change is persisted, so an SSO login no longer resolves to the account. Under the fail-closed default the revocation is durable; if a provider has AllowExistingAccountLink enabled, a same-named login can re-adopt the account, so a hard revoke there also needs the local account disabled or renamed.

Disabling a provider takes effect immediately for every grant: a disabled provider is treated exactly like an absent one on the login resolve, the link write, the legacy-link migration, and manual link creation — including when it is disabled mid-request, between the endpoint's own check and the write. Link removal still works on a disabled provider, so disable-then-clean-up is never blocked. A request already past its last configuration transaction may still complete once; the configuration lock is deliberately not held through session minting.

Account links are bound to their issuer (repointing protection)

Each OpenID canonical link records the id_token iss it was minted under, so a link is the full (iss, sub) pair, not a bare sub. This matters when a provider entry is repointed at a different identity provider: because a sub is only unique within an issuer, a new IdP that mints a short numeric subject like 1 could otherwise collide with an accumulated link and silently sign the new user in to the old user's account. Two guards close that:

• Login-time issuer check. Every login compares the resolved link's stored issuer to the login's issuer; a mismatch refuses the login (fail closed) — this catches a swapped IdP even behind an unchanged discovery URL (a DNS/backend repoint). Re-establish the link with the admin linking endpoint, or clear the stale links, to recover.
• Clear-on-endpoint-change. Changing a provider's endpoint URL drops that provider's accumulated links and issuer bindings — the same way the stored client secret is dropped on an endpoint change. An edit is treated as re-identifying the provider, so users re-link on their next login (or via the admin endpoint); plan a short re-link window if you change an endpoint on purpose, and leave the endpoint string untouched for a purely cosmetic edit.

Links created before this feature carry no stored issuer; they keep working unchanged and are stamped with the current issuer on the next successful login (trust-on-first-use), so upgrading does not lock anyone out on its own. Full detail, including the one accepted residual for a provider repointed before this feature shipped, is in Provider Setup.

Legacy username-keyed links honor the same opt-in (upgrade note)

Very early OpenID links were keyed on the username, not the sub. Because a username is something the identity provider can reassign, following such a link is name-based account matching, and it is gated behind the same AllowExistingAccountLink opt-in as adopting a same-named account. With the flag off (the default), a legacy link is not followed: a login whose name still matches its account is refused (403), and one whose name was freed by a rename gets a fresh account rather than the old one — so an attacker who obtains a victim's old username cannot be handed the victim's account.

The trade is an upgrade impact: an install that predates the stable-sub keying has all its OpenID links username-keyed and AllowExistingAccountLink defaulting off, so OpenID logins are refused until an administrator migrates them. Before affected users log in again, either enable AllowExistingAccountLink for the provider as a short, supervised maintenance window (be aware that while it is on, that provider trusts the IdP-supplied name, so whoever logs in first with a given name claims that account — keep the window short and turn it back off), or link accounts individually with the admin endpoint, which needs no name trust. Keep at least one non-SSO administrator with a password login before upgrading; if every admin is SSO-provisioned they can be locked out, and the only recovery is to stop Jellyfin and set <AllowExistingAccountLink>true</AllowExistingAccountLink> in the provider block of config.xml by hand, then restart, migrate, and revert.

An administrator account is never self-migrated this way, flag on or off: a returning admin who held a pre-upgrade username-keyed link is refused on their first post-upgrade login even with AllowExistingAccountLink on — the admin-takeover ceiling above (no name-based adoption of an admin account) applies to legacy links too — so re-link it explicitly with the admin endpoint from a break-glass, non-SSO admin instead of expecting self-migration. A user whose Jellyfin account was renamed and who logs in before the flag is enabled lands on a fresh empty account and is not recoverable by the flag afterward — an admin must delete the new link and re-link the original sub. The full step-by-step is in the Provider Setup.

SAML response validation (fail-closed)

A SAML response is accepted only when all of the following hold; any failure rejects the login:

• Signature — exactly one signature, whose reference covers the element that is actually consumed (root Response or the single Assertion). This blocks XML-signature-wrapping ("verify one node, read another").
• XML parsing — the response is parsed with DTD processing prohibited, so any <!DOCTYPE> is rejected before any other check runs. This closes both external-entity injection (XXE) and internal-entity expansion ("billion laughs") in the untrusted response.
• Time bounds — NotOnOrAfter (and NotBefore when present) are enforced with a bounded clock skew. A missing or unparseable bound is rejected (it is not treated as "valid forever").
• Audience — the assertion's AudienceRestriction must name this service provider (configurable; opt-out available for providers that cannot emit it). This stops an assertion minted for a different service from being replayed here.
• One-time use — a consumed assertion ID cannot mint a second session within its validity window (per-provider replay cache). The cache is enforced on the login callback and on the account-linking callback, so a captured assertion cannot be replayed to bind its identity to another account either.
• Bounded input — a response larger than 256 KB of Base64 is rejected before any decoding or XML parsing. Real responses are single-digit kilobytes; the cap stops a multi-megabyte body from costing memory and CPU on the unauthenticated callback before a single signature check has run.

Two further per-provider checks are opt-in (both off by default, set through the SAML provider configuration):

• ValidateRecipient — the assertion's bearer SubjectConfirmationData/@Recipient (and the Response Destination when present) must equal this server's assertion-consumer URL, so an assertion minted for a different endpoint — or a different service provider sharing the same identity provider — cannot be presented here. The expected URL is only as trustworthy as host resolution, so pin it with BaseUrlOverride.
• ValidateInResponseTo — only solicited responses are accepted: the assertion's InResponseTo must match an AuthnRequest this server issued and has not yet consumed (one-time, time-bounded). Enabling it refuses IdP-initiated (unsolicited) SSO, which completes the browser-binding defense below for providers that can issue unsolicited responses.

Operational details and caveats for both are in the Provider Setup.

Server-side request forgery (outbound fetches)

Every server-to-provider fetch is constrained to public http(s) targets by one shared hardened transport: the resolved address is validated at connect time (each redirect hop too), blocking loopback/private/link-local/CGNAT/metadata ranges and DNS rebinding. This covers both the avatar fetch and the OpenID backchannel — discovery, JWKS, the token exchange, and userinfo — so a provider endpoint (or a discovery redirect) that resolves to a private/loopback address cannot be reached from the login path either. The guard lives once in the plugin's outbound-HTTP home and is registered as the named outbound client the OpenID fetches resolve, so the two paths cannot drift apart.

The avatar fetch adds two more bounds: the download is capped in time and size, and the response must declare a raster image content type (PNG, JPEG, GIF, WebP) — vector types, notably SVG, are refused, because a stored SVG can carry script and become a stored-XSS vector if later served executably. The avatar is best-effort: a refused avatar is logged and skipped, the login itself proceeds.

OpenID authorize state

The in-flight authorize-state store is safe under concurrent logins, so parallel sign-ins cannot corrupt it or throw. A state is also provider-bound and single-use: it is minted for one provider and rejected outright if presented to a different provider's callback (stops a state validated at a low-trust provider from being replayed against a higher-trust one), and it lives for about 15 minutes — long enough for a provider-side MFA or consent step, short enough to bound the replay window.

The store is also bounded. Past a fixed ceiling a new challenge is refused (that sign-in fails cleanly and can be retried) rather than evicting a state belonging to a login already in flight — so a flood of anonymous challenge requests cannot grow memory without bound, and cannot knock out users who are mid-login either. The expired-state sweep and the capacity warning are throttled, so the same flood cannot amplify into CPU load or log volume. Each client is additionally held to a small share of that budget — see In-flight login capacity.

Login browser binding (forced-login defense)

Every login is bound to the browser that started it. When the challenge begins, the plugin sets a short-lived Secure, HttpOnly, SameSite=Lax, __Host--prefixed cookie carrying a fresh random id — __Host-sso_oid_state_binding for OpenID, __Host-sso_saml_state_binding for SAML; two separate cookies, so the flows cannot satisfy each other's check — and records the same id on the in-flight state. The session-minting callback proceeds only when the returning browser presents the matching cookie; a missing or mismatched cookie is refused (fail closed). This ties the login to the initiating user-agent as the OAuth 2.0 Security BCP requires, closing the forced-login / session-fixation vector where an attacker starts a flow of their own and lures a victim into completing it, silently signing the victim in as the attacker. The __Host- prefix makes the browser enforce Secure/host-only/Path=/, so a sibling subdomain cannot plant a same-named cookie to poison the check (cookie tossing).

It is automatic, with no configuration. Consequences worth knowing:

• HTTPS is required at the browser edge. The Secure cookie is only stored and returned over HTTPS (a TLS-terminating reverse proxy is fine — the browser sees HTTPS). Over plain http:// the cookie never comes back and every bound login is refused.
• Complete the login in the same browser that started it, and serve the whole flow from one origin — a callback opened in a different browser, or after clearing cookies mid-flow, is refused; just start the login again.
• SAML scope. The SAML binding covers solicited (SP-initiated) logins; an IdP-initiated response answers no request this server issued, so binding cannot cover it — enable ValidateInResponseTo (above) to refuse unsolicited responses and close the vector completely. A solicited response whose recorded request is gone — expired (~15 minutes), or the challenge and the response landed on different instances behind a load balancer without session affinity — is refused rather than accepted unbound, because a lost correlation must fail closed. Run a single Jellyfin instance or sticky sessions for SP-initiated SAML.

In-flight login capacity (per-client)

Each started login holds one short-lived in-flight entry (an OpenID authorize state or a SAML outstanding-request record) until it is completed or expires (~15 minutes). Both stores are globally capped — refuse-at-cap, never evict — and, so a single anonymous source cannot fill that global budget and lock out everyone's logins, each client is additionally held to a 1% share of it (up to 1,000 concurrent in-flight logins per client). This is automatic and always on; a real user starting a handful of logins never approaches it.

The share is keyed on the client IP the plugin sees, so behind a reverse proxy set Jellyfin's Known proxies — otherwise every request is attributed to the proxy's address. Private/loopback sources are exempt from the per-client share (they are un-attributable — typically the whole userbase behind one hop) but remain bounded by the global cap. Operator guidance is in the Provider Setup.

OpenID id_token validation

The id_token returned by the provider is validated before any identity is read from it; any failure rejects the login:

• Signature — verified against the provider's published JWKS (from its discovery document). Only asymmetric algorithms are accepted (RS256/384/512, PS256/384/512, ES256/384/512); a token signed with a symmetric algorithm (HS256) or left unsigned (alg: none) is rejected regardless of configuration. A rotated signing key is picked up automatically. A JWKS key below the minimum strength floor — RSA under 2048 bits, or an EC key off the approved NIST P-256/384/521 curves — is skipped like a malformed key, so a token signed by an under-strength key has no key to resolve against and fails closed. The same floor gates the SAML signing certificate, so the two paths cannot drift.
• Issuer — must match the discovery issuer. The per-provider DoNotValidateIssuerName escape hatch relaxes only this check; signature, audience and expiry validation have no off switch.
• Audience — must include this client. When an azp claim is present it must equal the client id, and a multi-audience token without azp is rejected — it may have been minted for a different party that merely lists this client as a co-audience.
• Lifetime — exp (and nbf when present) are enforced with a bounded clock skew.
• When the provider sends an at_hash claim, it must match the issued access token.

What your provider must be configured to satisfy is described in the id_token requirements.

OpenID authorization-response issuer (RFC 9207)

When the provider adds an iss parameter to the authorization response (a mix-up defense, RFC 9207), it must match the issuer of the validated id_token the code was redeemed for; a mismatch means the response came from a different authorization server than the one the token belongs to, and the login is rejected. Providers that do not send iss are unaffected. The per-provider DoNotValidateResponseIssuer escape hatch relaxes only this check.

PKCE downgrade detection

The plugin always sends a PKCE code_challenge (S256) with the authorization request. PKCE only protects against authorization-code injection when the server actually enforces it, so on login the provider's discovery document is checked for S256 in code_challenge_methods_supported (RFC 9700 §2.1.1); the result is cached for about 15 minutes. By default a provider that does not advertise it logs an [SSO Audit] warning and the login proceeds — PKCE is still sent, but the server may be ignoring it. Setting Require PKCE (S256) (RequirePkce) on a provider fails closed instead: the login is refused when S256 is not advertised, or when the discovery document cannot be read to confirm it.

Response hardening

The rendered auth page (the one that carries the one-time state token or signed assertion and completes the login client-side) sets X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Referrer-Policy: no-referrer, and Cache-Control: no-store — clickjacking protection, no MIME sniffing, no token leakage via the Referer header, and no caching of a token-bearing response.

The page also carries a strict Content-Security-Policy: default-src 'none', with only the page's own inline script and style authorized via a per-response nonce. Network access is limited to the page's own origin (connect-src 'self' for the session-mint call, frame-src 'self' for the bootstrap iframe, images same-origin or data:), and base-uri, form-action, and frame-ancestors are all denied. Markup injected into the page therefore cannot execute script, re-base its URLs, or send the token anywhere but back to this server.

Rate limiting (optional)

The anonymous SSO endpoints (challenge, callback, and token exchange, for both OpenID and SAML) can be rate-limited per client address to blunt brute-force and flood attempts. It is opt-in and off by default, configured in the plugin's XML configuration:

Setting	Default	Meaning
EnableRateLimit	false	Master switch.
RateLimitMaxAttempts	30	Requests allowed per window, per endpoint stage.
RateLimitWindowSeconds	60	Window length.

A throttled request gets 429 Too Many Requests with a Retry-After header. One login spends one request per stage (challenge → callback → token exchange), so the default is generous for real users while still catching sustained abuse.

Behind a reverse proxy, configure Jellyfin's own Known proxies networking setting. The limiter keys on the connection's remote address only and deliberately never parses X-Forwarded-For itself — a client-spoofable header must not be able to steer or evade throttling. With Known proxies set, Jellyfin resolves the real client into that address. Without it, every request appears to come from the proxy: if the proxy address is non-public (loopback/private — the common local-proxy case) no bucket is created and the userbase is never pooled, but a proxy on a public address would share one bucket across all clients, which is why Known proxies matters.

Non-public source addresses are never throttled; IPv6 clients are grouped by their /64. IPv4-in-IPv6 transition addresses (the NAT64 well-known prefix, 6to4, IPv4-compatible) are keyed on their embedded IPv4 instead of the shared transition prefix, so distinct clients translated through one NAT64 prefix each get their own bucket — one abuser behind the prefix cannot throttle everyone else behind it.

When throttling engages, the server log carries a bounded notice: a single warning line with the count of requests refused since the last notice, at most once per minute and never including a client address. That makes a sustained brute-force attempt — or a reverse proxy misconfigured so that every client pools into one bucket — visible in the log without the notice itself amplifying the flood into log volume.

The limiter is best-effort and in-process — counters are per Jellyfin instance and reset on restart — so it blunts sustained brute force at the public edge rather than enforcing a hard quota.

Secret handling

The OpenID client secret is write-only across the API: it is persisted in the server-side configuration but withheld from every configuration response, so it never reaches the admin browser (or a HAR capture, proxy log, or shared screen) after the first save. On the settings page the secret field starts blank — leave it blank to keep the stored value, or enter a new secret to replace it. The SAML certificate is the identity provider's public signing certificate (used to verify its assertions), not a secret, so it stays readable.

Secrets encrypted at rest

The OpenID client secret (OidSecret) and the SAML request-signing key (SamlSigningKeyPfx) are stored in the configuration XML as an AES-256-GCM ssoenc:v1: envelope, not plaintext, so a leaked config file alone does not reveal them. The data-encryption key lives in a separate sso-secret.key file in the plugin data folder (owner-only permissions on Linux); it is created on first save, not at startup, and must be backed up alongside the config — without it, every encrypted secret is permanently unrecoverable, and the plugin fails closed (refuses a signed SAML login or an OpenID token exchange) rather than falling back to an empty or wrong secret. An existing plaintext config keeps working unchanged and is rewritten as an envelope the next time it is saved; no manual migration step is needed.

This is a breaking change on downgrade. A plugin version without this change cannot read ssoenc: values, so rolling back after a secret has been encrypted leaves the affected provider looking like its secret is unset. Re-enter the secret/key on the older version, or restore a pre-upgrade plaintext config backup, before downgrading. The full rollback procedure is in Provider Setup.

SSO-only login (opt-in)

The optional SSO-only mode (DisablePasswordLogin) routes every account off Jellyfin's built-in password provider so users can only sign in through SSO — except one designated break-glass administrator, whose password login is preserved on every path as the IdP-independent recovery door. The security properties:

• Fail-closed last-admin guard. Activation is refused — with a single, non-enumerating message, and without changing anything — unless the break-glass account is an existing, enabled administrator that still has a usable password login. An SSO-linked admin does not qualify: its usability depends on the IdP being up, which is exactly what fails in the lockout scenario. If the enforcement sweep itself cannot run, the mode is rolled back rather than left recorded-on but unenforced.
• The break-glass door survives every path. The recovery admin is never swept or repointed (even when a provider's DefaultProvider targets SSO), and while the mode is on no SSO login or role mapping can demote it from administrator or disable it. Role mappings can never grant IsDisabled to any account.
• Un-forgeable state. DisablePasswordLogin, BreakGlassAdminUsername, and the tracked restore list are server-managed: a settings-page save, config PUT, or config import cannot flip the mode or move the designation — only the dedicated elevation-gated SSO-Only/Enable|Disable|BreakGlassAdmin endpoints (and the documented on-disk recovery edit) change them.
• Reversible without SSO. Disabling — via the endpoint, or by editing the config XML and restarting (a boot reconciliation restores the swept accounts) — restores password routing only, for exactly the accounts the mode moved. No password hash is ever reset or revealed, and natively-SSO plugin-created accounts are never handed a password door.

The operator runbook is in Provider Setup; the threat model is recorded in SSO-Only Login Design.

Audit trail

Security-relevant events — successful logins, opt-in adoption of an existing unlinked account, admin provider add/remove, and SSO-only mode transitions (enables, disables, and refused activations, by reason code) — are written as structured [SSO Audit] log entries (username, provider, admin flag; never a secret or config value).

Reporting

Report vulnerabilities privately via Report a vulnerability. Security-relevant behavior is covered by the automated test suite, and login-path changes go through an adversarial security review before merge.