Skip to content
Unreleased: these pages follow the main branch. The latest release is v0.5.
Add accounts with make:auth

Add accounts with make:auth

Give your app user accounts in one command: registration, login with “remember me” and throttling, login with Google and GitHub, two-factor authentication, account settings, logout, email verification, password reset and API tokens, with their pages, emails, routes, migration and tests. The code is written into your app, where you change it as you like; the parts that must be right (password hashing, tokens, sessions, throttling, the OAuth flow) stay in the auth and social packages, so fixes reach you with go get -u.

Before you start

You have a project made with anetos new (it has sessions, the cache, the queue and the mailer that accounts use), and no User model yet.

Steps

1. Generate the accounts

From the project’s directory:

go tool anetos make:auth
created app/models/user.go
created app/handlers/auth.go
created app/handlers/settings.go
created app/mailers/auth.go
created views/auth.templ
created views/settings.templ
created views/auth_mail.templ
created routes/auth.go
created auth.go
created auth_test.go
created locales/en/auth.yaml
created database/factories/users.go
created database/migrations/2026_10_02_090000_create_users_table.go
updated .env: SOCIAL_* settings
updated .env.example: SOCIAL_* settings
updated deploy/production.env.example: SOCIAL_* settings
updated main.go: setup calls setupAuth
updated views/layout.templ: the header shows AccountMenu
wrote app/models/models_gen.go

make:auth writes nothing if one of these files exists, or if a name they declare (User, Accounts, Login, …) is taken in its package; if writing fails midway, it removes what it wrote. It runs go mod tidy, anetos generate (the User model’s typed columns) and templ generate (the pages), checks that the project builds, and adds a call to setupAuth to setup in main.go, after routes.Register:

// illustrative: main.go after make:auth
routes.Register(srv.Router(), sessions)
// Accounts (anetos make:auth): registration, login with a password,
// Google or GitHub, two-factor authentication, account settings, email
// verification, password reset and API tokens.
if _, err := setupAuth(app, srv.Router(), sessions); err != nil {
	return nil, err
}

If your setup no longer has that statement, make:auth says so and you add the call yourself.

It also adds @AccountMenu() to the layout’s header, after its nav (the @ui.Nav block, or the </nav> line in a layout made before v0.5): links to log in and register for guests; the user’s name (to the dashboard), the settings and a logout button for logged-in users. setupAuth calls sessions.Use(a.Middleware), so every page with a session knows who is logged in, the home page of routes/web.go included. A layout without that nav gets nothing, and make:auth prints the line to add where you like.

The pages are made of the components of views/ui (Style your app): ui.AuthCard, a small centered card, for the forms, and ui.Cards on the dashboard and the settings page. AccountMenu is a ui.NavEnd with ui.NavLinks, and its buttons in ui.NavItems.

2. Migrate and try it

go run . migrate     # the users, api_tokens and social_accounts tables
go tool anetos dev

Open /register. In development, emails go to the log (MAIL_DRIVER=log), with their links; with QUEUE_DRIVER=database, the app’s workers send them, so they appear a moment later.

3. Turn on login with Google or GitHub

Each provider is on once its client ID and secret are set; until then its button doesn’t show and its routes answer 404. Create an OAuth app at the provider (the Google Cloud console: “OAuth client ID”, type “Web application”; GitHub: “New OAuth App”), register APP_URL/auth/google/callback (or /auth/github/callback) as its callback URL, and fill in the settings make:auth added to .env:

APP_URL=http://localhost:8080
SOCIAL_GOOGLE_CLIENT_ID=1234-abc.apps.googleusercontent.com
SOCIAL_GOOGLE_CLIENT_SECRET=…

The login and registration pages then show “Log in with Google”. A first login creates a user, with the address verified and no password (they can set one with “Forgot your password?”); an account whose address both the provider and your app have verified is linked to the existing user. Social login explains the rules and how to add another provider (Okta, Auth0, any OpenID Connect provider).

4. Run the tests

auth_test.go registers, verifies the address by following the emailed link, logs in and out, turns on two-factor authentication and logs in with a recovery code, changes the name, password, language, time zone and email address in the settings, resets the password, uses an API token, and logs in with Google and GitHub through a stand-in provider (anetostest.FakeSocial):

go test ./...

Keep these tests as you change the code: they cover the flows that matter.

5. Make it yours

FileHolds
app/models/user.goUser, and models.Users: how auth finds users, which are disabled (disabled_at), and stores their tokens, session keys (session_key, replaced to log them out everywhere) and two-factor state (two_factor, encrypted); the language and time zone they chose (locale, time_zone: PreferredLocale, PreferredTimeZone) and a new address waiting for its link (pending_email). Add columns here and in a migration
app/handlers/auth.gohandlers.Accounts: each page and form. Validation messages, redirects and what happens after registration are here; SocialUser finds or creates the user of a Google or GitHub account; SendVerification and SendPasswordReset email the links (the admin’s buttons use them too)
app/handlers/settings.go, views/settings.templThe settings page and its forms: add your own fields here
views/auth.templThe pages, inside your Layout
app/mailers/auth.go, views/auth_mail.templThe verification, reset and change-of-address emails
routes/auth.goThe routes and their names (login, register, dashboard, settings, …), the rate limits of the forgotten-password and verification forms, and what the settings allow (AllowEmailChange, AllowAccountDeletion)
auth.gosetupAuth: the api_tokens and social_accounts migrations, auth.New, social.New with the providers, and the routes
database/migrations/…_create_users_table.goThe users table

