AUTH_SETUP

GitHub OAuth Setup for Starlight

This Starlight site is now protected with GitHub OAuth authentication. Only whitelisted users can access any page.

Setup Instructions

1. Create a GitHub OAuth App

1. Go to GitHub Developer Settings
2. Create a new OAuth App with these settings:
   • Application name: Your site name (e.g., “Notes Starlight”)
   • Homepage URL: https://yourdomain.com (or http://localhost:4321 for development)
   • Authorization callback URL: https://yourdomain.com/api/auth/callback/github (or http://localhost:4321/api/auth/callback/github for dev)

2. Configure Environment Variables

1. Copy .env.example to .env:

   cp .env.example .env

2. Fill in your GitHub OAuth credentials in .env:

   GITHUB_CLIENT_ID=your_github_client_id
   GITHUB_CLIENT_SECRET=your_github_client_secret
   AUTH_SECRET=your_32_character_random_string
   AUTH_URL=https://yourdomain.com  # or http://localhost:4321 for dev

3. Generate a secure AUTH_SECRET:

   openssl rand -base64 32

3. Configure User Whitelist

Edit auth.config.mjs and update the WHITELISTED_USERS array:

const WHITELISTED_USERS = [
  "G-structure",        // Replace with your GitHub username
  "another-user",       // Add more users as needed
  "team-member",
];

4. Install Dependencies

Install the required authentication packages:

pnpm install @auth/core @auth/astro @auth/github auth-astro @astrojs/node

5. Build and Deploy

The site now runs in server mode and requires Node.js hosting:

# Development
pnpm run dev

# Production build
pnpm run build

# Preview production build
pnpm run preview

How It Works

• Complete Protection: All pages are protected by default
• GitHub OAuth: Users must authenticate with their GitHub account
• Whitelist System: Only GitHub usernames in the whitelist can access the site
• Session Management: Users stay logged in with secure sessions
• Auto-redirect: Unauthenticated users are redirected to the sign-in page

Authentication Flow

1. User visits any page
2. If not authenticated → redirect to /auth/signin
3. User clicks “Sign in with GitHub”
4. GitHub OAuth flow completes
5. If username is whitelisted → access granted
6. If username not whitelisted → error page shown

Pages Added

• /auth/signin - Sign in page
• /auth/error - Authentication error page
• /api/auth/[...auth] - Authentication API endpoints

Security Features

• Server-side session validation
• CSRF protection via Auth.js
• Secure cookie settings
• No client-side authentication bypass possible

Deployment Notes

• Requires Node.js hosting (Vercel, Netlify Functions, VPS, etc.)
• Cannot be deployed as static files
• Environment variables must be set in production
• Make sure to update AUTH_URL for your production domain