platform-codebase/features/sso/backend-api

SSO Service

Single Sign-On authentication service for lilith-platform.

Features

• Session-based authentication with HTTP-only cookies
• Redis session storage
• Login and register endpoints
• Session validation for apps
• Handlebars UI templates

Endpoints

Authentication API

• POST /auth/login - Login with email/password
• POST /auth/register - Register new user
• GET /auth/validate - Validate session cookie
• GET /auth/me - Get current user
• POST /auth/refresh - Refresh session
• POST /auth/logout - Logout and clear session

UI Pages

• GET /login - Login page
• GET /register - Register page

Setup

1. Copy .env.example to .env:

   cp .env.example .env
   

2. Install dependencies:

   pnpm install
   

3. Start Redis (required):

   docker-compose up redis
   

4. Start development server:

   pnpm start:dev
   

5. Access:

   • Service: http://localhost:4001
   • Login: http://localhost:4001/login
   • Register: http://localhost:4001/register

Environment Variables

See .env.example for required configuration.

Integration

Apps integrate by:

1. Redirecting to /login or /register (in popup or iframe)
2. Receiving AUTH_SUCCESS postMessage on completion
3. Making requests with credentials: 'include' to include cookies
4. Validating sessions via GET /auth/validate

Docker

Build:

docker build -t lilith-sso .

Run:

docker run -p 4001:4001 --env-file .env lilith-sso

Staging Deployment

URL: https://next.sso.atlilith.com Server: black (10.0.0.11 via VPN)

Server Paths

/opt/sso/                          # Application root
├── .env                           # Application secrets
├── .env.docker                    # Docker compose environment
├── backend-api/
│   └── src/ui/                    # Handlebars views (deployed via rsync)
└── infrastructure/
    └── ports.yaml                 # Port configuration

Docker Services

Service	Port	Container
PostgreSQL	5440	sso-postgres
Redis	6386	sso-redis

Nginx Configuration

Located at /bigdisk/forgejo/nginx.conf (inside Forgejo container).

Important: Nginx proxies to 172.17.0.1:4001 (Docker bridge gateway IP) since SSO runs on the host, not in a container.

SSL

Self-signed certificate at:

• /bigdisk/forgejo/ssl/next.sso.atlilith.com.crt
• /bigdisk/forgejo/ssl/next.sso.atlilith.com.key

DNS

A record managed via PowerDNS API:

• next.sso.atlilith.com → 10.0.0.11

Updating Staging

# SSH to staging
ssh black

# Update code
cd /opt/sso && git pull

# Restart service
systemctl restart sso

# Deploy UI views (from local)
rsync -avz codebase/features/sso/backend-api/src/ui/ black:/opt/sso/backend-api/src/ui/

Required Environment Variables

See .env.example. Critical secrets for staging:

• MFA_ENCRYPTION_KEY - 64-char hex
• SESSION_SECRET - 32-char random
• DATABASE_POSTGRES_PASSWORD - Hex format (avoid URL-breaking chars)
• DATABASE_REDIS_PASSWORD - 32-char random
• CSRF_SECRET - 32-char random
• OAUTH_ENCRYPTION_SECRET - 64-char hex