gitea-mirror/docs/BETTER_AUTH_MIGRATION.md

Better Auth Migration Guide

This document describes the migration from the legacy authentication system to Better Auth.

Overview

Gitea Mirror has been migrated to use Better Auth, a modern authentication library that provides:

• Built-in support for email/password authentication
• Session management with secure cookies
• Database adapter with Drizzle ORM
• Ready for OAuth2, OIDC, and SSO integrations
• Type-safe authentication throughout the application

Key Changes

1. Database Schema

New tables added:

• sessions - User session management
• accounts - Authentication providers (credentials, OAuth, etc.)
• verification_tokens - Email verification and password reset tokens

Modified tables:

• users - Added emailVerified field

2. Authentication Flow

Login:

• Users now log in with email instead of username
• Endpoint: /api/auth/sign-in/email
• Session cookies are automatically managed

Registration:

• Users register with username, email, and password
• Username is stored as an additional field
• Endpoint: /api/auth/sign-up/email

3. API Routes

All auth routes are now handled by Better Auth's catch-all handler:

• /api/auth/[...all].ts handles all authentication endpoints

Legacy routes have been backed up to /src/pages/api/auth/legacy-backup/

4. Session Management

Sessions are now managed by Better Auth:

• Middleware automatically populates context.locals.user and context.locals.session
• Use useAuth() hook in React components for client-side auth
• Sessions expire after 30 days by default

Future OIDC/SSO Configuration

The project is now ready for OIDC and SSO integrations. To enable:

1. Enable SSO Plugin

// src/lib/auth.ts
import { sso } from "better-auth/plugins/sso";

export const auth = betterAuth({
  // ... existing config
  plugins: [
    sso({
      provisionUser: async (data) => {
        // Custom user provisioning logic
        return data;
      },
    }),
  ],
});

2. Register OIDC Providers

// Example: Register an OIDC provider
await authClient.sso.register({
  issuer: "https://idp.example.com",
  domain: "example.com",
  clientId: "your-client-id",
  clientSecret: "your-client-secret",
  providerId: "example-provider",
});

3. Enable OIDC Provider Mode

To make Gitea Mirror act as an OIDC provider:

// src/lib/auth.ts
import { oidcProvider } from "better-auth/plugins/oidc";

export const auth = betterAuth({
  // ... existing config
  plugins: [
    oidcProvider({
      loginPage: "/signin",
      consentPage: "/oauth/consent",
      metadata: {
        issuer: process.env.BETTER_AUTH_URL || "http://localhost:3000",
      },
    }),
  ],
});

4. Database Migration for SSO

When enabling SSO/OIDC, run migrations to add required tables:

# Generate the schema
bun drizzle-kit generate

# Apply the migration
bun drizzle-kit migrate

New tables that will be added:

• sso_providers - SSO provider configurations
• oauth_applications - OAuth2 client applications
• oauth_access_tokens - OAuth2 access tokens
• oauth_consents - User consent records

Environment Variables

Required environment variables:

# Better Auth configuration
BETTER_AUTH_SECRET=your-secret-key
BETTER_AUTH_URL=http://localhost:3000

# Legacy (kept for compatibility)
JWT_SECRET=your-secret-key

Migration Script

To migrate existing users to Better Auth:

bun run migrate:better-auth

This script:

1. Creates credential accounts for existing users
2. Moves password hashes to the accounts table
3. Preserves user creation dates

Troubleshooting

Login Issues

• Ensure users log in with email, not username
• Check that BETTER_AUTH_SECRET is set
• Verify database migrations have been applied

Session Issues

• Clear browser cookies if experiencing session problems
• Check middleware is properly configured
• Ensure auth routes are accessible at /api/auth/*

Development Tips

• Use bun db:studio to inspect database tables
• Check /api/auth/session to verify current session
• Enable debug logging in Better Auth for troubleshooting

Resources

• Better Auth Documentation
• Better Auth Astro Integration
• Better Auth Plugins