Authentication
Configure login methods, API access, rate limiting, and password storage.
Comicarr uses JWT-based authentication, API key access, and several security hardening features.
HTTP Authentication
| Setting | Type | Default | Description |
|---|---|---|---|
HTTP_USERNAME | string | — | Login username. |
HTTP_PASSWORD | string | — | Login password. Stored as a bcrypt hash. |
Authentication Mode
| Setting | Type | Default | Description |
|---|---|---|---|
AUTHENTICATION | int | 0 | Authentication method: 0 = basic HTTP auth, 1 = form login, 2 = form-based login. |
Standard HTTP Basic authentication. The browser shows a native username/password dialog. Set AUTHENTICATION to 0.
This mode is simplest but does not support session management or login timeout. Credentials are sent with every request.
A web-based login form served by Comicarr. Set AUTHENTICATION to 1 or 2.
Form login uses JWT-based sessions, supports login timeout, and rate limiting. This is the recommended mode for most deployments.
Session Management
| Setting | Type | Default | Description |
|---|---|---|---|
LOGIN_TIMEOUT | int | 43800 | JWT token expiry in minutes. Default is approximately 30 days (43,800 minutes). |
Sessions are JWT-based. On successful login, Comicarr issues a signed JWT token using the HS256 algorithm (pinned to prevent algorithm confusion attacks). The signing key is stored in SECURE_DIR/jwt.key, separate from the Fernet master key.
The token is set as an HttpOnly, SameSite=Strict cookie named comicarr_session. The token expiry is controlled by the LOGIN_TIMEOUT setting.
CSRF Protection
Comicarr includes CSRF middleware that requires a custom header on all state-changing requests:
| Parameter | Value |
|---|---|
| Required header | X-Requested-With: ComicarrFrontend |
| Affected methods | POST, PUT, DELETE, PATCH |
| Exempt paths | /opds, /api/health |
This header requirement is combined with SameSite=Strict cookies to prevent cross-site request forgery. Browsers will not send the custom header in cross-origin requests, so forged requests from other sites are rejected.
API key authenticated requests (e.g. from external tools like Komga or Mylar) use the X-Api-Key header instead of browser cookies, so CSRF protection does not apply to them.
Security Headers
Comicarr sets the following security headers on all responses via middleware:
| Header | Value |
|---|---|
X-Content-Type-Options | nosniff |
X-Frame-Options | DENY |
Referrer-Policy | strict-origin-when-cross-origin |
Permissions-Policy | camera=(), microphone=(), geolocation=() |
Cross-Origin-Opener-Policy | same-origin |
X-XSS-Protection | 0 |
Content-Security-Policy | Restricts sources for scripts, styles, images, etc. |
Strict-Transport-Security | Added when ENABLE_HTTPS is true |
Setup Gate
On first run, Comicarr blocks all requests except setup-related paths until initial setup is completed. This prevents unauthenticated access to the application before credentials are configured.
Paths allowed during setup:
/and/index.html/auth/setupand/auth/check_setup/assetsand/favicon.ico/api/health
All other requests receive a redirect or error response until setup is finished.
API Access
| Setting | Type | Default | Description |
|---|---|---|---|
API_KEY | string | — | API key for authenticating API requests. Auto-generated on first startup. |
The API is always enabled. An API key is automatically generated when Comicarr first starts. You can regenerate the key at any time from Settings > Web Interface.
Pass the key as the X-Api-Key header:
curl -H "X-Api-Key: YOUR_API_KEY" http://localhost:8090/api/watchlistThe API key is separate from your login credentials. It is auto-generated on first startup and can be regenerated through the UI on the Settings > Web Interface page.
Rate Limiting
Comicarr enforces rate limiting on the login endpoint to protect against brute-force attacks.
| Parameter | Value |
|---|---|
| Maximum attempts | 5 per IP |
| Lockout duration | 300 seconds (5 minutes) |
After 5 failed login attempts from a single IP address, that IP is locked out for 300 seconds. No configuration options exist for these values -- they are hardcoded for security.
Password Storage
Comicarr uses bcrypt with 12 salt rounds for password hashing.
| Setting | Type | Default | Description |
|---|---|---|---|
ENCRYPT_PASSWORDS | bool | True | Enable bcrypt hashing for stored passwords. |
SECURE_DIR | string | — | Directory for security-sensitive files (e.g. jwt.key, master.key). Defaults to <config_dir>/secure. |
Password Lifecycle
Password set via UI
The user enters a plaintext password on the settings page.
Bcrypt hash generated
Comicarr hashes the password using bcrypt with 12 rounds and stores only the hash in config.ini.
Login verification
On login, the submitted password is compared against the stored bcrypt hash. The plaintext password is never stored.
Legacy Migration
Older installations may have passwords stored as base64-encoded strings. Comicarr detects these on startup and automatically migrates them to bcrypt hashes. No user action is required.
Do not manually edit HTTP_PASSWORD in config.ini. The value must be a valid bcrypt hash. Use the web UI to change your password.