Skip to main content

Authentication Flow

Overview​

This flow shows how users authenticate via Google OAuth, how new users are registered and approved, and how sessions are managed throughout the application.

Authentication Flow​

1. Initial Access​

When a user visits the site:

  • If not authenticated → Redirect to /login.html
  • If authenticated → Check if user is approved
  • If not approved → Redirect to /pending-approval.html

2. Google OAuth Login​

Location: server.js:677 - GET /auth/google

  1. User clicks "Sign in with Google"
  2. Redirects to Google OAuth consent screen
  3. User selects Google account and grants permissions
  4. Google redirects to callback URL: /auth/google/callback

3. OAuth Callback Processing​

Location: server.js:683 - GET /auth/google/callback
Location: auth.js:35 - GoogleStrategy callback

Process:

  1. Extract User Profile:

    • Email address
    • Display name
    • Profile picture
    • Google user ID

  2. Check Banned Emails:

    • Query banned_emails table
    • If banned → Return error, block login
    • Location: auth.js:45

  3. Determine Approval Status:

    • Admin users (info@fyrster.dk) → Auto-approved
    • New users → Pending approval (approved = false)
    • Location: auth.js:58

  4. Upsert User in Database:

    INSERT INTO users (user_id, email, name, picture, approved, updated_at)
    VALUES ($1, $2, $3, $4, $5, CURRENT_TIMESTAMP)
    ON CONFLICT (user_id) 
    DO UPDATE SET email = EXCLUDED.email, ...
    • Location: auth.js:63

  5. Create Session:

    • Passport serializes user object
    • Session stored in database (express-session)
    • Location: auth.js:119, server.js:687

  6. Redirect:

    • If approved → Redirect to home page
    • If pending → Redirect to /pending-approval.html

Session Validation​

On Every API Request​

Location: server.js:123 - isAuthenticated middleware

  1. Check Authentication:

    • req.isAuthenticated() checks session
    • If not authenticated → Return 401

  2. Check Approval:

    • Location: server.js:140 - checkUserApproved
    • Query database for approved status
    • If not approved → Return 403 (Account pending approval)
    • If approved → Process request

Logout Flow​

Location: server.js:698 - GET /auth/logout

  1. User clicks logout
  2. Passport logout (req.logout())
  3. Destroy session (req.session.destroy())
  4. Redirect to /login.html

Security Features​

Banned Email Protection​

  • Emails in banned_emails table are blocked before user creation
  • Ban reason is returned to user
  • Location: auth.js:45-54

Admin Auto-Approval​

  • info@fyrster.dk is automatically approved
  • Other users require admin approval
  • Location: auth.js:58-59

Session Security​

  • Sessions stored server-side (not in cookies)
  • Session validated on every request
  • Unapproved users cannot access API endpoints

Database Schema​

users Table​

CREATE TABLE users (
  user_id VARCHAR(255) PRIMARY KEY,  -- Google user ID
  email VARCHAR(255),
  name VARCHAR(255),
  picture TEXT,
  approved BOOLEAN DEFAULT false,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

banned_emails Table​

CREATE TABLE banned_emails (
  id SERIAL PRIMARY KEY,
  email VARCHAR(255) UNIQUE NOT NULL,
  reason TEXT,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

API Endpoints​

GET /auth/google​

  • Initiates Google OAuth flow
  • Redirects to Google consent screen

GET /auth/google/callback​

  • Google OAuth callback
  • Processes authentication
  • Creates/updates user
  • Creates session
  • Redirects based on approval status

GET /auth/logout​

  • Logs out user
  • Destroys session
  • Redirects to login

Error Handling​

Authentication Errors​

  • 401 Unauthorized: User not authenticated
  • 403 Forbidden: User not approved (pending approval)

Banned Email​

  • Error message includes ban reason
  • User cannot proceed with login

User Approval Workflow​

  1. New User Registration:

    • User logs in with Google
    • User created with approved = false
    • Redirected to pending approval page

  2. Admin Approval:

    • Admin views user list (GET /api/admin/users)
    • Admin approves user (POST /api/admin/users/:userId/approve)
    • User can now access platform

  3. Auto-Approval:

    • Admin email (info@fyrster.dk) is auto-approved
    • No manual approval needed