Installation

Start with First working application for a runnable browser flow through signup, verification, 2FA, a protected request and logout. This page details prerequisites and integration choices.

Optional application roles require the fresh canonical schema and explicit initialization before signups. Use seed-admin --app-permissions to create the first protected administrator, then configure WithAppPermissions. Initialization does not install any library permissions. See the setup and permission guide.

Version 0.5.3 requires schema revision 3. Apply the matching migration catalog before starting the backend. Signup is closed by default: explicitly configure WithRegistration for public or invited account creation, and configure WithAuthentication separately for password/OAuth login.

Prerequisites

• Go 1.26.10 or later
• A database: PostgreSQL, MySQL, or SQLite
• An SMTP server, or your own mailer implementation: required unless every email-sending feature is off (invites, email verification, 2FA, and admin login's two-factor challenge, the last of which is on by default and needs TwoFactorConfig.DisableAdminTwoFactor to turn off). EnvironmentDev is the one exception when a mailer is otherwise needed: with neither WithMailer nor WithEmail set, it falls back to a log-only driver. See Configuration.

Install

go get github.com/nazimdjebloun/go-auth

go-auth's go.mod requires pgx/v5 (PostgreSQL), modernc.org/sqlite (SQLite), and go-sql-driver/mysql (MySQL) directly; the last two are used by the goauth CLI, which registers all three drivers. The library imports the pgx stdlib driver itself, so PostgreSQL is registered automatically. For SQLite or MySQL, your program must still blank-import the driver package it uses so it registers with database/sql:

If the driver you configured is not actually registered (the import is missing), New() fails fast at startup with an error naming the missing import. It does not fail later on the first query.

The goauth CLI

The CLI shares the library's root module and release. Run it from the application's Go module without a version suffix to use the dependency selected by go.mod:

go run github.com/nazimdjebloun/go-auth/cmd/goauth migrate \
  --driver postgres --dsn "$DATABASE_URL"

From this source checkout, use go run ./cmd/goauth with the same arguments. For an installed binary, install an exact release matching the library and put $GOBIN or $GOPATH/bin on PATH. A go install/go run version suffix selects that release independently of the application's module. Avoid @latest for migration deployment: it can run a different schema catalog from your binary.

Each command takes --help. Migrations covers deployment, adoption, recovery and the Go API. Keep auth migration ownership separate from the application's migration tool.

What you'll need before configuring

Gather these before writing your configuration:

• A base URL for your frontend: used to build links in emails (verification, invites, password reset).
• A database connection: either a connection string, or a database/pool you already opened yourself.
• A signing secret: at least 32 random bytes. This is the one piece of key material the library needs; source it from your environment, never commit it.
• The origins your frontend is served from: used for CSRF origin checking. No wildcard option exists.
• A mailer, conditionally: required if you enable invite-only signup, email verification, or 2FA, or leave admin login's two-factor challenge on (the default; turn it off with TwoFactorConfig.DisableAdminTwoFactor for a mailer-free, API-only deployment). Either SMTP credentials or your own delivery implementation (Resend, Postmark, SES, etc.) work. EnvironmentDev alone falls back to a log-only driver when a mailer is needed but neither is configured.
• OAuth credentials, conditionally: a client ID, client secret, and redirect URL per provider, only if you want OAuth login.

Nothing here is read from the environment by the library itself. go-auth has no notion of env vars. You decide how your program sources these values (environment variables are the usual choice) and pass them in as plain Go values.

The configuration pattern, at a glance

Pass option functions to NewConfig(opts ...Option). The table maps each option to its responsibility; Configuration documents every field and validation rule.

Database setup

New requires a reachable database with the matching completed auth migration history. It checks both before starting workers, including with a borrowed database or pool. Run migrations separately; construction does not create or upgrade tables. SMTP configuration is validated, but startup does not promise delivery to a remote mailbox.

The published catalog and desired schema are embedded in the library. Apply pending auth migrations explicitly before starting the app:

go run github.com/nazimdjebloun/go-auth/cmd/goauth migrate \
  --driver postgres --dsn "$DATABASE_URL"

The initial catalog is revision 000001. Existing databases must match its complete schema before explicit adoption; old or partial schemas require reviewed reconciliation. Migrations defines these paths, and Schemas documents the auth objects.

Next

• Configuration: every option, field by field
• Schemas: the tables, the CLI, and applying the schema

Redis (optional)

Redis uses github.com/redis/go-redis/v9 through the root module. Apply the current SQL migrations before enabling WithRedis. The complete feature requires Redis scripting and snapshot/TTL permissions; see Redis setup.