platform-codebase/features/platform-admin/frontend-admin/docs/authentication.md

Platform Admin Authentication

Environment-Specific Authentication

Platform Admin uses different authentication methods based on the deployment environment, automatically detected via hostname.

Development Environment

Hostname: admin.atlilith.local or localhost

Behavior:

• Login page shows dev mode notice
• No credentials required
• Uses dev user switcher (bottom-left corner of screen)
• Switch between "Admin" (full access) and "Employee" (limited access)

Tech Stack:

• DevUserProvider from @lilith/ui-dev-tools
• AuthProviderWithDevBridge bridges dev user state to auth state
• Dev user types defined in src/config/devUserTypes.ts

How to Login:

1. Navigate to http://admin.atlilith.local:3201/
2. Click the dev user switcher in bottom-left corner
3. Select user type (Admin or Employee)
4. Automatically redirected to dashboard

---

Staging Environment

Hostname: Any hostname containing "staging" (e.g., staging-admin.atlilith.com, admin.staging.atlilith.com)

Behavior:

• Login page shows simple username/password form
• Credentials pre-filled with staging values
• Uses credential-based login via SSO backend

Credentials:

Username: stagingadmin
Password: stagingpassword

Tech Stack:

• loginWithCredentials() from @lilith/auth-provider
• Sends credentials to SSO service via SSOClient
• Returns authenticated user on success

How to Login:

1. Navigate to staging URL
2. Form automatically pre-filled with staging credentials
3. Click "Login" button
4. Redirects to dashboard on success

---

Production Environment

Hostname: admin.atlilith.com or any non-staging production domain

Behavior:

• Login page shows SSO login button
• Opens OAuth popup window for authentication
• Full security with proper session management

Tech Stack:

• login() from @lilith/auth-provider
• SSOClient opens OAuth popup
• Returns authenticated user on success

How to Login:

1. Navigate to https://admin.atlilith.com/
2. Click "Login with SSO" button
3. Complete authentication in popup window
4. Redirects to dashboard on success

---

Authentication Flow

Components

1. LoginPage (src/pages/LoginPage.tsx)

   • Detects environment via window.location.hostname
   • Renders appropriate UI for each environment
   • Handles login submission

2. AdminOnlyGuard (src/components/AdminOnlyGuard.tsx)

   • Checks authentication state via useAuth()
   • Redirects unauthenticated users to /login
   • Blocks employees from accessing admin-only pages (403)

3. App Router (src/App.tsx)

   • /login route is public (no guard)
   • All other routes wrapped with AdminOnlyGuard

Authentication Providers

ThemeProvider
└─ DevUserProvider (dev mode only)
   └─ AuthProviderWithDevBridge
      └─ AuthProvider (SSO integration)
         └─ App

Provider Flow:

1. DevUserProvider: Manages dev user switcher state
2. AuthProviderWithDevBridge: Bridges dev user to auth state in development
3. AuthProvider: Core authentication (SSO client, session management)

---

Environment Detection Logic

function detectEnvironment(): Environment {
  const hostname = window.location.hostname;

  // Development: admin.atlilith.local or localhost
  if (hostname.endsWith('.atlilith.local') || hostname === 'localhost') {
    return 'development';
  }

  // Staging: staging-admin.atlilith.com or admin.staging.atlilith.com
  if (hostname.includes('staging')) {
    return 'staging';
  }

  // Production: admin.atlilith.com or similar
  return 'production';
}

---

Security Notes

Development

• Dev user switcher is only available when import.meta.env.DEV === true
• Production builds automatically disable dev mode features
• No real credentials or sessions in development

Staging

• Uses real SSO backend but simplified credential flow
• Credentials are pre-filled for convenience
• Not secure for production use

Production

• Full OAuth flow with popup window
• Secure session management via SSO service
• No credentials stored in frontend
• Session validated on every request

---

Access Levels

Defined in @lilith/types as AccessLevel enum:

enum AccessLevel {
  ADMIN = 'admin',        // Full platform access (Platform Admin)
  EMPLOYEE = 'employee',  // Limited access (blocked by AdminOnlyGuard)
  USER = 'user',          // No access (blocked by AdminOnlyGuard)
}

AdminOnlyGuard only allows AccessLevel.ADMIN:

• Admins: Full access to all features
• Employees: Blocked with 403 error
• Users: Redirected to login

---

Development Workflow

Starting Platform Admin

# From platform-admin frontend directory
cd features/platform-admin/frontend-admin
pnpm dev

Runs on: http://admin.atlilith.local:3201/

Testing Different Environments

Development:

• URL: http://admin.atlilith.local:3201/
• Use dev user switcher to authenticate

Staging (simulated locally):

• Modify /etc/hosts: 127.0.0.1 staging-admin.atlilith.local
• URL: http://staging-admin.atlilith.local:3201/
• Uses staging credentials

Production (simulated locally):

• Modify /etc/hosts: 127.0.0.1 admin.atlilith.local
• Set NODE_ENV=production in build
• URL: http://admin.atlilith.local:3201/
• Requires real SSO service

---

Configuration

SSO URL

Defined in src/main.tsx:

const ssoUrl = import.meta.env.VITE_SSO_URL || 'https://next.sso.atlilith.com';

Override for local development:

VITE_SSO_URL=http://localhost:4001 pnpm dev

Dev User Types

Defined in src/config/devUserTypes.ts:

export const PLATFORM_ADMIN_DEV_USER_TYPES: DevUserTypeConfig[] = [
  {
    id: 'employee',
    label: 'Employee',
    emoji: '👔',
    description: 'Platform employee with elevated access',
  },
  {
    id: 'admin',
    label: 'Admin',
    emoji: '👑',
    description: 'Full administrative access',
  },
];

---

Troubleshooting

Issue: Login page shows but dev user switcher is missing

Solution: Ensure you're accessing via admin.atlilith.local (not localhost)

• Dev user switcher only appears when hostname ends with .atlilith.local

Issue: Staging credentials don't work

Solution:

1. Verify hostname contains "staging"
2. Check SSO backend is running and configured for staging credentials
3. Check browser console for errors

Issue: Redirected to login after authenticating

Solution:

1. Check AdminOnlyGuard logic in browser DevTools
2. Verify user has accessLevel: AccessLevel.ADMIN
3. Check auth state in React DevTools

Issue: Dev user switcher shows but auth state not updating

Solution:

1. Check DevUserProvider is wrapping AuthProviderWithDevBridge
2. Verify mapPlatformAdminDevUser is correctly mapping dev user to User type
3. Check browser console for errors

---

Last Updated: 2026-01-23