go-core

A multi-tenant authentication and authorization module for Go. Built on Gin, PostgreSQL (pgx/SQLC), and Redis, it handles JWT auth, OAuth2 social login, WebAuthn/passkeys, magic links, two-factor authentication, RBAC, an OIDC provider, webhooks, brute-force protection, GeoIP rules, session groups for cross-app SSO, and an embedded HTMX admin GUI. Drop it into your backend and skip building auth from scratch.

Quick Start

package main

import (
	"log"

	"github.com/gin-gonic/gin"

	core "github.com/MrF1ow/go-core"
	"github.com/MrF1ow/go-core/app"
)

func main() {
	cfg := core.DefaultConfig()
	cfg.Database.Host = "localhost"
	cfg.Database.Port = 5432
	cfg.Database.DBName = "myapp"
	cfg.Database.User = "postgres"
	cfg.Database.Password = "secret"
	cfg.JWT.Secret = "your-secret-at-least-32-characters-long"
	cfg.Redis = nil // in-memory; DefaultConfig() otherwise uses localhost:6379 DB 1

	coreApp, err := app.New(cfg)
	if err != nil {
		log.Fatal(err)
	}
	defer coreApp.Close()

	r := gin.Default()
	coreApp.RegisterRoutes(r)
	r.Run(":8080")
}

That's it. You get registration, login, token refresh, password reset, email verification, 2FA, social login, and more out of the box.

Public API

Function	Description
app.New(cfg)	Validates config, connects to Postgres, initializes all services
app.NewWithDB(cfg, pool)	Same as New but reuses an existing *pgxpool.Pool
app.RegisterRoutes(r)	Mounts all routes onto a Gin engine
app.AuthMiddleware()	Returns a gin.HandlerFunc for protecting your own routes
app.Close()	Shuts down background services and connection pool

Required Config

These must be set or app.New() returns an error:

Field	Description
Database.Host	PostgreSQL host
Database.Port	PostgreSQL port (default: 5432)
Database.DBName	Database name
Database.User	Database user
Database.Password	Database password (not validated, but you need it)
JWT.Secret	Signing key for all access and refresh tokens. Minimum 32 characters.

Optional Config

Everything below is off or defaulted until you configure it. DefaultConfig() gives you sensible CORS defaults and reasonable token lifetimes.

Field	What it does	When unset
Redis	Redis connection for token blacklisting and sessions	DefaultConfig() uses localhost:6379 DB 1. app.New() pings it and fails if Redis is down. Set cfg.Redis = nil for in-memory cache.
Email	SMTP config for sending emails	Nil = email sending disabled. Magic links, 2FA email codes, and verification emails won't work.
CORS	Cross-origin settings	Sensible defaults via DefaultConfig(). Override if needed.
OIDC	OpenID Connect provider config	Disabled.
WebAuthn	Passkey and biometric authentication	Disabled unless you set RPID. DefaultConfig() sets RPID to localhost.
SMS	2FA via Twilio	Disabled.
Admin	Admin GUI settings, API key, and branding	Disabled.
Social	OAuth2 social login (Google, Facebook, GitHub)	Disabled.
GeoIP	IP-based access rules, requires a MaxMind database file	Disabled.
Session	Session groups, trusted devices, cross-app SSO settings	Defaults to single-app mode.
MultiTenant	Enables multi-app mode with X-App-ID header	False. Single-app mode.
PublicURL	Base URL for API links in emails and redirects	DefaultConfig() sets http://localhost:8080.
FrontendURL	Frontend app URL for redirect targets	DefaultConfig() sets http://localhost:5173.
AppName	Application name used in emails and admin GUI	Empty.
Port	Server port for the reference cmd/api implementation	DefaultConfig() sets 8080.
GinMode	Gin framework mode (debug, release, test)	DefaultConfig() sets debug.

Features

• JWT authentication (access + refresh tokens)
• Registration, login, password reset, email verification
• Magic link authentication
• OAuth2 social login (Google, Facebook, GitHub)
• WebAuthn / passkeys
• Two-factor auth (TOTP, SMS, email, passkey)
• Role-based access control (RBAC)
• Multi-tenant with per-app configuration
• HTMX admin GUI (embedded, no extra files needed)
• OpenID Connect provider (auth code + PKCE)
• Webhooks
• Brute-force protection and account lockout
• GeoIP-based access rules
• Session groups (cross-app SSO)
• Activity logging

Workers authenticate to /app/:id with X-App-API-Key and X-App-ID. IP rules for that app apply to those routes.

Running the Example

Check out examples/basic/main.go for a working setup. You'll need PostgreSQL running with migrations applied.

# Start dependencies
make docker-dev
make migrate-up

# Run the example
go run ./examples/basic

make docker-dev starts PostgreSQL and Redis. make migrate-up applies the embedded schema. make dev or go run ./examples/basic runs the API on the host.

Documentation

Human-facing docs live in docs/. Config fields are in docs/configuration.md. The cmd/api env mapping is docs/guides/ENV_VARIABLES.md.

Development

make dev          # Hot reload dev server
make test         # Run all tests
make fmt          # Format code
make lint         # golangci-lint
make security     # gosec + govulncheck scans
make ci           # Run full CI pipeline (fmt, lint, test, security, build)
make build-prod   # Production binary
make setup-admin  # Create admin account for Admin GUI
make swag-init    # Regenerate Swagger docs after API changes

Claude Code Skills

This project includes Claude Code skills for AI-assisted development. They live in .claude/skills/go-core/ and cover:

• Hub — routes you to living docs/ and the remaining skill refs
• Auth flows — registration, login, token lifecycle, 2FA, OAuth2
• Email system — email templates and sending logic
• Security — brute-force protection, GeoIP, CSRF, rate limiting
• New endpoint — guide for adding new API endpoints (internal/coreapp)
• Integration — how to consume the module in your app
• Commits — commit message conventions and scopes

Project structure, schema, routes, and admin GUI live in docs/ and in code (internal/schema.sql, RegisterRoutes). Invoke the hub skill with /go-core in Claude Code.

Credits

Originally forked from gjovanovicst/golang-auth-api. Significantly reworked into a consumable Go module — migrated from GORM to pgx/SQLC, embedded all assets, added a public API, and cleaned up the architecture.

License

MIT.