Environment Configuration Guide #

Back to docs index | Back to project README

This document describes the environment variables MBKAuth expects and keeps brief usage notes for each parameter. Validation and defaults are implemented in lib/config/index.js (it parses mbkautheVar, applies optional mbkauthShared fallbacks, normalizes values, and throws on validation failures).

How configuration is provided #

All configuration variables can be supplied through any of three sources:

1. VarName (Simple environment variable, e.g. process.env.APP_NAME or process.env.app_name) — Top Priority (overrides both mbkautheVar and mbkauthShared).
2. mbkautheVar.VarName — App-specific variables supplied either as keys in the process.env.mbkautheVar JSON string, or as flat prefixed environment variables (e.g. process.env["mbkautheVar.APP_NAME"]) — Overrides mbkauthShared.
3. mbkauthShared.VarName — Shared defaults across multiple services supplied either as keys in the process.env.mbkauthShared JSON string, or as flat prefixed environment variables (e.g. process.env["mbkauthShared.APP_NAME"]).

Lowercase Normalization & Case-Insensitivity #

All configuration variables are normalized in lowercase internally, and are accepted case-insensitively across all sources:

• APP_NAME, app_name, AppName, and appName are all recognized and map to the same setting.
• In code, the resulting mbkautheVar object exposes both lowercase (mbkautheVar.app_name) and uppercase (mbkautheVar.APP_NAME) properties, and supports camelCase access through an intelligent Proxy.

Parameters (short descriptions) #

• APP_NAME

  • Description: Application identifier used for access control.
  • Example: "APP_NAME":"mbkauthe"
  • Required: Yes

• MAIN_SECRET_TOKEN

  • Description: Primary token used for internal auth and validations.
  • Example: "MAIN_SECRET_TOKEN":"my-secret-token"
  • Required: Yes

• SESSION_SECRET_KEY

  • Description: Cryptographic key for sessions/cookies. Use a long random string.
  • Example: "SESSION_SECRET_KEY":"<32+ random chars>"
  • Required: Yes

• IS_DEPLOYED

  • Description: Deployment mode flag; affects cookie domain and localhost behavior.
  • Values: true / false / f (normalized to strings)
  • Example: "IS_DEPLOYED":"false"
  • Required: Yes

• DOMAIN

  • Description: Root app domain used for cross-subdomain cookie sharing in production (e.g., yourdomain.com, not auth.yourdomain.com). When IS_DEPLOYED=true, session cookies are scoped to .yourdomain.com so they are sent on all subdomains.
  • Example: "DOMAIN":"localhost"
  • Required: Yes

• DB_TYPE

  • Description: Which database backend to use.
  • Values: postgres (default) / sqlite
  • Example: "DB_TYPE":"sqlite"
  • Required: No (defaults to postgres)

