Bootstrap Settings (.env)
Bootstrap settings are loaded once at startup from the .env file (or OS environment variables if no .env is present). Changing any of these requires restarting the server.
Autentico loads .env from the current working directory.
Generate a .env with secure defaults:
# Production (HTTPS) — secure cookie flags default to true
./autentico init --url https://auth.example.com
# Local development (HTTP) — pass --dev to disable Secure cookie flags
./autentico init --url http://localhost:9999 --dev
caution
Never commit .env to source control. It contains your RSA private key and all cryptographic secrets.
Application
| Variable | Default | Description |
|---|---|---|
AUTENTICO_APP_URL | http://localhost:9999 | Public base URL of the application. Used as the OIDC issuer (iss) and for constructing redirect URIs. Must match the URL clients use to reach the server. |
AUTENTICO_APP_OAUTH_PATH | /oauth2 | URL path prefix for all OAuth2 endpoints. Change this only if you need to namespace the endpoints. |
AUTENTICO_DB_FILE_PATH | ./autentico.db | Path to the SQLite database file. The directory must exist and be writable. Use an absolute path in production. |
AUTENTICO_LISTEN_PORT | (derived from APP_URL) | Override the port the server binds to locally. Useful when a reverse proxy handles TLS and the public AUTENTICO_APP_URL port differs from the local bind port. Defaults to the port in AUTENTICO_APP_URL. |
Cryptographic secrets
All secrets are generated by autentico init. In production, inject them as environment variables from a secrets manager rather than committing them to .env.
| Variable | Description |
|---|---|
AUTENTICO_PRIVATE_KEY | Base64-encoded RSA 2048 private key PEM. Used to sign ID tokens and access tokens (RS256). If unset, an ephemeral key is generated at startup — tokens issued with an ephemeral key are invalidated on restart. |
AUTENTICO_ACCESS_TOKEN_SECRET | HMAC secret for access token signing. Must be a strong random value (at least 32 bytes). |
AUTENTICO_REFRESH_TOKEN_SECRET | HMAC secret for refresh token signing. Must be a strong random value. |
AUTENTICO_CSRF_SECRET_KEY | 32-byte secret for CSRF token generation (gorilla/csrf). Must be stable across restarts — changing it invalidates all in-flight CSRF tokens. |
Cookies
The two _SECURE cookie flags default to true. They should only be set to false for local HTTP development — use autentico init --dev to generate a .env with these flags disabled.
| Variable | Default | Description |
|---|---|---|
AUTENTICO_CSRF_SECURE_COOKIE | true | Adds the Secure flag to the CSRF cookie. Set to false only when running over plain HTTP (local development). |
AUTENTICO_IDP_SESSION_COOKIE_NAME | autentico_idp_session | Cookie name for the IdP SSO session. |
AUTENTICO_IDP_SESSION_SECURE | true | Adds the Secure flag to the IdP session cookie. Set to false only for local HTTP development. |
AUTENTICO_REFRESH_TOKEN_COOKIE_NAME | autentico_refresh_token | Cookie name used when cookie-only delivery is enabled. Change if you run multiple Autentico instances under the same domain. |
AUTENTICO_REFRESH_TOKEN_COOKIE_ONLY | false | Opt-in security enhancement. When true, the refresh token is delivered as an HttpOnly cookie instead of in the JSON response body. This prevents JavaScript (including XSS payloads) from ever reading the refresh token. Non-standard: the OIDC spec expects refresh_token in the response body, so only enable this if your client is purpose-built to read the token from the cookie rather than the JSON response. |
Rate limiting
Per-IP token-bucket rate limiting applied to authentication and sensitive endpoints:
/oauth2/login/oauth2/mfaand/oauth2/mfa//oauth2/passkey/login/beginand/oauth2/passkey/login/finish/oauth2/forgot-password/oauth2/reset-password/oauth2/token(and Keycloak-compatible/oauth2/protocol/openid-connect/token)/account/api/password/account/api/mfa/totp(DELETE)
Two-tier limiting: a request must pass both the per-second and per-minute bucket to proceed.
| Variable | Default | Description |
|---|---|---|
AUTENTICO_RATE_LIMIT_RPS | 5 | Sustained request rate per IP (requests/second). Set to 0 to disable both limiters — useful when your reverse proxy already handles rate limiting. |
AUTENTICO_RATE_LIMIT_BURST | 10 | Burst capacity for the per-second limiter. An IP can send this many requests instantly before the per-second rate applies. |
AUTENTICO_RATE_LIMIT_RPM | 20 | Sustained request rate per IP (requests/minute). Caps long-term enumeration even when requests are spaced to avoid the per-second limit. |
AUTENTICO_RATE_LIMIT_RPM_BURST | 20 | Burst capacity for the per-minute limiter. |
Anti-timing delay
Random delay added to authentication responses (/oauth2/passkey/login/*, /oauth2/forgot-password, /oauth2/resend-verification) to prevent timing-based user enumeration. The server sleeps for a random duration between the min and max values before responding.
Set both to 0 to disable — useful for profiling or when your infrastructure already mitigates timing attacks.
| Variable | Default | Description |
|---|---|---|
AUTENTICO_ANTI_TIMING_MIN_MS | 50 | Minimum delay in milliseconds. |
AUTENTICO_ANTI_TIMING_MAX_MS | 150 | Maximum delay in milliseconds. Must be greater than min, otherwise the delay is disabled. |
Performance tuning
| Variable | Default | Description |
|---|---|---|
GOMAXPROCS | all CPUs | Standard Go environment variable that controls the maximum number of OS threads executing goroutines simultaneously. Not an Autentico setting — it is read by the Go runtime directly. Set to a lower value to reserve CPU for other processes on the same machine. |
AUTENTICO_DB_READ_POOL_SIZE | 0 | Number of SQLite read connections in the pool. Reads run concurrently via WAL mode while writes serialize through a single connection. 0 means auto: whichever is smaller between available CPUs and 4, with a minimum of 2. On a 2-core machine you get 2 readers; on 4+ cores you get 4. Set explicitly to override (e.g. 8 for read-heavy workloads). |
Token signing
| Variable | Default | Description |
|---|---|---|
AUTENTICO_JWK_CERT_KEY_ID | autentico-key-1 | Key ID (kid) embedded in the JWK Set and JWT headers. Relying parties use this to select the correct verification key. Change if you are rotating keys. |
Networking
The AppDomain, AppHost, AppPort, and AppAuthIssuer values are all derived from AUTENTICO_APP_URL — do not set them manually.
| Derived value | Example (from https://auth.example.com) |
|---|---|
| Domain | auth.example.com |
| Host | auth.example.com |
| Port | 443 |
| Auth Issuer | https://auth.example.com/oauth2 |
Example .env
AUTENTICO_APP_URL=https://auth.example.com
AUTENTICO_APP_OAUTH_PATH=/oauth2
AUTENTICO_DB_FILE_PATH=/data/autentico.db
AUTENTICO_PRIVATE_KEY=LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQo...
AUTENTICO_ACCESS_TOKEN_SECRET=change-me-to-a-strong-random-secret
AUTENTICO_REFRESH_TOKEN_SECRET=change-me-to-another-strong-random-secret
AUTENTICO_CSRF_SECRET_KEY=change-me-to-a-32-byte-random-secret
AUTENTICO_CSRF_SECURE_COOKIE=true
AUTENTICO_IDP_SESSION_SECURE=true
AUTENTICO_REFRESH_TOKEN_COOKIE_ONLY=false
# Rate limiting (set RPS=0 to disable both tiers if reverse proxy handles it)
AUTENTICO_RATE_LIMIT_RPS=5
AUTENTICO_RATE_LIMIT_BURST=10
AUTENTICO_RATE_LIMIT_RPM=20
AUTENTICO_RATE_LIMIT_RPM_BURST=20
# Anti-timing delay (set both to 0 to disable for profiling)
AUTENTICO_ANTI_TIMING_MIN_MS=50
AUTENTICO_ANTI_TIMING_MAX_MS=150
# Read pool size (0 = auto)
AUTENTICO_DB_READ_POOL_SIZE=0