gobetterauth

README

---

Table of Contents

1. Introduction
2. Features
3. Docs
4. Contributing

---

Introduction

✨ Overview

GoBetterAuth is an open-source authentication solution that scales with you. Embed it as a library in your Go app, or run it as a standalone auth server for any language or framework. It provides secure email/password authentication, session management, email verification, password reset, and more, all built with clean architecture. GoBetterAuth is flexible enough to integrate with any technology stack. It streamlines the implementation of essential security features through a clean, modular architecture, allowing developers to concentrate on building their applications without the overhead of managing authentication complexities.

---

Features

• 🔑 Email & Password – Secure, production-ready authentication with argon2 password hashing. Includes Email Verification, Password Reset and Change Email flows.
• 🌐 Social OAuth Providers – Google, GitHub, Discord and more coming soon.
• 💾 Multiple Database Support – SQLite, PostgreSQL, MySQL adapters and more coming soon, with migration scripts included.
• 🗄️ Secondary Storage – Supports in-memory/database storage and a custom interface to implement Redis and other key-value stores. Use secondary storage to manage session data, rate limiting counters, and other high-frequency records. This enables offloading intensive data to high-performance storage solutions or RAM for optimal scalability and speed.
• 📦 Minimal Dependencies – Standard library first, production-ready, and framework-agnostic.
• 🧩 Comprehensive Configuration – Flexible, type-safe config with sensible defaults and environment variable support.
• ⚙️ Flexible Configuration – Whether you're embedding as a library or running as a server, GoBetterAuth gives you full control over your authentication logic.
• 🛡️ Enhanced Security – CSRF protection.
• ⚡ Rate Limiting – Configurable rate limiting with secondary storage.
• 🪝 Hooks System – Powerful hooks for deep customization: Endpoint Hooks allow you to modify requests and responses in the lifecycle. Database Hooks let you tap into DB events like BeforeCreate and AfterCreate on entities, with support for custom hooks in plugins. Event Hooks run after key actions, enabling event-driven workflows. Webhooks are also supported, so you can trigger external services when authentication events occur.
• 📨 Event Bus – Built-in event bus enables event-driven architecture, allowing you to publish and subscribe to authentication and authorization events for seamless integration with external systems and custom workflows.
• 🔌 Plugin System – Extensible plugin architecture for custom business logic and routes. Including flexible plugin interface to implement all kinds of plugins.

---

Docs

For more info and a full guide on how to use this library, check out the Docs.

---

Contributing

Your contributions are welcome! Here's how you can get involved:

• If you find a bug, please submit an issue.
• Set up your development environment by following our Contribution Guide.
• Contribute code by making a pull request to enhance features, improve user experience, or fix issues.

---

Support & Community

• Discord Server

---

Documentation

Index

• func InitApi(config *models.Config, authService *internalauth.Service) models.AuthApi
• func InitConfigManager(config *models.Config) (models.ConfigManager, error)
• func InitDatabase(config *models.Config) (*gorm.DB, error)
• func InitDefaults(config *models.Config)
• func InitEventBus(config *models.Config) (models.EventBus, error)
• func InitPluginRegistry(config *models.Config, api models.AuthApi, eventBus models.EventBus, ...) models.PluginRegistry
• func InitSecondaryStorage(config *models.Config) error
• func InitServices(config *models.Config, configManager models.ConfigManager, ...) *internalauth.Service
• func InitWebhookExecutor(config *models.Config) models.WebhookExecutor
• func RunCoreMigrations(db *gorm.DB)
• func RunPluginMigrations(pluginRegistry models.PluginRegistry)
• type Auth
  • func New(baseConfig *models.Config) *Auth
  • func (auth *Auth) AuthMiddleware() func(http.Handler) http.Handler
  • func (auth *Auth) CSRFMiddleware() func(http.Handler) http.Handler
  • func (auth *Auth) ClosePlugins() error
  • func (auth *Auth) CorsAuthMiddleware() func(http.Handler) http.Handler
  • func (auth *Auth) DropMigrations()
  • func (auth *Auth) EndpointHooksMiddleware() func(http.Handler) http.Handler
  • func (auth *Auth) GetUserIDFromContext(ctx context.Context) (string, bool)
  • func (auth *Auth) GetUserIDFromRequest(req *http.Request) (string, bool)
  • func (auth *Auth) Handler() http.Handler
  • func (auth *Auth) OptionalAuthMiddleware() func(http.Handler) http.Handler
  • func (auth *Auth) RateLimitMiddleware() func(http.Handler) http.Handler
  • func (auth *Auth) RedirectAuthMiddleware(redirectURL string, status int) func(http.Handler) http.Handler
  • func (auth *Auth) RegisterRoute(route models.CustomRoute)
  • func (auth *Auth) RunMigrations()

