Dashboard Authentication

Secure your Codex-LB dashboard with password and TOTP two-factor authentication

Overview

Codex-LB supports multi-layered authentication for the admin dashboard:

• Password authentication - bcrypt-hashed password stored in database
• TOTP (Time-based One-Time Password) - Optional 2FA using authenticator apps
• Session management - 12-hour encrypted session cookies
• Rate limiting - Protection against brute-force attacks

By default, authentication is disabled for easy first-time setup. Once configured, all /api/* endpoints (except auth endpoints) require valid authentication.

API key authentication (for proxy endpoints) and dashboard authentication (for admin endpoints) are separate systems. See API Keys for proxy authentication.

Password Authentication

Initial Setup

On first launch, the dashboard is open (no authentication required). Set up password protection:

1. Navigate to Settings → Security
2. Click Setup Password
3. Enter a strong password (minimum 8 characters)
4. Click Save

From app/modules/dashboard_auth/service.py:210-213:

async def setup_password(self, password: str) -> None:
    setup_ok = await self._repository.try_set_password_hash(_hash_password(password))
    if not setup_ok:
        raise PasswordAlreadyConfiguredError("Password is already configured")

Password is hashed using bcrypt:

# From app/modules/dashboard_auth/service.py:337-338
def _hash_password(password: str) -> str:
    return bcrypt.hashpw(password.encode("utf-8"), bcrypt.gensalt()).decode("utf-8")

Password setup is a one-time operation. Once configured, you must use the password change flow to update it.

Logging In

Once password is configured, the dashboard requires authentication:

1. Navigate to dashboard URL
2. Enter password in login form
3. Click Sign In
4. Receive 12-hour session cookie

API endpoint:

POST /api/dashboard-auth/password/login

{
  "password": "your-password"
}

Response:

{
  "authenticated": true,
  "password_required": true,
  "totp_required_on_login": false,
  "totp_configured": false
}

Sets cookie: codex_lb_dashboard_session (httponly, secure, samesite=lax, 12h expiry)

Session Management

Sessions are encrypted using Fernet (symmetric encryption):

# From app/modules/dashboard_auth/service.py:95-101
def create(self, *, password_verified: bool, totp_verified: bool) -> str:
    expires_at = int(time()) + _SESSION_TTL_SECONDS  # 12 hours
    payload = json.dumps(
        {"exp": expires_at, "pw": password_verified, "tv": totp_verified},
        separators=(",", ":"),
    )
    return self._get_encryptor().encrypt(payload).decode("ascii")

Session payload:

• exp: Expiration timestamp
• pw: Password verified (boolean)
• tv: TOTP verified (boolean)

From app/modules/dashboard_auth/service.py:18-19:

DASHBOARD_SESSION_COOKIE = "codex_lb_dashboard_session"
_SESSION_TTL_SECONDS = 12 * 60 * 60  # 12 hours

Changing Password

Requirements: Valid authenticated session

POST /api/dashboard-auth/password/change

{
  "current_password": "old-password",
  "new_password": "new-password"
}

From app/modules/dashboard_auth/service.py:222-224:

async def change_password(self, current_password: str, new_password: str) -> None:
    await self.verify_password(current_password)
    await self._repository.set_password_hash(_hash_password(new_password))

Removing Password

To return to unauthenticated mode:

DELETE /api/dashboard-auth/password

{
  "password": "current-password"
}

From app/modules/dashboard_auth/service.py:226-228:

async def remove_password(self, password: str) -> None:
    await self.verify_password(password)
    await self._repository.clear_password_and_totp()  # Also clears TOTP!

Removing password also disables TOTP and clears the secret. This returns the system to completely unauthenticated mode.

TOTP Two-Factor Authentication

Prerequisites

TOTP requires an active password session. You cannot enable TOTP without first configuring password auth.

Setting Up TOTP

1. Log in with password
2. Navigate to Settings → Security → Two-Factor Authentication
3. Click Enable TOTP
4. Scan QR code with authenticator app (Google Authenticator, Authy, 1Password, etc.)
5. Enter 6-digit code from app
6. Click Verify

API flow:

Step 1: Start setup

POST /api/dashboard-auth/totp/setup/start

Response:

{
  "secret": "JBSWY3DPEHPK3PXP",
  "otpauth_uri": "otpauth://totp/codex-lb:dashboard?secret=JBSWY3DPEHPK3PXP&issuer=codex-lb",
  "qr_svg_data_uri": "data:image/svg+xml;base64,..."
}

From app/modules/dashboard_auth/service.py:246-256:

async def start_totp_setup(self, *, session_id: str | None) -> TotpSetupStartResponse:
    settings = await self._require_active_password_session(session_id)
    if settings.totp_secret_encrypted is not None:
        raise TotpAlreadyConfiguredError("TOTP is already configured...")
    secret = generate_totp_secret()  # 32-char base32 secret
    otpauth_uri = build_otpauth_uri(secret, issuer=_TOTP_ISSUER, account_name=_TOTP_ACCOUNT)
    return TotpSetupStartResponse(
        secret=secret,
        otpauth_uri=otpauth_uri,
        qr_svg_data_uri=_qr_svg_data_uri(otpauth_uri),  # SVG QR code as data URI
    )

Step 2: Confirm setup

POST /api/dashboard-auth/totp/setup/confirm

{
  "secret": "JBSWY3DPEHPK3PXP",
  "code": "123456"
}

Verifies the code and stores encrypted secret:

# From app/modules/dashboard_auth/service.py:258-268
async def confirm_totp_setup(self, *, session_id: str | None, secret: str, code: str) -> None:
    current = await self._require_active_password_session(session_id)
    if current.totp_secret_encrypted is not None:
        raise TotpAlreadyConfiguredError("TOTP is already configured...")
    verification = verify_totp_code(secret, code, window=1)
    if not verification.is_valid:
        raise TotpInvalidCodeError("Invalid TOTP code")
    await self._repository.set_totp_secret(self._encryptor.encrypt(secret))

TOTP uses standard 6-digit codes, 30-second time steps, SHA-1 algorithm, and window=1 (accepts codes from previous/current/next time step for clock skew tolerance).

Logging In with TOTP

Once TOTP is configured and totp_required_on_login is enabled:

1. Enter password → Creates session with pw=true, tv=false
2. Dashboard shows TOTP prompt
3. Enter 6-digit code from authenticator app
4. Upgrades session to pw=true, tv=true

TOTP verification:

POST /api/dashboard-auth/totp/verify

{
  "code": "123456"
}

From app/modules/dashboard_auth/service.py:270-287:

async def verify_totp(self, *, session_id: str | None, code: str) -> str:
    settings = await self._require_active_password_session(session_id)
    secret_encrypted = settings.totp_secret_encrypted
    if secret_encrypted is None:
        raise TotpNotConfiguredError("TOTP is not configured")
    secret = self._encryptor.decrypt(secret_encrypted)
    verification = verify_totp_code(
        secret,
        code,
        window=1,
        last_verified_step=settings.totp_last_verified_step,  # Replay protection
    )
    if not verification.is_valid or verification.matched_step is None:
        raise TotpInvalidCodeError("Invalid TOTP code")
    updated = await self._repository.try_advance_totp_last_verified_step(verification.matched_step)
    if not updated:
        raise TotpInvalidCodeError("Invalid TOTP code")
    return self._session_store.create(password_verified=True, totp_verified=True)

Replay protection: The totp_last_verified_step field prevents reusing codes. Each time step is a 30-second counter, and the system tracks the most recent verified step.

Disabling TOTP

Requirements: TOTP-verified session

POST /api/dashboard-auth/totp/disable

{
  "code": "123456"  // Current valid TOTP code required
}

From app/modules/dashboard_auth/service.py:289-306:

async def disable_totp(self, *, session_id: str | None, code: str) -> None:
    settings = await self._require_totp_verified_session(session_id)
    secret_encrypted = settings.totp_secret_encrypted
    if secret_encrypted is None:
        raise TotpNotConfiguredError("TOTP is not configured")
    secret = self._encryptor.decrypt(secret_encrypted)
    verification = verify_totp_code(
        secret,
        code,
        window=1,
        last_verified_step=settings.totp_last_verified_step,
    )
    if not verification.is_valid or verification.matched_step is None:
        raise TotpInvalidCodeError("Invalid TOTP code")
    # ... verify and clear TOTP secret
    await self._repository.set_totp_secret(None)

Authentication Guard

Scope

Authentication is enforced on all /api/* routes except:

• /api/dashboard-auth/* (auth endpoints themselves)
• /api/codex/usage (uses separate bearer caller identity validation)

Guard Logic

From openspec/specs/admin-auth/spec.md:84-96:

Authentication required condition: the system SHALL evaluate password_hash and totp_required_on_login together to determine whether authentication is required. When password_hash is NULL and totp_required_on_login is false, the guard MUST allow all requests (unauthenticated mode). When either password_hash is set or totp_required_on_login is true, the guard MUST require a valid session.

Session validation steps when requires_auth is true:

1. Valid session cookie must be present (else 401)
2. If password_hash is not NULL, session must have password_verified=true
3. If totp_required_on_login is true, session must have totp_verified=true

From app/modules/dashboard_auth/service.py:187-208:

async def get_session_state(self, session_id: str | None) -> DashboardAuthSessionResponse:
    settings = await self._repository.get_settings()
    password_required = settings.password_hash is not None
    totp_required = password_required and settings.totp_required_on_login
    totp_configured = settings.totp_secret_encrypted is not None
    state = self._session_store.get(session_id) if password_required else None
    password_authenticated = bool(state and state.password_verified)
    
    if not password_required:
        authenticated = True  # Unauthenticated mode
    elif totp_required:
        authenticated = bool(state and state.password_verified and state.totp_verified)
    else:
        authenticated = password_authenticated

    # Surface TOTP prompt only for password-authenticated sessions
    totp_required_on_login = bool(totp_required and password_authenticated)
    return DashboardAuthSessionResponse(
        authenticated=authenticated,
        password_required=password_required,
        totp_required_on_login=totp_required_on_login,
        totp_configured=totp_configured,
    )

Session State Endpoint

Check current authentication state:

GET /api/dashboard-auth/session

Response (unauthenticated mode):

{
  "authenticated": true,
  "password_required": false,
  "totp_required_on_login": false,
  "totp_configured": false
}

Response (password set, not logged in):

{
  "authenticated": false,
  "password_required": true,
  "totp_required_on_login": false,
  "totp_configured": false
}

Response (logged in with password, TOTP pending):

{
  "authenticated": false,
  "password_required": true,
  "totp_required_on_login": true,
  "totp_configured": true
}

Response (fully authenticated with TOTP):

{
  "authenticated": true,
  "password_required": true,
  "totp_required_on_login": false,  // Already verified in this session
  "totp_configured": true
}

Rate Limiting

Both password and TOTP login attempts are rate-limited:

# From app/modules/dashboard_auth/service.py:312-326
_totp_rate_limiter = TotpRateLimiter(max_failures=8, window_seconds=60)
_password_rate_limiter = TotpRateLimiter(max_failures=8, window_seconds=60)

Limits: 8 failures per 60-second window

Rate limit logic (from app/modules/dashboard_auth/service.py:143-178):

def check(self, key: str) -> int | None:
    now = int(time())
    failures = self._failures.get(key)
    if failures is None:
        return None
    cutoff = now - self._window_seconds
    while failures and failures[0] <= cutoff:
        failures.popleft()  # Remove old failures outside window
    if not failures:
        self._failures.pop(key, None)
        return None
    if len(failures) >= self._max_failures:
        retry_after = failures[0] + self._window_seconds - now
        return max(1, retry_after)
    return None

On rate limit breach:

• HTTP Status: 429 Too Many Requests
• Header: Retry-After: {seconds}
• Error: {"error": {"code": "rate_limit_exceeded", ...}}

Rate limit state is stored in-memory and resets on server restart. For production deployments with multiple instances, consider implementing distributed rate limiting.

Settings Cache

To avoid per-request database queries, settings are cached:

From openspec/specs/admin-auth/spec.md:179-192:

The system SHALL cache DashboardSettings in memory with a TTL of 5 seconds to avoid per-request DB queries in the auth guard. The cache MUST be invalidated immediately when settings are modified via the settings API or password/TOTP management endpoints.

Cache behavior:

• TTL: 5 seconds
• Invalidation: Immediate on setting changes
• Benefit: Reduces DB load on high-traffic dashboards

Logout

POST /api/dashboard-auth/logout

Clears session cookie (server-side no-op since sessions are stateless/encrypted).

From app/modules/dashboard_auth/service.py:308-309:

def logout(self, session_id: str | None) -> None:
    self._session_store.delete(session_id)  # Stateless: client-side cookie clear

Security Best Practices

Strong Passwords

• Minimum 8 characters (enforced)
• Recommended: 12+ characters with mixed case, numbers, symbols
• Use a password manager

Enable TOTP

Always enable TOTP for production deployments:

1. Setup password
2. Configure TOTP
3. Enable Settings → Require TOTP on Login

TOTP adds a second factor even if password is compromised. Highly recommended for production.

Network Security

• HTTPS: Always run behind HTTPS in production
• Firewall: Restrict dashboard access to trusted IPs
• Reverse proxy: Use nginx/Caddy for TLS termination

Session Security

Sessions use Fernet encryption with a key derived from environment:

# From app/core/crypto.py (implied)
# Encryption key derived from ENCRYPTION_KEY or SECRET_KEY environment variable

Environment variables:

# Generate secure key:
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

# Set in environment:
export ENCRYPTION_KEY="your-generated-key-here"

If ENCRYPTION_KEY changes, all existing sessions are invalidated. Users must re-login.

Troubleshooting

Locked Out (Forgot Password)

If you forget the password:

Option 1: Reset via database

UPDATE dashboard_settings 
SET password_hash = NULL, totp_secret_encrypted = NULL, totp_required_on_login = false 
WHERE id = 1;

This returns to unauthenticated mode.

Option 2: Set new password hash

# Generate new hash
import bcrypt
new_hash = bcrypt.hashpw(b"new-password", bcrypt.gensalt()).decode("utf-8")
print(new_hash)

Then update database:

UPDATE dashboard_settings SET password_hash = '$2b$12$...' WHERE id = 1;

TOTP Code Not Working

Causes:

• Clock skew between server and authenticator app
• Wrong secret scanned
• Code already used (replay protection)

Solutions:

1. Ensure server and device clocks are synced (NTP)
2. Re-scan QR code in authenticator app
3. Wait for next 30-second window

Rate Limited

Symptom: 429 Too Many Requests

Cause: 8 failed login attempts in 60 seconds

Solution: Wait for the Retry-After duration (shown in error response)

Session Expired

Symptom: Dashboard redirects to login after 12 hours

Cause: Normal session TTL behavior

Solution: Log in again. Consider increasing _SESSION_TTL_SECONDS in code if needed.

Related Features

• API Keys - Authenticate proxy requests (separate from dashboard auth)
• Account Pooling - Manage pooled accounts
• Usage Tracking - Monitor dashboard activity

Technical Reference

Key source files:

• app/modules/dashboard_auth/service.py - Auth business logic
• app/modules/dashboard_auth/repository.py - Database operations
• app/modules/dashboard_auth/schemas.py - API schemas
• app/core/auth/totp.py - TOTP implementation
• app/core/crypto.py - Encryption utilities
• openspec/specs/admin-auth/spec.md - Detailed specification