Authentication

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

1. Configure your reverse proxy with HTTPS and the X-ULI-Proxy-Auth header (see Reverse Proxy Setup below). This header is required for the app to trust forwarded protocol headers.
2. Set AUTH_ENABLED=true in your .env or docker-compose.yml environment block.
3. Restart the container: docker compose up -d --force-recreate
4. Find your proxy auth token in the container logs: docker logs unifi-log-insight 2>&1 | grep "Proxy auth token"
5. Add the token to your reverse proxy configuration as the X-ULI-Proxy-Auth header value (see examples below).
6. Open the web UI over HTTPS. Go to Settings → Security and create the first admin account (username + password, minimum 8 characters).
7. Authentication is now active. All subsequent visits require login.

Environment Variables

Session Management

Login creates a server-side session stored in the database. A session cookie (uli_session, 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, a client type, and a set of scopes that limit which API operations it can perform. Tokens do not expire — revoke or disable them when no longer needed.
• 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 Setup

Authentication requires HTTPS. Place Insights Plus behind a reverse proxy that terminates TLS. The proxy must send two headers so the app can verify the connection is secure:

• X-Forwarded-Proto — tells the app whether the client connected over HTTP or HTTPS.
• X-ULI-Proxy-Auth — a shared secret that proves the request came through your trusted proxy, not from an attacker spoofing headers.

docker logs unifi-log-insight 2>&1 | grep "Proxy auth token"

Proxy Configuration Examples

Replace YOUR_TOKEN_HERE with the token from your container logs.

location / {
    proxy_pass http://<your-host>:8090;
    proxy_set_header Host              $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For   $remote_addr;
    proxy_set_header X-Real-IP         $remote_addr;
    proxy_set_header X-ULI-Proxy-Auth  "YOUR_TOKEN_HERE";
}

proxy_set_header X-ULI-Proxy-Auth "YOUR_TOKEN_HERE";

your-domain.com {
    reverse_proxy <your-host>:8090 {
        header_up X-ULI-Proxy-Auth "YOUR_TOKEN_HERE"
    }
}

labels:
  - "traefik.http.routers.uli.rule=Host(`insights.example.com`)"
  - "traefik.http.routers.uli.entrypoints=websecure"
  - "traefik.http.routers.uli.tls=true"
  - "traefik.http.middlewares.uli-proxy-auth.headers.customrequestheaders.X-ULI-Proxy-Auth=YOUR_TOKEN_HERE"
  - "traefik.http.routers.uli.middlewares=uli-proxy-auth"
  - "traefik.http.services.uli.loadbalancer.server.port=8090"