Installation
Prerequisites, what you need before configuring go-auth, and a map of the configuration pattern.
Installation
Prerequisites
- Go 1.26 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.DisableAdminTwoFactorto turn off).EnvironmentDevis the one exception when a mailer is otherwise needed: with neitherWithMailernorWithEmailset, it falls back to a log-only driver. See Configuration.
Install
go get github.com/nazimdjebloun/go-authgo-auth's own go.mod requires pgx/v5 (PostgreSQL) and modernc.org/sqlite (SQLite) directly, plus the libraries it uses. The library imports the pgx stdlib driver itself, so PostgreSQL is registered automatically. For SQLite or MySQL, your program must blank-import the driver package it uses so it registers with database/sql:
| Database | Package |
|---|---|
| PostgreSQL | github.com/jackc/pgx/v5/stdlib |
| SQLite | modernc.org/sqlite (pure Go, no CGO) |
| MySQL | github.com/go-sql-driver/mysql |
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
Schema and bootstrap tooling, shipped alongside the library. There are two ways to run it, and they do the same thing:
# Install once, then call it by name
go install github.com/nazimdjebloun/go-auth/cmd/goauth@latest
goauth migrate --driver postgres --dsn "$DATABASE_URL"
# Or run it without installing anything
go run github.com/nazimdjebloun/go-auth/cmd/goauth@latest migrate \
--driver postgres --dsn "$DATABASE_URL"go install is shorter to type afterwards and faster on repeat use, but it needs $GOBIN (or $GOPATH/bin) on your PATH, and it pins whatever version you installed until you reinstall. go run leaves nothing behind and is always current. Use it for CI, a Dockerfile, or a one-off bootstrap, which is how migrate and seed-admin are usually used.
`@latest` is required, in both forms
cmd/goauth is a separate module with its own go.mod, so it isn't part of your project's dependency graph even after go get of the library. Drop the version suffix and Go looks for the package among your own dependencies and fails with no required module provides package. This is not a run vs install distinction: both need it. Pin a release instead of @latest if you want reproducible builds.
| Command | What it does |
|---|---|
migrate | Connects to your database and applies the schema directly, one statement at a time. Requires --driver and --dsn. |
generate | Writes the schema to a .sql file instead of applying it: check it in, or feed it to Atlas, golang-migrate, Flyway, or your own migration tool. Requires --driver; --out defaults to auth.schema.sql. |
seed-admin | Creates the first admin account directly in the database, since every admin route needs an existing admin session to call. Sends a real email first and writes nothing if that send fails. See Admin → Creating the first admin. |
Each command takes --help. Schemas covers migrate and generate in full.
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.DisableAdminTwoFactorfor a mailer-free, API-only deployment). Either SMTP credentials or your own delivery implementation (Resend, Postmark, SES, etc.) work.EnvironmentDevalone 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.
| Option | Configures |
|---|---|
WithApp | App name, base URL, database connection, deployment environment |
WithSecret | The root secret for CSRF, OAuth, 2FA, and OTP keys |
WithSecurity | Allowed origins, password policy, CSRF token |
WithSession | Session, refresh-token, and verification/reset-token lifetimes |
WithTwoFactor | Email two-factor settings |
WithCookie | Cookie name, domain, path, SameSite, Secure |
WithRegistration | Which signup methods are available |
WithOrganizations | Multi-tenant organizations |
WithMailer | A custom mailer implementation |
WithEmail | The built-in SMTP mailer |
WithTemplates | Custom email templates |
WithPasswordHasher | A self-identifying password hasher, including the built-in Argon2id implementation |
WithBcryptCost | Keep bcrypt and change its cost |
WithPasswordPepper | Configure opt-in, versioned password peppering and rotation keys |
WithRateLimit and its narrower variants | Per-route rate limiting |
WithProvider | Register an OAuth provider |
WithLogger | Structured logging |
WithAudit / WithAuditSink | Audit logging |
Database setup
The schema ships embedded in the library. There is no .sql file to find on
disk after go get. Apply it once before starting your app for the first time:
go run github.com/nazimdjebloun/go-auth/cmd/goauth@latest migrate \
--driver postgres --dsn "$DATABASE_URL"Schemas covers the tables themselves, the other two ways to get at the schema, and what to expect when it changes between releases.
Next
- Configuration: every option, field by field
- Schemas: the tables, the CLI, and applying the schema