The routes:

RouteFor
GET, POST /registerGuests: create an account, email the verification link, log in (10 posts a minute per client IP address)
GET, POST /loginGuests: log in (AUTH_THROTTLE limits failures)
GET, POST /two-factor-challengeGuests whose login waits for a two-factor code: the authenticator app’s, or a recovery code
GET, POST /forgot-passwordGuests: email a reset link (5 posts a minute per client IP address; 3 links an hour per address, the same answer after)
GET, POST /reset-passwordGuests: choose a new password with the link. A reset logs the user out everywhere and revokes their API tokens; for an address never verified, the link verifies it and turns off the two-factor authentication and Google and GitHub links that whoever registered it first may have set up. Two uses of the link at once change the password once
GET /auth/{provider}/redirect, GET /auth/{provider}/callbackGuests: log in with Google or GitHub (404 for a provider whose settings aren’t set)
GET /verify-emailAnyone with the link: verify the address (400 if the link is bad, expired, or for an address the user has since changed)
GET /dashboardLogged-in users: the account and its API tokens
POST /logoutLogged-in users
POST /email/verification-notificationLogged-in users: email the link again (3 a minute per client IP address, 6 an hour per account)
POST /tokensLogged-in users who confirmed their password lately: create an API token (shown once); refused while an admin impersonates the user
POST /tokens/{id}/deleteLogged-in users: revoke an API token
GET /settings; POST /settings/profile, /settings/password, /settings/preferencesLogged-in users: their settings (below)
POST /settings/emailLogged-in users who confirmed their password lately: a new email address (with AllowEmailChange; 5 tries an hour per account)
POST /settings/email/cancelLogged-in users: drop the change
GET /settings/email/verifyAnyone with the link emailed to the new address: make it the account’s
GET, POST /settings/email/revertAnyone with the link emailed to the old address: undo the change and secure the account (10 posts a minute per client IP address)
POST /settings/deleteLogged-in users who confirmed their password lately: delete the account (with AllowAccountDeletion)
GET, POST /confirm-passwordLogged-in users: type the password again before a sensitive page (a.RequireConfirmed), then go back
GET, POST /two-factor, POST /two-factor/confirm, /recovery-codes, /disableLogged-in users who confirmed their password lately: turn two-factor authentication on (a QR code, then a code), get new recovery codes, turn it off. See Two-factor authentication
GET /api/meAPI clients, with Authorization: Bearer <token>

Logging in, registering and logging in with a provider lead to the page the user asked for before logging in, or else to AUTH_HOME_URL: /dashboard, the default setupAuth gives in auth.go (auth.WithDefaultHomeURL("/dashboard")). To send users elsewhere, set AUTH_HOME_URL=/projects in the environment, or change the default in auth.go; the setting wins, so each deployment can choose. Logged-in users who open a guest page go there too; guests who open a member page go to AUTH_LOGIN_URL and come back after logging in. To protect your own pages, put them in a group with a.Middleware and a.Require, as routes/auth.go does: setupAuth returns the *auth.Auth.

Disabled users (disabled_at set, as the admin does) are logged out at their next request and see “This account is disabled.” when they log in with the right password; their API tokens stop working.

The settings page

/settings (AUTH_SETTINGS_URL; the dashboard and the admin link to it) lets a logged-in user change:

  • Their name.
  • Their password, with the current one; their other browsers and devices are logged out, and this one stays logged in (and remembered, if it was) (auth.ChangePassword). A user who logs in with Google or GitHub has no password: they set one within a few minutes of logging in.
  • Their language and time zone, from the app’s languages and i18n.TimeZones(); pages and emails use them (translations). “Your browser’s” language forgets the one chosen on this browser (c.ForgetLocale).
  • Their email address, after typing their password again: that is what keeps someone with a stolen session from taking the account’s login and reset channel. The new address gets a link, and becomes theirs (verified) once it is followed, so a typo can’t lock them out; until then they log in with the old one. Once it is made, their other sessions and the reset links sent to the old address stop working (auth.LogoutOthers). The old address, if it was verified, is told of the change, with a link that undoes it, for AUTH_REVERT_TTL (7 days), even once it is made: if the change wasn’t theirs, someone has their password, so undoing it also secures the account. The address goes back (verified), the password is cleared, two-factor authentication turned off, API tokens and links to Google and GitHub removed, everyone logged out, and the old address gets a link to choose a new password. The link opens a page with a button, as mail scanners follow links. Turn it off with AllowEmailChange: false in routes/auth.go, for apps whose addresses come from an organisation.
  • Delete their account, after typing their password again: the user, their API tokens and Google or GitHub links go, and they’re logged out. Off by default: AllowAccountDeletion: true turns it on. If the app gives users roles, remove them in DeleteAccount too (rbac.RemoveUser); other data of theirs is the app’s to delete or keep.

