OAuth Provider Implementation

This document describes how to implement third-party OAuth providers for user authentication in DeployStack. The system currently supports GitHub OAuth as a reference implementation, but the architecture is designed to easily accommodate additional providers like Google, Microsoft, GitLab, and others.

For general authentication architecture, see Backend Authentication System. For OAuth2 server implementation (API access), see OAuth2 Server Implementation.

Overview

OAuth provider integration allows users to authenticate using their existing accounts from third-party services. This provides a seamless login experience without requiring users to create and manage separate DeployStack credentials.

Architecture

The OAuth provider system is built on:

Arctic - OAuth 2.0 client library supporting multiple providers
Global Settings - Database-driven configuration for each provider
Modular Routes - Separate route files for each provider
Unified Session Management - Integration with Lucia authentication
Account Linking - Automatic linking based on email addresses

File Structure

OAuth providers follow a consistent file organization pattern:

services/backend/src/
├── routes/auth/
│   ├── github.ts           # GitHub OAuth routes
│   ├── githubStatus.ts     # GitHub status endpoint
│   ├── [provider].ts       # New provider routes
│   └── [provider]Status.ts # New provider status
├── global-settings/
│   ├── github-oauth.ts     # GitHub settings
│   └── [provider]-oauth.ts # New provider settings
├── db/
│   └── schema.sqlite.ts    # User table with provider IDs
└── lib/
    └── lucia.ts            # Session management

Current Implementation: GitHub

GitHub OAuth serves as the reference implementation demonstrating the complete flow:

OAuth Flow

Login Initiation (/api/auth/github/login)
- Validates login is enabled globally
- Checks provider configuration
- Generates CSRF state parameter
- Redirects to GitHub authorization
User Authorization (at GitHub)
- User reviews requested permissions
- Approves or denies access
- Redirects back to callback URL
Callback Processing (/api/auth/github/callback)
- Validates state parameter
- Exchanges code for access token
- Fetches user profile information
- Creates or links user account
- Establishes session
Status Endpoint (/api/auth/github/status)
- Reports if provider is enabled
- Indicates configuration status
- Used by frontend for UI decisions

User Provisioning

When a user authenticates via OAuth:

New Users: Account created with provider profile data
Existing Users: Account linked if email matches
Role Assignment: Always global_user (never admin)
Team Creation: Default team created automatically
Email Trust: Provider emails considered verified

Security Features

State Parameter: CSRF protection
First User Protection: Must use email registration
Secure Cookies: httpOnly, secure in production
Minimal Scopes: Only request necessary permissions

Adding a New OAuth Provider

Follow these steps to add support for a new OAuth provider:

Step 1: Verify Arctic Support

Check if Arctic supports your provider:

# Arctic supports many providers out of the box
# See: https://arctic.js.org/providers

Supported providers include:

Google
Microsoft/Azure AD
GitLab
Discord
Apple
And many more...

Step 2: Create Global Settings

Create settings file at src/global-settings/[provider]-oauth.ts:

// Example structure (not actual code to avoid outdating)
// Define settings for:
// - enabled (boolean)
// - clientId (string)
// - clientSecret (string, encrypted)
// - callbackUrl (string)
// - scope (string)

Key considerations:

Mark clientSecret as is_encrypted: true
Set appropriate default scopes
Group settings under 'auth' category
Add to global settings index

Step 3: Update Database Schema

Add provider ID field to authUser table:

// In src/db/schema.sqlite.ts
// Add field like:
// google_id: text('google_id').unique()
// microsoft_id: text('microsoft_id').unique()

Generate migration after schema update:

npm run db:generate

Step 4: Implement OAuth Routes

Create route files following the pattern:

Implements /api/auth/[provider]/login:

Check if login and provider are enabled
Generate state for CSRF protection
Create authorization URL with Arctic
Store state in secure cookie
Redirect to provider

Callback Route (`src/routes/auth/[provider].ts`)

Implements /api/auth/[provider]/callback:

Validate state parameter
Exchange code for tokens
Fetch user information
Handle user creation/linking
Create session
Redirect to frontend

Status Route (`src/routes/auth/[provider]Status.ts`)

Implements /api/auth/[provider]/status:

Check if provider is enabled
Verify configuration is complete
Return status for frontend

Step 5: Register Routes

Add routes to authentication router:

// In src/routes/auth/index.ts
// Import and register:
// await fastify.register([provider]AuthRoutes, { prefix: '/[provider]' })
// await fastify.register([provider]StatusRoutes, { prefix: '/[provider]' })