Behemoth is a plugin-based authentication library for Go. You choose the plugins and the database, and Behemoth sets up the tables, routes, sessions, hooks, and telemetry around them.
Behemoth is at v0.x, and the API can change between minor versions until v1.0.0. The changelog lists every change. Pin the version in your go.mod and read the changelog before you upgrade.
Website · Guides · Reference · Go package documentation
| Plugin | What it does |
|---|---|
emailpassword |
Sign-up, sign-in, sign-out, and password reset |
username |
Unique usernames and sign-in by username, on top of emailpassword |
phonenumber |
A phone number confirmed by one-time code, sign-in by code or password, and password reset by code |
magiclink |
Sign-in by a link sent to the user's email |
emailverification |
Confirms a user's email address by link |
oauth |
Sign-in through OAuth 2.0 or OpenID Connect, such as Google or GitHub, linking provider accounts to a user, and stored provider tokens |
twofactor |
A second factor at sign-in: an authenticator app, a code by email or text message, and recovery codes. Experimental. |
Around the plugins:
- Migrations. Behemoth builds a migration from the tables your plugins and your own schema declare, and writes it to a folder for you to review. The
behemothcommand line does it from your application's directory. - Hooks. Run your code before or after a user is written, or around a whole flow such as sign-up. A handler can change data, stop an operation, or react afterwards.
- Sessions and tokens. Sessions live in your database or a key-value store, and travel as a cookie or a header.
- Router adapters. Mount the routes on
net/http, Gin, Echo, chi, or Fiber. - Telemetry. Logs, audit events, metrics, and traces, with an OpenTelemetry adapter.
- Rate limiting and Argon2id password hashing, on by default.
Behemoth needs Go 1.26 or later.
go get github.com/go-behemoth/behemothDatabase and router adapters are separate modules, so you download only what you use:
go get github.com/go-behemoth/behemoth/storage/adapters/postgres
go get github.com/go-behemoth/behemoth/plugins/adapters/ginThe adapter for the standard library's http.ServeMux needs no dependency of its own, so it comes with the core module: import github.com/go-behemoth/behemoth/plugins/adapters/nethttp.
Use one version for every Behemoth module in your go.mod.
This quick start builds a server with email and password sign-in on PostgreSQL and net/http. You need Go 1.26 or later, Docker, and openssl.
Setup has two steps. Prepare collects the declarations of your plugins and schema, with no database. Boot connects them to a database and a router.
-
Start PostgreSQL, and set the two variables the application reads:
docker run -d --name behemoth-db -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=behemoth -p 5432:5432 postgres:17 export DATABASE_URL='postgres://postgres:postgres@localhost:5432/behemoth?sslmode=disable' export BEHEMOTH_SECRET=$(openssl rand -hex 32)
BEHEMOTH_SECRETis the master secret that every key is derived from. Keep the same value between runs, or sessions stop working. If the server stops withneed >= 32, the variable is not set in that terminal. -
Create a module:
mkdir myapp && cd myapp go mod init example.com/myapp
-
Put the setup in
auth/behemoth.go. The server and thebehemothcommand line both start from it, so the tables a migration creates are the tables the server reads:// Package auth holds the quickstart's Behemoth setup. The server and the // behemoth command line both start from Prepare, so the tables a migration // creates are the tables the server reads. package auth import ( "context" "database/sql" "os" "github.com/go-behemoth/behemoth/core" "github.com/go-behemoth/behemoth/engine" "github.com/go-behemoth/behemoth/migration" "github.com/go-behemoth/behemoth/plugins/emailpassword" "github.com/go-behemoth/behemoth/storage/adapters/postgres" _ "github.com/lib/pq" ) // Prepare returns what the application declares. It opens no connection. func Prepare() (*engine.PreparedApp, error) { plugins := []core.Plugin{emailpassword.New(emailpassword.Options{})} return engine.Prepare(plugins, engine.PrepareConfig{ Migration: migration.MigrationConfig{ FolderPath: "migrations", Path: migration.PathManaged, // Behemoth applies the migrations itself }, }) } // MigrationBackend opens the database the command line compares with. func MigrationBackend(ctx context.Context, app *engine.PreparedApp) (migration.Backend, error) { db, err := OpenDB(ctx) if err != nil { return migration.Backend{}, err } return postgres.MigrationBackend(db, app.Resolver), nil } // OpenDB opens the PostgreSQL database that DATABASE_URL names. func OpenDB(ctx context.Context) (*sql.DB, error) { db, err := sql.Open("postgres", os.Getenv("DATABASE_URL")) if err != nil { return nil, err } if err := db.PingContext(ctx); err != nil { db.Close() return nil, err } return db, nil }
-
Write the server in
main.go:// Command quickstart is the smallest Behemoth application: email and // password sign-up and sign-in on PostgreSQL and net/http. package main import ( "context" "log" "net/http" "os" "time" "github.com/go-behemoth/behemoth/core" "github.com/go-behemoth/behemoth/crypto" "github.com/go-behemoth/behemoth/engine" "github.com/go-behemoth/behemoth/httpapi" "github.com/go-behemoth/behemoth/plugins/adapters/nethttp" "github.com/go-behemoth/behemoth/storage/adapters/postgres" "example.com/myapp/auth" ) func main() { ctx := context.Background() // 1. Declarations: plugins and schema. No database yet. app, err := auth.Prepare() if err != nil { log.Fatal(err) } // 2. Storage, bound to the resolver that Prepare derived. sqlDB, err := auth.OpenDB(ctx) if err != nil { log.Fatal(err) } defer sqlDB.Close() db := postgres.NewPostgresAdapter(sqlDB, app.Resolver) // 3. Runtime: sessions and the routes, on your own mux. mux := http.NewServeMux() _, err = engine.Boot(ctx, app, db, engine.BootConfig{ Crypto: crypto.Config{ // The master secret: 64 hex characters, from `openssl rand -hex 32`. Secrets: crypto.StaticSecretSource{ Secrets: map[int]string{1: os.Getenv("BEHEMOTH_SECRET")}, Current: 1, }, }, HTTP: nethttp.New(mux), Session: core.SessionConfig{ExpiresIn: 24 * time.Hour}, // The session token travels in a header, which curl shows. Router: httpapi.RouterConfig{ Carrier: httpapi.TokenCarrierConfig{Delivery: httpapi.DeliveryHeader}, }, }) if err != nil { log.Fatal(err) } log.Fatal(http.ListenAndServe(":8080", mux)) }
-
Download the modules the code imports, install the command line, and create the tables.
generatewrites the first migration to./migrations, andmigrateapplies it:go mod tidy go install github.com/go-behemoth/behemoth/cmd/behemoth@latest behemoth generate -confirm behemoth migrate -confirm
-
Run the server, and in another terminal sign up and sign in:
go run .curl -X POST localhost:8080/api/auth/sign-up/email \ -d '{"email":"ada@example.com","password":"correct horse battery"}' curl -i -X POST localhost:8080/api/auth/sign-in/email \ -d '{"email":"ada@example.com","password":"correct horse battery"}'
The sign-up answers
201 Createdwith the new user. The sign-in answers200 OKand carries the session token in theSet-Auth-Tokenheader. A client sends it back asAuthorization: Bearer TOKEN. Without theRoutersetting inmain.go, the token travels in a cookie. -
Stop PostgreSQL when you are done:
docker rm -f behemoth-db.
To protect your own routes and read who is signed in, see Sessions. To call the same flows from code, without a router, see Email and password.
The examples directory holds applications you can run:
examples/quickstartis the quick start above.examples/cliis a small application on PostgreSQL andnet/httpwhose migrations thebehemothcommand line writes. Its README covers Docker, schema changes, and answering a question. It runs withdocker compose up --build.examples/initis a complete application on PostgreSQL and Gin. It shows migrations, a custom plugin, hooks, telemetry with OpenTelemetry, and sign-in with GitHub, Google, or another OpenID Connect provider.
| Kind | Options |
|---|---|
database/sql |
PostgreSQL, MySQL, SQLite, SQL Server |
| Document | MongoDB |
| ORM | Bun, GORM |
| Key-value (sessions, rate limits) | Redis |
Supported databases lists the releases of each database that Behemoth supports and tests on.
Migrations can be generated for PostgreSQL, MySQL, SQLite, and SQL Server. MongoDB has no migrations: the adapter creates the declared indexes (EnsureIndexes), and Boot checks them.
The guides and the reference are on the website. The reference pages are built from the pages below, which also read well on GitHub.
| Page | Covers |
|---|---|
| Email and password | The plugin's options, routes, and hook points |
| Username | Usernames on top of email and password: the rules, sign-up, sign-in by username, and rate limits |
| Phone number | Confirming a number by one-time code, sign-in by code or password, password reset by code, and rate limits |
| SMS and one-time codes | The SMS sender plugins use, and the code manager |
| Magic link | Sign-in by emailed link: setup, sending the link, routes, redirects, and rate limits |
| Two-factor authentication | A second factor at sign-in: TOTP, codes by email or SMS, recovery codes, the lock, routes, and rate limits |
| OAuth | Sign-in through an OAuth 2.0 or OpenID Connect provider: providers, the callback page, linking provider accounts, the provider's tokens, routes, and rate limits |
| Email verification | Confirming a user's address: when a link is sent, routes, requiring a verified email, and changing an address safely |
| The mail sender plugins use, and waiting or background sends | |
| Router adapters | Mounting the routes on net/http, Gin, Echo, chi, or Fiber, and what is specific to each |
| Callers and permissions | Who a call runs for: reading the caller, naming your own code, authenticating another transport, and the permissions flows require |
| Sessions | Session settings, how the token travels (cookie, header, body), the sign-in response, and protecting your own routes |
| Session tokens | Short-lived JWTs that tell another service who a request is from, and the published keys it checks them with |
| JWT verification | Checking a JWT signed with an asymmetric key, such as a session token in another Go service: the checks, the key set cache, and the errors |
| Outbound calls | The client Behemoth calls other services with: its settings, the rules every call follows, and using it in your code |
| Hooks | Hook points, handlers, ordering, and failure behavior |
| Telemetry | Loggers, audit, metrics, tracing, and the OpenTelemetry adapter |
| Command line | behemoth generate and behemoth migrate: setup, the launcher, its questions, and the draft file |
| Core tables | Writing Behemoth's tables from a plugin |
| Supported databases | The releases of PostgreSQL, MySQL, SQL Server, MongoDB, Redis, and SQLite that Behemoth supports, and running the tests against another release |
| MongoDB | What the server needs, and creating the indexes a schema declares |
Contributions are welcome. Open an issue to discuss a change before you send a large pull request.
- Fork the repository, and create a branch from
dev. - Format the code with
gofmt, and follow the Go Code Review Comments. - Add tests for your change, and run
go test ./.... Thetestsmodule and each adapter module have their owngo.mod, so run their tests from their directories. CI runs every module, and the container suites intestsneed Docker. - Update the docs in
docs/together with the code. - Open a pull request against
dev.
Internal docs explain how the system works.
MIT. See LICENSE.txt.