It links to two-factor authentication. To add a field (a phone number, a newsletter choice), add a column and a migration, the field to User, a form to views/settings.templ and a handler to app/handlers/settings.go, as UpdateProfile does.

Apps that ran make:auth before have no settings page. To add it, take from a new project’s make:auth: the pending_email, locale and time_zone columns (a migration) and User fields, with PreferredLocale and PreferredTimeZone; app/handlers/settings.go, views/settings.templ, the ChangeEmail and EmailChanging mailables and their views; the AllowEmailChange and AllowAccountDeletion fields of Accounts and the settings routes; the auth.settings, auth.mail and other new keys of locales/en/auth.yaml. Then run go tool anetos gen and go tool templ generate.

To do more when someone signs up (a welcome email, a trial), change Register and SocialUser in app/handlers/auth.go, which create users. examples/saas, a make:auth app, queues a welcome job in the transaction that creates the user, so the job runs only if the user is committed:

// welcome queues the welcome email of a new user, once the transaction
// that creates them commits: a worker sends it (jobs.SendWelcome).
func welcome(ctx context.Context, u *models.User) error {
	return queue.Dispatch(ctx, jobs.SendWelcome{UserID: u.ID}, queue.AfterCommit())
}

(Copied from examples/saas/app/handlers/auth.go, region dispatch.)

// SendWelcome emails a new user the welcome email. Registration and the
// first login with Google or GitHub dispatch it once the user is
// committed; a worker runs it, with the queue's retries.
type SendWelcome struct {
	UserID int64 `json:"user_id"`
}

// Handle sends the email.
func (j SendWelcome) Handle(ctx context.Context) error {
	u, err := db.Find[models.User](ctx, j.UserID)
	if errors.Is(err, db.ErrNotFound) {
		return queue.Permanent(err) // deleted since: retrying won't help
	}
	if err != nil {
		return err
	}
	url, err := mailer.URL(ctx, "/dashboard")
	if err != nil {
		return err
	}
	m := mailers.Welcome{Name: u.Name, Email: u.Email, URL: url}
	if u.TrialEndsAt != nil {
		m.TrialEnds = *u.TrialEndsAt
	}
	return mailer.Send(ctx, m)
}

(Copied from examples/saas/app/jobs/welcome.go, region job.)

setup registers the job type, queue.Register[jobs.SendWelcome](q, queue.Tries(5)), where anetos new left a comment for it; see Queues.

How it works

The generated code is the same kind of code as examples/auth, which the Authentication guide walks through, adapted to a anetos new project: templ pages in views, typed columns, the mailer for the links (mailer.Queue, so a slow mail server doesn’t slow the request), and route names. Links in emails are absolute, on APP_URL. Reset and verification tokens are signed, not stored: a reset link works for AUTH_RESET_TTL and once, a verification link for AUTH_VERIFY_TTL. Registration creates the user and renders the email in one transaction, so an email that can’t be rendered leaves no account behind; the queue sends it after the commit. Names are kept on one line (control characters dropped), and emails go to the address alone, the name only in their body.

The forgotten-password form answers the same whether or not the address has an account, but takes a little longer when it does (it renders and queues the email): someone measuring response times could tell. The registration form says when an address is taken, as most sites do.

Logging in with a provider follows the rules of Social login: accounts are linked to users by the provider’s account ID, not by email, and an address finds an existing user only when both the provider and your app have verified it, and the user has no other account of that provider linked.

make:auth doesn’t add authorization policies: see Authorization.

Common problems

ProblemCauseFix
…_create_users_table.go exists or app/models/user.go existsThe app has users already, or make:auth ran beforeRename yours, or add accounts by hand from Authentication
app/models already declares User (or another name)A name the generated files declare is taken in that packageRename yours
the project doesn't build after the files are writtenYour code and the generated code clash, or a tool failedFix it, then run the commands it prints
no app/models directoryNot an anetos new projectStart from examples/auth
main.go doesn't have the routes.Register callsetup was changedAdd the setupAuth call it prints
no such table: usersThe migrations haven’t rungo run . migrate
URL needs the app's public URL when registeringAPP_URL isn’t setSet it in .env
No email in the logQUEUE_DRIVER=database and the workers aren’t runningRun the app with go tool anetos dev or go run ., or use QUEUE_DRIVER=sync
No “Log in with Google” buttonIts SOCIAL_GOOGLE_* settings are emptySet both in .env
redirect_uri_mismatch at GoogleThe callback URL registered there isn’t APP_URL/auth/google/callbackFix APP_URL or the URL at Google

Next steps

Coming from another framework? anetos make:auth writes the handlers, views and routes into your app, as Laravel’s starter kits and Rails’ authentication generator do, where Django’s django.contrib.auth keeps its views in the library. Hashing, remember-me, throttling and tokens stay in the library here, and so does the OAuth flow.