Authentication System Overview

Authentication System Overview

The 8531 TeamSite uses a comprehensive authentication and authorization system built on OAuth 2.0 and JWT tokens with role-based access control.

🌐 Domain Architecture

Environments

• Production: https://team.8531.ca - Main production site
• Development: https://dev.team.8531.ca - Staging and preview deployments
• Local: http://localhost:4321 - Local development environment

Authentication Flow

User clicks login →
Redirect to auth.8531.ca →
Google OAuth authentication →
JWT token generation →
Redirect back with token →
Token verification →
Access granted based on role

🔐 JWT Token Structure

The JWT payload contains the following information:

interface JWTPayload {
  sub: string;        // User ID
  email: string;      // User email
  name: string;       // User display name
  picture?: string;   // Profile picture URL
  role: string;       // User role (Admin|CoreTeam|Member|Guest)
  exp: number;        // Expiration time
  iat: number;        // Issued at time
  iss: string;        // Issuer (auth.8531.ca)
  aud: string;        // Audience (8531-apps)
}

👥 Role Hierarchy

The system implements a four-tier permission system:

1. Admin - Full access to all content and settings

   • Can see all content regardless of status
   • Can access admin-only pages
   • Can manage user roles and permissions

2. CoreTeam - Access to team documentation and internal resources

   • Can access CoreTeam and Member content
   • Can see draft and review status content
   • Cannot access admin-only content

3. Member - Access to member resources and basic documentation

   • Can access Member content
   • Cannot see draft/review content
   • Cannot access CoreTeam or Admin content

4. Guest - Public access only

   • Can only access public content
   • No authentication required

🛡️ Security Features

• RS256 Encryption: Asymmetric JWT tokens for enhanced security
• HTTP-Only Cookies: Prevent XSS attacks on authentication tokens
• SameSite Policy: Strict CSRF protection
• Secure Headers: X-Frame-Options, Content-Type-Options, etc.
• CORS Configuration: Environment-specific cross-origin policies
• Token Expiration: 1-hour access tokens with refresh capability
• Zero Trust Architecture: All requests require authentication

🧪 Testing Authentication Locally

Testing Different Roles

For local development, you can test different user roles by adding query parameters:

# Test as Guest (default)
http://localhost:4321

# Test as Member
http://localhost:4321?test_role=Member

# Test as Core Team
http://localhost:4321?test_role=CoreTeam

# Test as Admin
http://localhost:4321?test_role=Admin

Testing Content Status Management

For local development, you can test content status filtering:

# Show all content regardless of status (development override)
http://localhost:4321?show_status=true

# Test specific role with status bypass
http://localhost:4321?test_role=CoreTeam&show_status=true

# Test draft content access
http://localhost:4321?test_role=Admin  # Admin can see draft content
http://localhost:4321?test_role=Guest  # Guest cannot see draft content

📋 Environment Configuration

Required Environment Variables

NODE_ENV=development                    # Environment type
HOSTNAME=localhost:4321                # Current hostname
AUTH_GATEWAY_URL=https://auth.8531.ca  # Auth service URL
JWT_SECRET=your-jwt-secret              # JWT signing secret
JWT_ISSUER=https://auth.8531.ca        # JWT issuer
JWT_AUDIENCE=8531-apps                  # JWT audience
SITE_URL=http://localhost:4321          # Site URL

Local Development Setup

1. Copy .env.example to .env.local:

   cp .env.example .env.local

2. Configure the required variables for your environment

3. Restart the development server

🔑 Supported Auth Providers

• Google OAuth: Primary authentication provider
• Additional Providers: Configurable through auth gateway

📊 Monitoring & Analytics

Authentication Metrics Tracked

• Login success/failure rates
• Token refresh patterns
• Session duration analytics
• Geographic access patterns
• Role-based access statistics

Security Metrics

• Failed authentication attempts
• Token validation failures
• Unauthorized access attempts
• CORS policy violations
• Session timeout events

🔒 Security Best Practices

1. Principle of Least Privilege: Users get minimum required access
2. Key Rotation: Automatic public key fetching from auth gateway
3. Secure Transmission: HTTPS-only in production environments
4. Session Management: Proper timeout and refresh mechanisms
5. Access Logging: Comprehensive audit trail for security events

🛠️ Implementation Details

Authentication Middleware

The authentication is handled by /src/lib/route-middleware.ts which:

1. Validates JWT tokens on protected routes
2. Extracts user information from token
3. Enforces role-based access control
4. Handles token refresh when needed

API Authentication

API endpoints use the same authentication system:

1. JWT validation for all protected endpoints
2. Role-based endpoint access
3. Secure session management
4. Rate limiting protection

Frontend Authentication

The frontend manages authentication through:

1. AuthButton.astro component for login/logout
2. Client-side token storage in HTTP-only cookies
3. Automatic redirect on authentication failure
4. Role-based UI rendering

🚨 Troubleshooting

Common Issues

1. “Invalid Token” Error

   • Check if token has expired
   • Verify JWT secret configuration
   • Ensure proper token format

2. “Access Denied” Error

   • Verify user role permissions
   • Check content access requirements
   • Ensure proper authentication flow

3. “CORS Error”

   • Verify CORS configuration
   • Check environment-specific settings
   • Ensure proper domain configuration

Debug Mode

For debugging authentication issues, you can:

1. Check browser console for errors
2. Inspect cookies for valid tokens
3. Use browser dev tools to examine network requests
4. Check server logs for authentication events

📞 Support

For authentication issues:

• Auth Gateway: https://auth.8531.ca
• Domain Strategy: Documentation available in .dev/ directory
• Security Issues: Contact system administrator immediately