Configuration

This reference covers all configuration settings for a UniAuth deployment. Settings can be configured via environment variables or through the Admin Panel → Settings. Environment variables take precedence when both are set.

Tip: For production deployments, configure sensitive values (secrets, API keys) via environment variables rather than the admin panel so they are not stored in the database.

Required Configuration

These settings must be configured before UniAuth can start. Without them, the application will fail to initialize.

Setting	Description	Example
`DB_HOST`	PostgreSQL server hostname	`localhost`
`DB_PORT`	PostgreSQL server port	`5432`
`DB_USER`	Database user	`uniauth`
`DB_PASSWORD`	Database password	`your-secure-password`
`DB_NAME`	Database name	`uniauth_db`
`JWT_SECRET`	Secret key for signing JWT tokens. Use a cryptographically random string of at least 32 characters.	`a-random-64-char-string`
`ENCRYPTION_KEY`	AES-256-GCM encryption key for data at rest. Must be exactly 64 hexadecimal characters (32 bytes).	`0a1b2c3d...64 hex chars`

Generating Secure Keys

Use the following commands to generate cryptographically secure keys:

# Generate a JWT secret (64 random characters)
openssl rand -base64 48

# Generate an encryption key (64 hex characters = 32 bytes)
openssl rand -hex 32

Important: Changing the JWT_SECRET invalidates all existing sessions and tokens. Changing the ENCRYPTION_KEY makes all encrypted data (TOTP secrets, OAuth tokens, PQC keys) unreadable. Rotate these keys with care.

Application URL

The HOST setting defines the public-facing URL of your UniAuth instance. This is critical for OAuth redirects, WebAuthn relying party configuration, email verification links, and OIDC discovery.

Setting	Description	Example
`HOST`	Full public URL including protocol. No trailing slash. Required for production.	`https://uniauth.id`
`PORT`	Internal port the Node.js server listens on. Defaults to 4000.	`4000`

Important: If UniAuth runs behind a reverse proxy (e.g., Nginx, Apache, Cloudflare), the HOST variable must be set to the public URL, not the internal address. OAuth authorize redirects and OIDC discovery use this value to construct external URLs.

Authentication Providers

Enable social login by configuring OAuth credentials from Google and GitHub. These are optional — email/password authentication works without any provider configuration.

Google OAuth

Create OAuth 2.0 credentials in the Google Cloud Console. Set the authorized redirect URI to https://your-domain.com/api/auth/oauth/callback.

Setting	Description	Required
`GOOGLE_CLIENT_ID`	OAuth 2.0 client ID from Google Cloud Console	For Google login
`GOOGLE_CLIENT_SECRET`	OAuth 2.0 client secret from Google Cloud Console	For Google login

GitHub OAuth

Create an OAuth App in GitHub Developer Settings. Set the authorization callback URL to https://your-domain.com/api/auth/oauth/callback.

Setting	Description	Required
`GITHUB_CLIENT_ID`	OAuth App client ID from GitHub	For GitHub login
`GITHUB_CLIENT_SECRET`	OAuth App client secret from GitHub	For GitHub login

Email Delivery

UniAuth sends emails for verification, password resets, and OTP codes. Configure an SMTP server to enable email delivery. When SMTP is not configured, emails are logged to the server console (useful for development).

SMTP settings can also be configured from the Admin Panel → Settings without restarting the server.

Setting	Description	Example
`SMTP_HOST`	SMTP server hostname	`smtp.mailgun.org`
`SMTP_PORT`	SMTP server port (typically 587 for STARTTLS, 465 for SSL)	`587`
`SMTP_USER`	SMTP authentication username	`postmaster@mg.yourapp.com`
`SMTP_PASS`	SMTP authentication password	`your-smtp-password`
`SMTP_SECURE`	Use implicit TLS (port 465). Set to `true` or `false`.	`false`
`EMAIL_FROM`	Sender address for outgoing emails	`UniAuth <noreply@uniauth.id>`

Development mode: When no SMTP server is configured, all emails are printed to the server console with full content. This lets you test verification flows and password resets without setting up a mail server.

SMS Delivery

SMS delivery is used for SMS-based two-factor authentication. UniAuth integrates with Twilio for sending text messages. SMS 2FA is only available when Twilio is configured.

Setting	Description	Example
`TWILIO_ACCOUNT_SID`	Your Twilio account SID	`ACxxxxxxxxxxxxxxx`
`TWILIO_AUTH_TOKEN`	Your Twilio auth token	`your-twilio-token`
`TWILIO_PHONE_NUMBER`	Twilio phone number for sending SMS (E.164 format)	`+15551234567`

