GoAuth Documentation

GoAuth is a modular, framework-agnostic authentication library for Go. Compose the auth features you need — core, session or stateless JWT, 2FA, OAuth, notifications, admin — and plug them into any web framework.

Getting Started

• Introduction — What GoAuth is and how it works
• Installation — Install and set up GoAuth
• Quick Start — Build a working auth system

Modules

Core (auto-registered) — User registration, profile management, password flows, email/phone verification.

Authentication (pick one):

• Session — Server-side sessions with cookie strategies
• Stateless — JWT access + refresh tokens (default)

Optional:

• Notification — Email/SMS delivery
• Two-Factor — TOTP-based 2FA with backup codes
• OAuth — Social login (Google, GitHub, Facebook, Microsoft, Apple, Discord)
• Admin — User CRUD with admin middleware
• Audit — Security event logging
• Captcha — reCAPTCHA v3, Cloudflare Turnstile
• CSRF — Token-based CSRF protection
• Magic Link — Passwordless auth via email

Architecture

┌──────────────────────────────────────┐
│         Your Application             │
└──────────────┬───────────────────────┘
               │
               ▼
┌──────────────────────────────────────┐
│  GoAuth Instance                     │
│  ┌────────────────────────────────┐  │
│  │    Core Module (Auto)          │  │
│  │  Signup, Profile, Passwords,   │  │
│  │  Verification                  │  │
│  └────────────────────────────────┘  │
│                                      │
│  Auth Strategy (pick one):           │
│  ┌─────────────┐ ┌──────────────┐   │
│  │   Session   │ │  Stateless   │   │
│  └─────────────┘ └──────────────┘   │
│                                      │
│  Optional Modules:                   │
│  ┌─────────────┐ ┌──────────────┐   │
│  │Notification │ │  Two-Factor  │   │
│  └─────────────┘ └──────────────┘   │
│  ┌─────────────┐ ┌──────────────┐   │
│  │   OAuth     │ │   Captcha    │   │
│  └─────────────┘ └──────────────┘   │
│  ┌─────────────┐ ┌──────────────┐   │
│  │   Admin     │ │    CSRF      │   │
│  └─────────────┘ └──────────────┘   │
│  ┌─────────────┐ ┌──────────────┐   │
│  │   Audit     │ │ Magic Link   │   │
│  └─────────────┘ └──────────────┘   │
└──────────────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────┐
│  Storage (GORM: Postgres/MySQL/      │
│  SQLite, or custom types.Storage)    │
└──────────────────────────────────────┘

Three-Phase Pattern

// 1. Create
a, _ := auth.New(&config.Config{...})

// 2. Register optional modules
a.Use(twofactor.New(&twofactor.TwoFactorConfig{...}))

// 3. Initialize
a.Initialize(context.Background())

// Serve with adapter
mux := http.NewServeMux()
stdhttp.Register(mux, a)

Framework Integration

Built-in adapters in pkg/adapters/:

stdhttp.Register(mux, a)         // net/http
ginadapter.Register(router, a)   // Gin
chiadapter.Register(router, a)   // Chi
fiberadapter.Register(app, a)    // Fiber

Reference

• API Endpoints — REST API documentation
• Core Module — Core module details
• Notification Module — Email/SMS integration