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 emailpassword plugin.
  • 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 behemoth command.
  • 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:

FeatureBehemothDIY
Password hashingBuilt-inManual
Session storageOnly token hashes storedCustom implementation
Sensitive values at restSealed by the storeOften plaintext
Schema changesGenerated migrationsHand-written
Extending sign-upHooks and pluginsEdit 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 FrameworkDriver interface

Quick example #

The following example adds email and password authentication to a Gin application:

go
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.
Full example

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: