Authentication

Authentication

🌐 English · Deutsch

Authentication is enabled by default. On first start the admin account is created via a setup token (Getting Started).

Users & roles

Role	Permissions
admin	Everything — incl. settings, encoding, user management, library management (delete/rename/move), custom paths, AutoSync management
user	Search, downloads, own favourites, own notifications, view/play the library
kids	Like user, but age-limited and read-only: no downloads, no Auto-Sync, no module store, no module settings

The kids role is a restriction, not a rank below user. An account that has it sees an age-limited app and cannot change that — there is no PIN, because there is nothing to leave. The limit is the one set under Settings → Start Page → Kids mode → Age limit (default 6) and is applied by the server at every point, not by the browser:

Where	What happens
Home feed	Titles rated above the limit are dropped while the rows are built; the 18+ source is never fetched
Search	The adult source answers 403; results are filtered against the cached TMDB rating
Advanced search	TMDB is queried with certification.lte, so the paging is already limited
Library	The shelf is filtered against the cached TMDB rating
Playback	/api/stream/start refuses the file itself — a copied or guessed path does not play either
Downloads	/api/download and Auto-Sync answer 403
Module store, module settings	Redirect / 403

Be clear about what this can and cannot do. Filtering can only judge a title TMDB has a certification for, and unrated titles are shown on purpose — dropping everything unrated would empty the app on an instance without a TMDB key, and an empty app is one people switch the protection off for. The parts that do not depend on metadata at all — the refusals in the table above — are what actually holds.

Don't confuse it with the kids mode on the home page: that is for a shared account with a child in front of it right now, it is entered by anyone and left with a PIN. The role is for a child with their own login.

User management (create, delete, change role) is done by admins on the settings page. Rules: username max. 64 characters (a–z, 0–9, ., _, -), password min. 8 characters. You cannot delete your own account. Role changes apply without re-login (the session role is refreshed from the DB every 15 s).

Sessions & protections

• Sessions are valid for 24 h (HTTPOnly, SameSite=Lax; Secure flag with HTTPS).
• Login rate limit: max. 10 login attempts per minute (optional Redis backend via MEDIAFORGE_REDIS_URL).
• CSRF protection for forms; JSON API routes require Content-Type: application/json.
• Security headers (CSP, X-Frame-Options DENY, nosniff, Referrer-Policy; HSTS with HTTPS).
• Session fixation protection: the session is recreated on every login.
• The Flask secret key lives in ~/.mediaforge/.flask_secret (file mode 0600).

HTTPS: Behind a TLS reverse proxy, set web_base_url to the https:// URL or export MEDIAFORGE_HTTPS=1 — otherwise session cookies are not marked "Secure" (the app logs a warning).

SSO / OIDC

Single sign-on with any OpenID Connect provider (Keycloak, Authentik, Authelia, …). Configure under Settings → SSO or via environment variables:

Setting	DB key	Env variable
Enable SSO	web_sso	MEDIAFORGE_WEB_SSO
SSO only (disable local login)	web_force_sso	MEDIAFORGE_WEB_FORCE_SSO
Issuer URL	oidc_issuer_url	MEDIAFORGE_OIDC_ISSUER_URL
Client ID	oidc_client_id	MEDIAFORGE_OIDC_CLIENT_ID
Client secret	oidc_client_secret	MEDIAFORGE_OIDC_CLIENT_SECRET
Button display name	oidc_display_name	MEDIAFORGE_OIDC_DISPLAY_NAME
Admin username	oidc_admin_user	MEDIAFORGE_OIDC_ADMIN_USER
Admin subject (sub claim)	oidc_admin_subject	MEDIAFORGE_OIDC_ADMIN_SUBJECT

Notes:

• The discovery URL is derived automatically from the issuer URL (<issuer>/.well-known/openid-configuration); scopes: openid email profile.
• Register <base URL>/oidc/callback as the redirect URI at your provider.
• SSO users are created automatically on first login. If the username or sub claim matches oidc_admin_user/oidc_admin_subject, the user is granted admin rights.
• Changes to the SSO configuration require a restart.
• With Force SSO the local login form is disabled entirely.

External API authentication

The /api/v1/... endpoints don't use session login but an API key in the X-Api-Key header. The key is generated automatically on first start and can be viewed and regenerated in the settings (API Reference).

Running without authentication

Internally a no-auth mode exists (virtual admin), but the standard launch always enables authentication. Never expose an instance without auth to untrusted networks.