Functions

func InitApi

func InitApi(config *models.Config, authService *internalauth.Service) models.AuthApi

func InitConfigManager

func InitConfigManager(config *models.Config) (models.ConfigManager, error)

InitConfigManager initializes the appropriate config manager based on mode

func InitDatabase

func InitDatabase(config *models.Config) (*gorm.DB, error)

InitDatabase creates a GORM DB connection based on provider.

func InitDefaults

func InitDefaults(config *models.Config)

func InitEventBus

func InitEventBus(config *models.Config) (models.EventBus, error)

InitEventBus initializes the event bus based on configuration

func InitPluginRegistry

func InitPluginRegistry(config *models.Config, api models.AuthApi, eventBus models.EventBus, apiMiddleware *models.ApiMiddleware, webhookExecutor models.WebhookExecutor) models.PluginRegistry

func InitSecondaryStorage

func InitSecondaryStorage(config *models.Config) error

InitSecondaryStorage wires up the secondary storage implementation based on type

func InitServices

func InitServices(config *models.Config, configManager models.ConfigManager, eventBus models.EventBus, pluginRateLimits []models.PluginRateLimit) *internalauth.Service

func InitWebhookExecutor

func InitWebhookExecutor(config *models.Config) models.WebhookExecutor

InitWebhookExecutor creates and returns a WebhookExecutor

func RunCoreMigrations

func RunCoreMigrations(db *gorm.DB)

func RunPluginMigrations

func RunPluginMigrations(pluginRegistry models.PluginRegistry)

Types

type Auth

type Auth struct {
	Config *models.Config

	Service *auth.Service
	Api     models.AuthApi

	EventBus models.EventBus

	OnRestartRequired func() error
	// contains filtered or unexported fields
}

func New

func New(baseConfig *models.Config) *Auth

New creates a new Auth instance using the provided config and options.

func (*Auth) AuthMiddleware

func (auth *Auth) AuthMiddleware() func(http.Handler) http.Handler

func (*Auth) CSRFMiddleware

func (auth *Auth) CSRFMiddleware() func(http.Handler) http.Handler

func (*Auth) ClosePlugins

func (auth *Auth) ClosePlugins() error

ClosePlugins calls Close for all registered plugins

func (*Auth) CorsAuthMiddleware

func (auth *Auth) CorsAuthMiddleware() func(http.Handler) http.Handler

func (*Auth) DropMigrations

func (auth *Auth) DropMigrations()

DropMigrations is a helper function to drop all database tables related to core and plugins. Use with caution as this will delete all data in those tables.

func (*Auth) EndpointHooksMiddleware

func (auth *Auth) EndpointHooksMiddleware() func(http.Handler) http.Handler

func (*Auth) GetUserIDFromContext

func (auth *Auth) GetUserIDFromContext(ctx context.Context) (string, bool)

func (*Auth) GetUserIDFromRequest

func (auth *Auth) GetUserIDFromRequest(req *http.Request) (string, bool)

func (*Auth) Handler

func (auth *Auth) Handler() http.Handler

Handler sets up all routes and returns the final http.Handler

func (*Auth) OptionalAuthMiddleware

func (auth *Auth) OptionalAuthMiddleware() func(http.Handler) http.Handler

func (*Auth) RateLimitMiddleware

func (auth *Auth) RateLimitMiddleware() func(http.Handler) http.Handler

func (*Auth) RedirectAuthMiddleware

func (auth *Auth) RedirectAuthMiddleware(redirectURL string, status int) func(http.Handler) http.Handler

func (*Auth) RegisterRoute

func (auth *Auth) RegisterRoute(route models.CustomRoute)

func (*Auth) RunMigrations

func (auth *Auth) RunMigrations()

RunMigrations is a helper function to run all necessary database migrations for core and plugins manually. This is already ran automatically during Auth initialization, so this function is only needed if you want to run migrations manually for some reason.