Authentication Configuration
Harper's authentication system is configured via the top-level authentication section of harperdb-config.yaml.
authentication:
authorizeLocal: true
cacheTTL: 30000
enableSessions: true
operationTokenTimeout: 1d
refreshTokenTimeout: 30d
hashFunction: sha256
Options
authorizeLocal
Type: boolean — Default: true
Automatically authorizes requests from the loopback IP address (127.0.0.1) as the superuser, without requiring credentials. Disable this for any Harper server that may be accessed by untrusted users from the same instance — for example, when using a local proxy or for general server hardening.
cacheTTL
Type: number — Default: 30000
How long (in milliseconds) an authentication result — a particular Authorization header or token — can be cached. Increasing this improves performance at the cost of slower revocation.
enableSessions
Type: boolean — Default: true
Added in: v4.2.0
Enables cookie-based sessions to maintain an authenticated session across requests. This is the preferred authentication mechanism for web browsers: cookies hold the token securely without exposing it to JavaScript, reducing XSS vulnerability risk.
operationTokenTimeout
Type: string — Default: 1d
How long a JWT operation token remains valid before expiring. Accepts jsonwebtoken-compatible duration strings (e.g., 1d, 12h, 60m). See JWT Authentication.
refreshTokenTimeout
Type: string — Default: 30d
How long a JWT refresh token remains valid before expiring. Accepts jsonwebtoken-compatible duration strings. See JWT Authentication.
hashFunction
Type: string — Default: sha256
Added in: v4.5.0
Password hashing algorithm used when storing user passwords. Replaced the previous MD5 hashing. Options:
sha256— Default. Good security and excellent performance.argon2id— Highest security. More CPU-intensive; recommended for environments that do not require frequent password verifications.