The highest tagged major version is
README
¶
A comprehensive, framework-agnostic authentication and authorization library for Go.
Note: This project is still a work in progress. Contributions are most welcome!
Table of Contents
Introduction
✨ Overview
GoBetterAuth is a comprehensive, authentication and authorization library/framework for Go applications. It provides secure email/password authentication, social OAuth providers, session management, email verification, password reset, and more, all built with clean architecture principles.
💭 Why GoBetterAuth?
GoBetterAuth is designed to be a comprehensive authentication and authorization solution for Go applications. It simplifies the implementation of common security features while providing a clean and modular architecture. This way developers can focus on building their applications without worrying about the complexities of authentication and the time it takes to implement these features.
Features
- 🔑 Email & Password Authentication – Secure, production-ready authentication with argon2 password hashing
- 🌐 Social OAuth Providers – Google, GitHub, Discord, and extensible generic OAuth2 support
- 🔐 Session Management – Secure, customizable session handling with refresh and expiration controls
- ✉️ Email Verification – Optional, configurable email verification workflow
- 🔄 Password Reset – Secure password reset with customizable email callbacks
- 🏗️ Clean Architecture – Go Clean Architecture: domain, usecase, repository, handler, and infrastructure layers
- 🔌 Plugin System – Extensible plugin architecture for custom business logic and routes
- 💾 Multiple Database Support – SQLite and PostgreSQL adapters, with migration scripts included
- 🛡️ Security First – CSRF protection, secure cookies, rate limiting, and input validation
- ⚡ Rate Limiting – Configurable, per-endpoint rate limiting with memory or database storage
- 🔁 Token Refresh Flow – Automatic token refresh and session extension
- 📦 Minimal Dependencies – Standard library first, production-ready, and framework-agnostic
- 🧩 Comprehensive Configuration – Flexible, type-safe config with sensible defaults and environment variable support
- 🧪 Test Coverage – Unit, integration, and E2E tests reflecting production scenarios
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
Documentation
¶
Index ¶
- func DropDatabase(ctx context.Context, config *domain.Config) error
- func ForceVersion(ctx context.Context, config *domain.Config, version int) error
- func GetMigrationInfo(ctx context.Context, config *domain.Config) (*domain.MigrationInfo, error)
- func GetMigrationVersion(ctx context.Context, config *domain.Config) (uint, bool, error)
- func IsMigrationDirty(ctx context.Context, config *domain.Config) (bool, error)
- func ResetDatabase(ctx context.Context, config *domain.Config) error
- func RunMigrations(ctx context.Context, config *domain.Config) error
- func RunMigrationsDown(ctx context.Context, config *domain.Config) error
- func RunMigrationsSteps(ctx context.Context, config *domain.Config, steps int) error
- type Auth
- func (auth *Auth) AuthMiddleware() *middleware.AuthMiddleware
- func (auth *Auth) CipherManager() *crypto.CipherManager
- func (auth *Auth) Config() *domain.Config
- func (a *Auth) Handler() http.Handler
- func (auth *Auth) OptionalAuthMiddleware() *middleware.OptionalAuthMiddleware
- func (auth *Auth) PasswordHasher() *crypto.Argon2PasswordHasher
- func (auth *Auth) RunMigrations(ctx context.Context) error
- func (auth *Auth) SecretGenerator() *crypto.SecretGenerator
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DropDatabase ¶
DropDatabase drops all database tables (DESTRUCTIVE OPERATION) This is a convenience function for users to drop all tables programmatically WARNING: This operation is irreversible and will delete all data
func ForceVersion ¶
ForceVersion forces the migration version to a specific number This should only be used to fix a dirty database state This is a convenience function for users to force migration version programmatically
func GetMigrationInfo ¶
GetMigrationInfo returns information about migration status This is a convenience function for users to check migration status programmatically
func GetMigrationVersion ¶
GetMigrationVersion returns only the current migration version This is a convenience function for users who only need the version number
func IsMigrationDirty ¶
IsMigrationDirty checks if the database is in a dirty state This is useful for checking if migrations failed and need manual intervention
func ResetDatabase ¶
ResetDatabase drops all tables and re-runs all migrations This is equivalent to running DropDatabase followed by RunMigrations WARNING: This operation is destructive and will delete all data
func RunMigrations ¶
RunMigrations applies all pending migrations to the database This is a convenience function for users to run migrations programmatically
func RunMigrationsDown ¶
RunMigrationsDown rolls back database migrations This is a convenience function for users to rollback migrations programmatically
Types ¶
type Auth ¶
type Auth struct {
// contains filtered or unexported fields
}
func (*Auth) AuthMiddleware ¶
func (auth *Auth) AuthMiddleware() *middleware.AuthMiddleware
AuthMiddleware returns a ready-to-use authentication middleware It validates session tokens and extracts user IDs from requests The middleware requires valid authentication (returns 401 if missing or invalid)
func (*Auth) CipherManager ¶
func (auth *Auth) CipherManager() *crypto.CipherManager
CipherManager returns the cipher manager for encryption and signing
func (*Auth) Handler ¶
Handler returns an http.Handler that implements all authentication endpoints. This handler can be mounted on any HTTP server, including Chi, Echo, and stdlib mux. The handler automatically includes CORS middleware configured with the trusted origins. If secondary storage is configured, it will be used for session caching and rate limiting.
func (*Auth) OptionalAuthMiddleware ¶
func (auth *Auth) OptionalAuthMiddleware() *middleware.OptionalAuthMiddleware
OptionalAuthMiddleware returns a ready-to-use optional authentication middleware It validates session tokens if present, but doesn't require them Requests without tokens or with invalid tokens are still allowed
func (*Auth) PasswordHasher ¶
func (auth *Auth) PasswordHasher() *crypto.Argon2PasswordHasher
PasswordHasher returns the password hasher
func (*Auth) RunMigrations ¶
RunMigrations runs database migrations for the authentication system. This is primarily intended for testing environments where automatic migrations are needed.
func (*Auth) SecretGenerator ¶
func (auth *Auth) SecretGenerator() *crypto.SecretGenerator
SecretGenerator returns the secret generator
Source Files
Directories