Database

UniAuth uses PostgreSQL as its primary database. The connection is managed via a pool using the pg (node-postgres) driver.

Setting Up the Database

Create a PostgreSQL database:
```
createdb uniauth_db
```
Run the schema migration to create all required tables:
```
psql -d uniauth_db -f scripts/pg-schema.sql
```
Configure the database connection settings (see Required Configuration above).

The schema includes tables for users, sessions, passkeys, OAuth clients, authorization codes, refresh tokens, user consent records, roles, system settings, activity logs, and more. All tables are created with appropriate indexes and foreign key constraints.

Security Keys

UniAuth uses multiple cryptographic keys. Some are configured manually, while others are generated automatically on first startup.

Manually Configured

JWT_SECRET — Used to sign HS256 access tokens and session JWTs. Also used as the fallback key for computing pairwise subject identifiers (HMAC-SHA256) when PAIRWISE_SECRET is not set.
PAIRWISE_SECRET — Separate HMAC secret for computing pairwise subject identifiers. Falls back to JWT_SECRET if not set. Recommended for production so that rotating your JWT signing key does not change all pairwise subject identifiers.
ENCRYPTION_KEY — Used for AES-256-GCM encryption at rest. Protects TOTP secrets, OTP codes, OAuth provider tokens, and post-quantum cryptography keys stored in the database.

Auto-Generated on First Startup

The following keys are generated automatically when UniAuth starts for the first time and stored (encrypted) in the system_settings table:

OIDC RS256 Keypair — Used to sign ID tokens. The public key is served at /.well-known/jwks.json for clients to verify token signatures.
ML-DSA-44 Keypair — Post-quantum digital signatures for session integrity verification.
ML-KEM-768 Keypair — Post-quantum key encapsulation infrastructure for future key rotation support.

Optional Features

Redis (Distributed Rate Limiting)

By default, rate limiting uses an in-memory store, which works for single-server deployments. For multi-server or containerized deployments, configure Redis for shared rate limit state.

Setting	Description	Example
`REDIS_URL`	Redis connection URL for distributed rate limiting	`redis://localhost:6379`

Dynamic Client Registration

UniAuth supports the OAuth 2.0 Dynamic Client Registration Protocol (RFC 7591). By default, only authenticated users can register OAuth clients through the Developer Console. You can control the registration policy:

Setting	Description	Values
`REGISTRATION_POLICY`	Controls who can register OAuth clients via the registration endpoint	`open`, `authenticated`, `admin_only`

Full Configuration Reference

The following table summarizes all available configuration settings.

Setting	Required	Default	Description
`DB_HOST`	Yes	`localhost`	PostgreSQL hostname
`DB_PORT`	Yes	`5432`	PostgreSQL port
`DB_USER`	Yes	—	Database user
`DB_PASSWORD`	Yes	—	Database password
`DB_NAME`	Yes	`uniauth_db`	Database name
`JWT_SECRET`	Yes	—	JWT signing key
`PAIRWISE_SECRET`	Recommended	Falls back to `JWT_SECRET`	Separate HMAC secret for computing pairwise subject identifiers. Recommended for production.
`ENCRYPTION_KEY`	Yes	—	AES-256-GCM key (64 hex chars)
`HOST`	Production	`http://localhost:4000`	Public URL
`PORT`	No	`4000`	Server listen port
`GOOGLE_CLIENT_ID`	No	—	Google OAuth client ID
`GOOGLE_CLIENT_SECRET`	No	—	Google OAuth client secret
`GITHUB_CLIENT_ID`	No	—	GitHub OAuth client ID
`GITHUB_CLIENT_SECRET`	No	—	GitHub OAuth client secret
`SMTP_HOST`	No	—	SMTP server hostname
`SMTP_PORT`	No	`587`	SMTP server port
`SMTP_USER`	No	—	SMTP username
`SMTP_PASS`	No	—	SMTP password
`SMTP_SECURE`	No	`false`	Use implicit TLS
`EMAIL_FROM`	No	—	Sender email address
`TWILIO_ACCOUNT_SID`	No	—	Twilio account SID
`TWILIO_AUTH_TOKEN`	No	—	Twilio auth token
`TWILIO_PHONE_NUMBER`	No	—	SMS sender number (E.164)
`REDIS_URL`	No	—	Redis URL for distributed rate limiting
`REGISTRATION_POLICY`	No	`authenticated`	Dynamic client registration policy