Skip to main content

Introducing GoAuth

· 3 min read
GoAuth Team
GoAuth Team
GoAuth Development Team

GoAuth is a modular, framework-agnostic authentication library for Go. It gives you composable modules for building auth systems -- from basic email/password signup to multi-organization setups with 2FA and audit logging.

What GoAuth Provides​

GoAuth ships with 12 modules that you compose via a three-phase lifecycle:

a, _ := auth.New(&config.Config{...})   // 1. Create
a.Use(twofactor.New())                   // 2. Register modules
a.Initialize(context.Background())       // 3. Initialize

Core (auto-registered) handles user registration, login, password reset, email/phone verification, and profile management. You then pick an authentication strategy:

  • Session -- Server-side sessions with a cookie-cache strategy that avoids a DB round-trip on every request.
  • Stateless (default) -- JWT access/refresh token pair with configurable TTLs and refresh token rotation.

Session and stateless are mutually exclusive. If you register neither, stateless is used by default.

Optional modules cover the rest:

  • OAuth -- Social login with Google, GitHub, Microsoft, and Discord (PKCE supported)
  • Two-Factor -- TOTP-based 2FA with encrypted secrets and backup codes
  • Notification -- Email/SMS delivery via pluggable senders (SendGrid, SMTP, Twilio, or custom)
  • Admin -- User CRUD endpoints with admin auth middleware
  • Organization -- Multi-org support with roles and invitations
  • Audit -- Security event logging with configurable retention and cleanup
  • Captcha -- reCAPTCHA v3 and Cloudflare Turnstile
  • CSRF -- Token-based CSRF protection
  • Magic Link -- Passwordless authentication via email

Security Defaults​

GoAuth ships with sensible defaults out of the box:

  • bcrypt password hashing with configurable cost factor
  • HS256 JWT signing with a required 32+ character secret
  • AES-256-GCM encryption for sensitive data (TOTP secrets, OAuth tokens)
  • SHA-256 refresh token hashing in the database
  • Account lockout after 5 failed attempts (15-minute window)
  • Password policy enforcement (min 8, max 128 characters)
  • TOTP code reuse prevention within the validity window

Framework Adapters​

GoAuth includes adapters for 4 Go web frameworks:

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

Event System​

Every auth action emits typed events that you can hook into:

a.On(types.EventAfterSignup, func(ctx context.Context, data interface{}) error {
    user := types.EventDataAs[*types.SignupEventData](data)
    // sync to CRM, send analytics, etc.
    return nil
})

The event bus supports multiple handlers per event, priority ordering, retry policies, and a dead-letter queue for failed handlers. The default backend is an in-memory worker pool (10 workers, 1000 queue); you can provide a custom types.AsyncBackend for external brokers.

Storage​

GoAuth uses GORM under the hood with support for PostgreSQL, MySQL, and SQLite. Storage is type-safe -- Storage.Core(), Storage.Session(), Storage.Stateless() -- with no string-based lookups. An in-memory cache decorator is included, and the storage interface is pluggable for custom backends.

Getting Started​

go get github.com/bete7512/goauth

Check the Quick Start guide to build a working auth system in a few minutes, or browse the Examples for specific use cases.

Follow along on GitHub for updates and to contribute.