Introduction
This page introduces Behemoth, a plugin-based authentication library for Go.
Behemoth gives your application sign-up, sign-in, and session management on the database and HTTP framework you already use.
What is Behemoth? #
Behemoth is a library, not a hosted service. You add it to your Go application, and it mounts its routes on your router and stores its data in your database. Authentication methods are plugins. A built-in migration engine and transaction management keep your schema and your writes consistent.
Behemoth is built around plugins. Email and password sign-in is a plugin, and so is any method you add yourself. Plugins can declare tables, hooks, tokens, and rate limits.
Features #
Behemoth includes the following features:
- Plugin system: Add authentication methods and behavior as plugins, with declared dependencies and ordering.
- Email and password: Sign up, sign in, sign out, and reset a forgotten password with the built-in
emailpasswordplugin. - More sign-in methods: Add sign-in by magic link, username, phone number, or an OAuth provider, and confirm email addresses, with plugins.
- Sessions and tokens: Manage sessions with rolling expiry, concurrency limits, and IP address and user agent capture, deliver the token by cookie, header, or body, and issue single-use tokens.
- Hooks: Run your code before a data write or flow such as sign-up, after it, or when it fails.
- Migrations: Generate migration files from the schema your plugins declare, with the
behemothcommand. - Mail and SMS: Hand messages to the sender you provide, so you keep your own delivery service and templates.
- Telemetry: Get logs, audit events, metrics, and traces for sign-in and data writes.
- Database support: Use PostgreSQL, MySQL, SQLite, SQL Server, MongoDB, or the Bun and GORM adapters.
- Framework support: Use router adapters for
net/http, Gin, Echo, chi, and Fiber.
Why Behemoth? #
Authentication is a critical part of an application and is difficult to implement correctly. Behemoth handles the security-sensitive parts and leaves you in control of your data model and your routes.
The following table compares Behemoth with a custom implementation:
| Feature | Behemoth | DIY |
|---|---|---|
| Password hashing | Built-in | Manual |
| Session storage | Only token hashes stored | Custom implementation |
| Sensitive values at rest | Sealed by the store | Often plaintext |
| Schema changes | Generated migrations | Hand-written |
| Extending sign-up | Hooks and plugins | Edit your own handlers |
Framework support #
Behemoth mounts its routes on your application's router through an adapter. The following frameworks are supported:
net/http- Gin
- Echo
- chi
- Fiber
- Any other framework, if you implement the
FrameworkDriverinterface
Quick example #
The following example adds email and password authentication to a Gin application:
import (
"github.com/go-behemoth/behemoth/core"
"github.com/go-behemoth/behemoth/engine"
"github.com/go-behemoth/behemoth/plugins/emailpassword"
)
// 1. Declare the plugins and build the application.
plugin := emailpassword.New(emailpassword.Options{})
app, err := engine.Prepare(
[]core.Plugin{plugin},
engine.PrepareConfig{},
)
if err != nil {
log.Fatal(err)
}
// 2. Boot it against your database and router.
ac, err := engine.Boot(
ctx,
app,
db,
engine.BootConfig{
// Crypto settings omitted here
HTTP: ginadapter.New(router),
},
)
if err != nil {
log.Fatal(err)
}
// POST /api/auth/sign-up/email and
// POST /api/auth/sign-in/email are now available.The examples/init directory in the repository shows a complete application with PostgreSQL, Gin, migrations, custom hooks and a custom plugin.
Next steps #
To start using Behemoth, read the following guides:
- Installation: Install Behemoth in your project.
- Quick Start: Build your first authentication flow.
- Sessions: Learn how session management works.
- Email and password: Configure the built-in plugin and password reset.
- Hooks: Run your code at fixed points.
- How Behemoth fits together: See how plugins, hooks, sessions, and the database work together.