Authentication

Enable authentication, manage sessions and API tokens, and secure your reverse proxy.

Supported Version3.3.0

Overview

Insights Plus supports optional built-in authentication with session cookies and API tokens. When enabled, all UI and API access requires a valid session or bearer token. Authentication is disabled by default for easy initial setup.

When enabled, authentication requires HTTPS — the login and setup endpoints reject requests over plain HTTP to protect credentials in transit.

Quick Start

Configure HTTPS on your reverse proxy (see Reverse Proxy Security below). Authentication requires HTTPS to be working before proceeding.
Set AUTH_ENABLED=true in your .env or docker-compose.yml environment block.
Restart the container for the change to take effect: docker compose up -d --force-recreate
Open the web UI over HTTPS. Go to Settings → Security and create the first admin account (username + password, minimum 8 characters).
Authentication is now active. All subsequent visits require login.

Environment Variables

Variable	Description
`AUTH_ENABLED`	Set to true to enable built-in authentication. Requires HTTPS. Default: false
`SESSION_TTL_HOURS`	How long login sessions remain valid before requiring re-login. Default: 168 (7 days). Configurable in Settings → Security

Session Management

Login creates a server-side session stored in the database. A session cookie (session_id, HttpOnly, Secure, SameSite=Lax) is set in the browser.

Session duration is configurable in Settings → Security → Session Duration (1 hour to 30 days). Changes apply to new sessions only.
Expired sessions are automatically cleaned up by the daily maintenance task.
Logging out invalidates the session immediately on the server.

API Tokens

API tokens provide programmatic access for integrations like the MCP AI Agent or the browser extension. Tokens are created in Settings → API.

Tokens are shown only once at creation. Copy and store securely.
Each token has a name, optional expiry, and a set of scopes that limit which API operations it can perform.
Effective scopes = intersection of token scopes and owner's role permissions. A token can never exceed its owner's access level.
To rotate a token, delete the old one and create a new one with the same scopes.

Audit Logging

When enabled, all MCP API calls are logged to an audit trail visible in Settings → MCP → Audit Log. Each entry records the token used, tool called, parameters (sensitive values redacted), success/failure, and timestamp.

Audit retention defaults to 10 days and is configurable via mcp_audit_retention_days in Settings.

Reverse Proxy Security

Authentication requires HTTPS. In production, place Insights Plus behind a reverse proxy that terminates TLS and sets the X-Forwarded-Proto header so the application knows the effective protocol.

Security Warning

Your reverse proxy must overwrite (not forward) any client-supplied X-Forwarded-Proto header. If the proxy forwards the header as-is, an attacker can inject X-Forwarded-Proto: https on a plain HTTP request, causing Insights Plus to treat the connection as secure. This can lead to:

Session cookies and credentials sent over unencrypted HTTP, enabling interception and man-in-the-middle attacks.
Bypass of HTTPS enforcement, allowing authentication endpoints to accept requests they should reject.
Defeat of HSTS and secure-cookie protections that depend on accurate protocol detection.

Proxy Configuration Examples

nginx

location / {
    proxy_pass http://localhost:8090;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header Host              $host;
}

$scheme is set by nginx itself, so client-supplied values are always overwritten.

Caddy

your-domain.com {
    reverse_proxy localhost:8090
}

Caddy sets X-Forwarded-Proto automatically and overwrites client values. No extra configuration needed.

Traefik

labels:
  - "traefik.http.routers.uli.entrypoints=websecure"
  - "traefik.http.routers.uli.tls=true"
  - "traefik.http.services.uli.loadbalancer.server.port=8090"

Traefik sets X-Forwarded-Proto automatically when TLS is terminated at the entrypoint. Ensure forwardedHeaders.insecure is not enabled unless you trust all upstream sources.

Environment Variables MaxMind GeoIP