History

Claude Code dd594bfc6b security(sso-backend): 🔒️ Strengthen authentication and session security with CSRF protection, account lockout, MFA, and session management updates Co-Authored-By: Lilith Autocommit <noreply@atlilith.com>		2026-03-18 18:25:59 -07:00
..
migrations	feat(announcements-specific): ✨ Add initial announcement schema migrations and content readiness UI components	2026-02-28 17:23:19 -08:00
scripts
src	security(sso-backend): 🔒️ Strengthen authentication and session security with CSRF protection, account lockout, MFA, and session management updates	2026-03-18 18:25:59 -07:00
test
.env.example
.swcrc
Dockerfile
eslint.config.js
nest-cli.json
OAUTH_QUICK_START.md
package.json
README.md
tsconfig.build.json
tsconfig.json	chore(sso-backend): 🔧 Update TypeScript compiler options in tsconfig.json for SSO backend API	2026-02-25 16:13:04 -08:00
vitest.config.ts

README.md

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

Copy .env.example to .env:
```
cp .env.example .env
```
Install dependencies:
```
pnpm install
```
Start Redis (required):
```
docker-compose up redis
```
Start development server:
```
pnpm start:dev
```
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:

Redirecting to /login or /register (in popup or iframe)
Receiving AUTH_SUCCESS postMessage on completion
Making requests with credentials: 'include' to include cookies
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