• LOGIN_DB

  • Description: PostgreSQL connection string for auth (must start with postgresql:// or postgres://).
  • Example: "LOGIN_DB":"postgresql://user:pass@localhost:5432/mbkauth"
  • Required: Yes, when DB_TYPE is postgres (the default)
  • Create free postgres db: https://neon.com/

• SQLITE_PATH

  • Description: Path to the SQLite database file (created if missing). Uses better-sqlite3 under the hood.
  • Example: "SQLITE_PATH":"./data/mbkauthe.sqlite"
  • Required: Yes, when DB_TYPE is sqlite
  • Default: ./mbkauthe.sqlite
  • Run npm run create-tables after setting this to create the schema (loads docs/schema/db.sqlite.sql instead of the Postgres db.sql).

• MBKAUTH_TWO_FA_ENABLE

  • Description: Enable Two-Factor Authentication.
  • Values: true / false / f
  • Example: "MBKAUTH_TWO_FA_ENABLE":"true"
  • Required: Yes

• COOKIE_EXPIRE_TIME

  • Description: Session cookie lifetime (days).
  • Default: 2
  • Example: "COOKIE_EXPIRE_TIME":7
  • Required: No

• DEVICE_TRUST_DURATION_DAYS

  • Description: Days a device remains trusted (skips some auth steps).
  • Default: 7
  • Example: "DEVICE_TRUST_DURATION_DAYS":30
  • Required: No

• MAX_SESSIONS_PER_USER

  • Description: Maximum number of concurrent application sessions allowed per user. When creating a new session that would exceed this number, the oldest session(s) for that user are pruned to make room for the new session.
  • Default: 5
  • Example: "MAX_SESSIONS_PER_USER": 10
  • Notes: Must be a positive integer. Validation is performed at startup by lib/config/index.js.
  • Required: No

• CLI_AUTH_ENABLED

  • Description: Attach the browser-based CLI/device login flow to the main router. Set to "false" or "f" to disable it.
  • Default: "true"
  • Example: "CLI_AUTH_ENABLED":"false"
  • Required: No

• CLI_AUTH_BASE_URL

  • Description: Optional absolute base URL (no trailing slash) used for the CLI verification link. Recommended in production so the device-flow page is reachable regardless of the request host.
  • Example: "CLI_AUTH_BASE_URL":"https://portal.mbktech.org"
  • Required: No

• LOGIN_REDIRECT_URL

  • Description: Post-login redirect path.
  • Default: /dashboard
  • Example: "LOGIN_REDIRECT_URL":"/dashboard"
  • Required: No

• env

  • Description: Development flag to enable diagnostics (DB query monitor, debug endpoints).
  • Values: dev to enable; any other value disables.
  • Example: env=dev
  • Required: No

• bucket

  • Description: Optional external storage bucket name or identifier used for static assets or third-party integrations.
  • Default: an empty string "" (no bucket configured)
  • Example: "bucket":"s3-bucket-name"
  • Usage: Future use in mbkbucket
  • Required: No

• GITHUB_LOGIN_ENABLED / GOOGLE_LOGIN_ENABLED

  • Description: Enable social login providers.
  • Default: false
  • If GOOGLE_LOGIN_ENABLED=true, GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are required.
  • If GITHUB_LOGIN_ENABLED=true, GitHub App client credentials are required.

• GITHUB_APP_CLIENT_ID / GITHUB_APP_CLIENT_SECRET

  • Description: GitHub App OAuth credentials used for user sign-in.
  • Required when GITHUB_LOGIN_ENABLED=true.

• GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET

  • Description: Legacy fallback keys if app-prefixed keys are not provided.

• GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET

  • Description: Google OAuth credentials.
  • Required when GOOGLE_LOGIN_ENABLED=true.
  • Create Google OAuth: https://console.cloud.google.com/

Quick examples #

Development (.env):

mbkautheVar={"APP_NAME":"mbkauthe","MAIN_SECRET_TOKEN":"dev-token","SESSION_SECRET_KEY":"dev-secret","IS_DEPLOYED":"false","DOMAIN":"localhost","LOGIN_DB":"postgresql://user:pass@localhost:5432/mbkauth_dev","MBKAUTH_TWO_FA_ENABLE":"false"}
mbkauthShared={"GITHUB_LOGIN_ENABLED":"false"}

Alternatively, you can provide configuration directly via standard flat environment variables (no JSON packing needed):

APP_NAME=mbkauthe
MAIN_SECRET_TOKEN=dev-token
SESSION_SECRET_KEY=dev-secret
IS_DEPLOYED=false
DOMAIN=localhost
LOGIN_DB=postgresql://user:pass@localhost:5432/mbkauth_dev
MBKAUTH_TWO_FA_ENABLE=false

Production (short):

mbkautheVar={"APP_NAME":"mbkauthe","MAIN_SECRET_TOKEN":"prod-token","SESSION_SECRET_KEY":"prod-secret","IS_DEPLOYED":"true","DOMAIN":"yourdomain.com","LOGIN_DB":"postgresql://dbuser:secure@db:5432/mbkauth_prod","MBKAUTH_TWO_FA_ENABLE":"true"}

SQLite (no external database required):

mbkautheVar={"APP_NAME":"mbkauthe","MAIN_SECRET_TOKEN":"dev-token","SESSION_SECRET_KEY":"dev-secret","IS_DEPLOYED":"false","DOMAIN":"localhost","DB_TYPE":"sqlite","SQLITE_PATH":"./data/mbkauthe.sqlite","MBKAUTH_TWO_FA_ENABLE":"false"}

Then run npm run create-tables to create ./data/mbkauthe.sqlite with the schema in docs/schema/db.sqlite.sql.

Rules & best practices #

• Boolean-like fields: use "true", "false", or "f" (the parser accepts booleans too and normalizes to strings).
• Numeric fields: must be positive numbers (e.g., COOKIE_EXPIRE_TIME, DEVICE_TRUST_DURATION_DAYS).
• LOGIN_DB must start with postgresql:// or postgres://.
• Never commit .env to source control and use HTTPS in production (when IS_DEPLOYED=true).
• Use a >=32-char SESSION_SECRET_KEY and rotate secrets regularly.

For the exact validation messages and default application, consult lib/config/index.js (it will throw a comprehensive error if validation fails at startup).