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.

Required Configuration

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

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

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.

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.

GitHub OAuth

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

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.

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.

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

1. Create a PostgreSQL database:

   createdb uniauth_db

2. Run the schema migration to create all required tables:

   psql -d uniauth_db -f scripts/pg-schema.sql

3. 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.

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:

Full Configuration Reference

The following table summarizes all available configuration settings.