Web Authentication ​

eCaptureQ Web can require a username and password to access the analysis interface and APIs for records, source management, status and long polling. Desktop does not enable this authentication layer.

Version and scope ​

Verified on 13 November 2026 against main commit 1bb574d. The latest stable release on that date is still v1.0.0, which does not include this login feature. Use a source build containing authentication or a subsequent release that includes it. Run ecaptureq-web --help and check for --hash-password and --listen; see the matching compilation guide and CLI migration.

• Login is enabled only when a file loaded with --sources contains an auth configuration object. Omitting auth or setting it to null disables authentication. An empty auth: {} is invalid and prevents Web startup.
• This is one configured account for shared access, without multiple users, roles or per-source permissions. Signed-in users can inspect retained records and manage sources.
• Authentication protects browser-to-Web access. It does not authenticate or encrypt the collector's --ecaptureq WebSocket endpoint. Protect that separate connection as described in Data Sources.
• Background receiving continues without signed-in users, after logout and after session expiry. Retention and eviction still apply.

Generate your password hash ​

On the Web service host, run:

ecaptureq-web --hash-password

For a macOS ZIP, use ./ecaptureq-web --hash-password; in Windows PowerShell, use .\ecaptureq-web.exe --hash-password. Enter and confirm a password of 8–1024 bytes; interactive input is hidden. Copy the complete output line into auth.passwordHash below. Do not put the plaintext password in command-line arguments.

The generated hash uses PBKDF2-HMAC-SHA256 with a random salt and 600,000 iterations. The configuration does not accept plaintext passwords. The tool also supports standard input for use with an existing secure input channel.

The newer config/sources.example.json contains the public initial credentials ecapture / ecaptureQ. These apply only when that example configuration is loaded; the program does not enable this account by default. Replace the username and password hash before deployment.

Enable login locally ​

Create sources.local.json. Replace the hash placeholder with the complete generated output. You can instead merge auth into an existing object-format configuration and keep its sources:

{
  "auth": {
    "username": "ecapture",
    "passwordHash": "REPLACE_WITH_GENERATED_HASH",
    "secureCookie": false
  },
  "sources": []
}

This example is for local HTTP testing, so it explicitly uses secureCookie: false. On Linux/macOS, restrict file permissions with chmod 600 sources.local.json; use equivalent file permissions on Windows. The service user needs read access, plus write access if new sources should be saved from the UI.

ecaptureq-web --listen 127.0.0.1:28257 --sources ./sources.local.json

1. Keep the service running and open http://127.0.0.1:28257/ on the same machine. An anonymous visit redirects to the login page.
2. Enter the configured username and the plaintext password used to generate the hash, not the hash itself.
3. After login, the analysis interface opens. This configuration has no sources and initially offers Mock mode. Follow Quick Start to add a source and switch to Live.
4. A Log out button appears at the top right. Logging out returns to the login page; anonymous requests to protected APIs return 401.

Invalid authentication configuration prevents Web startup rather than allowing anonymous access. Restart the Web service after changing authentication settings.

HTTPS and subpath deployments ​

Use an HTTPS reverse proxy for remote deployment and set auth.secureCookie to true, or omit it to use the default. The application's --listen option provides an HTTP listener; the proxy terminates TLS. Keep Secure cookies when the browser uses HTTPS, even if the proxy forwards to the local application over HTTP.

For example, forward the entire /ecaptureq-web/ prefix from your existing HTTPS proxy to this local service:

ecaptureq-web --listen 127.0.0.1:28257 \
  --sources ./sources.local.json \
  --base-path /ecaptureq-web/ \
  --exclude-http-path-prefix /ecaptureq-web/

Open https://your-host/ecaptureq-web/; the login page uses the same prefix. Preserve the prefix and external Host when forwarding pages, assets and APIs. In Nginx, use proxy_pass http://127.0.0.1:28257 without a trailing slash that would strip the prefix. Adapt the official Nginx example to your TLS setup. Long polls can wait 10 seconds, so the proxy read timeout must exceed that wait; the example uses 35 seconds.

Cookies use HttpOnly, SameSite=Strict and a Path matching --base-path. The application does not change the Secure attribute based on X-Forwarded-Proto; check the configuration against the browser's actual access protocol.

Sessions, logout and password changes ​

Sessions expire 12 hours after login. Refreshing and long polling do not extend this lifetime. After expiry, APIs return 401, and the page stops refreshing and redirects to login. Each instance supports up to 128 sessions. Restarting the service invalidates all sessions.

Log out revokes the current session and ends its long polls. Tabs sharing that cookie also lose access; independent sessions in other browsers remain valid. Logout does not clear the service's live cache or stop the collector.

To change or recover a forgotten password, run --hash-password on the service host, replace passwordHash in the configuration and restart Web. Update username at the same time if needed. A restart invalidates all login sessions and also clears in-memory live records and logs; export important records first. There is no self-service password recovery page.

Troubleshooting ​

Sources: configuration reference, authentication middleware, and password/configuration validation.