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

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 ANIWORLD_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 ~/.aniworld/.flask_secret (file mode 0600).

HTTPS: Behind a TLS reverse proxy, set web_base_url to the https:// URL or export ANIWORLD_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	ANIWORLD_WEB_SSO
SSO only (disable local login)	web_force_sso	ANIWORLD_WEB_FORCE_SSO
Issuer URL	oidc_issuer_url	ANIWORLD_OIDC_ISSUER_URL
Client ID	oidc_client_id	ANIWORLD_OIDC_CLIENT_ID
Client secret	oidc_client_secret	ANIWORLD_OIDC_CLIENT_SECRET
Button display name	oidc_display_name	ANIWORLD_OIDC_DISPLAY_NAME
Admin username	oidc_admin_user	ANIWORLD_OIDC_ADMIN_USER
Admin subject (sub claim)	oidc_admin_subject	ANIWORLD_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.