Authentication
Let people register, log in (with “remember me”), log out, verify their
email address and reset a forgotten password, and give API clients
tokens. The complete app is examples/auth.
In an anetos new project, go tool anetos make:auth writes all of this
into your app: see Add accounts with make:auth. This
guide is the auth package underneath, step by step.
Before you start
You need sessions (Sessions and flash messages), the
cache (login throttling counts failures in it, see
Cache) and a users table. Passwords are hashed with
auth/password (argon2id).
Steps
1. Describe your users
Your user model implements two methods:
// User is an account. The two Auth methods are what package auth needs.
type User struct {
db.Model
Name string `db:"name" json:"name"`
Email string `db:"email" json:"email"` // stored in lower case
Password string `db:"password" json:"-"` // password.Hash
RememberToken string `db:"remember_token" json:"-"`
EmailVerifiedAt *time.Time `db:"email_verified_at" json:"email_verified_at"`
Admin bool `db:"admin" json:"admin"`
TwoFactor string `db:"two_factor" json:"-"` // two-factor authentication, encrypted by package auth
}
// AuthID implements auth.Authenticatable.
func (u *User) AuthID() string { return strconv.FormatInt(u.ID, 10) }
// AuthPassword implements auth.Authenticatable.
func (u *User) AuthPassword() string { return u.Password }(Copied from examples/auth/users.go, region user.)
auth.Users tells the package how to find users, and, optionally, how
to store remember-me tokens and upgraded password hashes:
// users tells package auth how to find and update users.
var users = auth.Users[*User]{
ByID: func(ctx context.Context, id string) (*User, error) {
n, err := strconv.ParseInt(id, 10, 64)
if err != nil {
return nil, auth.ErrUserNotFound
}
u, err := db.Find[User](ctx, n) // db.ErrNotFound: no such user
return &u, err
},
ByLogin: func(ctx context.Context, email string) (*User, error) {
u, err := db.Query[User](ctx).Where(colEmail.Eq(strings.ToLower(email))).First()
return &u, err
},
RememberToken: func(u *User) string { return u.RememberToken },
SetRememberToken: func(ctx context.Context, u *User, token string) error {
_, err := db.Query[User](ctx).Where(colID.Eq(u.ID)).Update(colRemember.Set(token))
return err
},
SetPassword: func(ctx context.Context, u *User, hash string) error {
_, err := db.Query[User](ctx).Where(colID.Eq(u.ID)).Update(colPassword.Set(hash))
return err
},
// Two-factor authentication: package auth stores its state (the secret
// encrypted with APP_KEY, the recovery codes hashed) in a column.
TwoFactor: func(u *User) string { return u.TwoFactor },
SetTwoFactor: func(ctx context.Context, u *User, state string) error {
u.TwoFactor = state
_, err := db.Query[User](ctx).Where(colID.Eq(u.ID)).Update(colTwoF.Set(state))
return err
},
}(Copied from examples/auth/users.go, region users.)
ByID and ByLogin return db.ErrNotFound (or auth.ErrUserNotFound) when
there is no such user. Store email addresses in lower case, and look them
up the same way.
2. Set up auth and protect routes
// AUTH_* settings. Logging in leads to /dashboard, unless
// AUTH_HOME_URL names another page.
a, err := auth.New(app, users, auth.WithDefaultHomeURL("/dashboard"))
if err != nil {
return nil, err
}(Copied from examples/auth, region setup.)
Add a.Middleware after the session middleware, then a.Require on the
routes for logged-in users and a.Guest on the login and registration
pages:
pages := r.Group("", sessions.Middleware, web.CSRF(), a.Middleware)
pages.Get("/", func(c *web.Ctx) error { return c.Redirect(http.StatusSeeOther, "/dashboard") })
pages.Get("/verify-email", web.H(h.VerifyEmail))
guests := pages.Group("", a.Guest) // logged-in users go to AUTH_HOME_URL
guests.Get("/register", h.page("register"))
guests.Post("/register", web.H(h.Register))
guests.Get("/login", h.page("login"))
guests.Post("/login", web.H(h.Login))
guests.Get("/forgot-password", h.page("forgot"))
guests.With(ratelimit.Middleware("forgot-password", ratelimit.PerMinute(5))).Post("/forgot-password", web.H(h.SendReset))
guests.Get("/reset-password", h.page("reset"))
guests.Post("/reset-password", web.H(h.Reset))
guests.Get("/auth/{provider}/redirect", s.Redirect) // "Log in with …" links here
guests.Get("/auth/{provider}/callback", s.Callback)
guests.Get("/two-factor-challenge", h.page("challenge")) // AUTH_CHALLENGE_URL
guests.Post("/two-factor-challenge", web.H(h.Challenge))
loggedIn := pages.Group("", a.Require) // guests go to AUTH_LOGIN_URL
loggedIn.Get("/dashboard", h.Dashboard)
loggedIn.Post("/logout", h.Logout)
loggedIn.Post("/tokens/{id}/delete", web.H(h.RevokeToken))
loggedIn.Get("/users/{id}", web.H(h.ShowUser))
loggedIn.Get("/admin", h.Admin)
loggedIn.Post("/password", web.H(h.ChangePassword))
loggedIn.Get("/confirm-password", h.page("confirm")) // AUTH_CONFIRM_URL
loggedIn.Post("/confirm-password", web.H(h.ConfirmPassword))
// Two-factor authentication (AUTH_TWO_FACTOR_URL) and API tokens (they work
// without the browser): the password again first.
secure := loggedIn.Group("", a.RequireConfirmed)
secure.Post("/tokens", web.H(h.CreateToken))
secure.Get("/two-factor", h.TwoFactor)
secure.Post("/two-factor", h.StartTwoFactor)
secure.Post("/two-factor/confirm", web.H(h.ConfirmTwoFactor))
secure.Post("/two-factor/disable", h.DisableTwoFactor)
api := r.Group("/api", a.TokenMiddleware, a.Require) // Authorization: Bearer <token>
api.Get("/me", h.Me)(Copied from examples/auth, region routes.)
Require sends guests asking for a page to AUTH_LOGIN_URL (remembering
the page for auth.Intended), and answers other requests (JSON, htmx)
with 401. Guest sends logged-in users to AUTH_HOME_URL.
Read the current user in a handler with auth.User or auth.Current:
// illustrative
u, ok := auth.User[*User](c) // pages that show a guest something else
u, err := auth.Current[*User](c) // handlers that need the user: return errauth.User answers whether there is a user: a guest and a user who
couldn’t be loaded (the database is down; it’s logged) are both “no”.
Use it in views and pages that change for guests. auth.Current returns
auth.ErrUnauthenticated (401) for a guest, or the error that kept the
user from loading, which a handler returns as it is: use it behind
Require, and anywhere a failure must not pass for a guest.
The user is loaded from the database when first asked for, once per request.
3. Register
Hash the password, create the user and log them in:
func (h Accounts) Register(c *web.Ctx, in RegisterInput) (web.Responder, error) {
email := strings.ToLower(in.Email) // stored and looked up in lower case
taken, err := db.Query[User](c).Where(colEmail.Eq(email)).Exists()
if err != nil {
return nil, err
}
if taken {
return nil, validate.Fail("email", "The email has already been taken.")
}
hash, err := password.Hash(in.Password)
if err != nil {
return nil, err
}
u := &User{Name: in.Name, Email: email, Password: hash}
if err := db.Create(c, u); err != nil {
return nil, err
}
// The account exists now: a mail server that fails doesn't undo it
// (an app with a queue sends with mailer.Queue, which retries).
if err := sendLink(c, u.Email, "Verify your email address", "/verify-email?token="+url.QueryEscape(h.auth.VerificationToken(u, u.Email))); err != nil {
c.Logger().Error("send the verification link", "error", err)
}
if err := h.auth.Login(c, u, false); err != nil {
return nil, err
}
return web.Redirect("/dashboard"), nil
}(Copied from examples/auth, region register.)
4. Log in and out
Attempt checks the password and logs the user in; turn its errors
into a form error:
func (h Accounts) Login(c *web.Ctx, in LoginInput) (web.Responder, error) {
_, err := h.auth.Attempt(c, in.Email, in.Password, in.Remember)
var throttled *auth.ThrottledError
switch {
case errors.Is(err, auth.ErrInvalidCredentials):
return nil, validate.Fail("email", "These credentials don't match our records.")
case errors.As(err, &throttled):
return nil, validate.Fail("email", "Too many login attempts. Try again in a minute.")
case errors.Is(err, auth.ErrTwoFactorRequired):
return web.Redirect("/two-factor-challenge"), nil // the password was right: now the code
case err != nil:
return nil, err
}
return web.Redirect(auth.Intended(c, h.auth.Config().HomeURL)), nil // the page they wanted, or AUTH_HOME_URL
}
func (h Accounts) Logout(c *web.Ctx) error {
if err := h.auth.Logout(c); err != nil {
return err
}
return c.Redirect(http.StatusSeeOther, "/login")
}(Copied from examples/auth, region login.)
A failed login gives the same error whether the address has no account
or the password is wrong, and takes about as long (users with an old
bcrypt hash, until they next log in, can take longer). After
AUTH_THROTTLE attempts (5 by default) in a minute for one login, or
one account, from one IP address, and after AUTH_THROTTLE_IP failures
(50) from one address whatever the login, Attempt returns a
*auth.ThrottledError without checking the password. Users whose hash is
stronger than the defaults (made with password.HashWith) also take
longer to check than unknown logins. Login (and so Attempt) gives the
session a new ID; Logout empties it and logs the user out of every
browser where they chose “remember me”. With the default cookie
sessions, a copy of the session cookie taken before the logout keeps
working until it expires; use a server-side SESSION_DRIVER to revoke
sessions at logout.
5. Verify email addresses
Send a link with a verification token, and check it when it’s followed:
func (h Accounts) VerifyEmail(c *web.Ctx, in TokenQuery) (web.Responder, error) {
u, email, err := h.auth.CheckVerificationToken(c, in.Token)
if err != nil {
return nil, err // 400 for a bad or expired link
}
if email == u.Email && u.EmailVerifiedAt == nil {
now := anetos.Now(c).UTC()
if _, err := db.Query[User](c).Where(colID.Eq(u.ID)).Update(colVerified.Set(&now)); err != nil {
return nil, err
}
}
c.Session().Flash("status", "Your email address is verified.")
return web.Redirect("/dashboard"), nil
}(Copied from examples/auth, region verify.)
sendLink emails the link with the mailer, as an absolute URL
on APP_URL (mailer.URL); in tests, anetostest records the email,
and the test follows its link.
6. Reset forgotten passwords
func (h Accounts) SendReset(c *web.Ctx, in ForgotInput) (web.Responder, error) {
u, err := users.ByLogin(c, in.Email)
switch {
case err == nil:
if err := sendLink(c, u.Email, "Reset your password", "/reset-password?token="+url.QueryEscape(h.auth.PasswordResetToken(u))); err != nil {
return nil, err
}
case !errors.Is(err, db.ErrNotFound):
return nil, err
}
// The same answer either way, so the form doesn't reveal who has an
// account.
c.Session().Flash("status", "If that address has an account, we've emailed it a link.")
return web.Redirect("/login"), nil
}
func (h Accounts) Reset(c *web.Ctx, in ResetInput) (web.Responder, error) {
u, err := h.auth.CheckPasswordResetToken(c, in.Token)
if errors.Is(err, auth.ErrInvalidToken) {
return nil, validate.Fail("password", "This reset link is invalid or has expired. Ask for a new one.")
}
if err != nil {
return nil, err
}
hash, err := password.Hash(in.Password)
if err != nil {
return nil, err
}
// Only if the password is still the one the link was made for: two
// uses of the link at once change it once.
n, err := db.Query[User](c).Where(colID.Eq(u.ID), colPassword.Eq(u.Password)).Update(colPassword.Set(hash))
if err != nil {
return nil, err
}
if n == 0 {
return nil, validate.Fail("password", "This reset link is invalid or has expired. Ask for a new one.")
}
// The new password logs out every session and remembered browser
// (their password fingerprint no longer matches); API tokens are
// revoked too.
if err := h.auth.RevokeAllTokens(c, u); err != nil {
return nil, err
}
c.Session().Flash("status", "Your password has been reset. You can log in now.")
return web.Redirect("/login"), nil
}(Copied from examples/auth, region reset.)
A reset token works for AUTH_RESET_TTL (an hour) and only until the
password changes, so it works once; the update is conditional on the old
hash, so two uses at the same moment change it once. Changing the
password logs the user out of every other session (cookie sessions:
when they’re next used, as the password fingerprint no longer matches)
and remembered browser; a.RevokeAllTokens removes their API tokens.
Throttle the form that sends links, as the example does, so it can’t be
used to flood someone’s inbox.
7. Let users change their password
a.ChangePassword(ctx, u, current, new) checks the current password
(throttled, AUTH_THROTTLE tries a minute), stores the new one hashed,
and logs the user out of their other sessions and remembered browsers
(a.LogoutOthers), keeping the one they’re using: it gets a new
session ID, and stays remembered if it was. A user without a password (who logs in
with Google, say) sets one without current, if they logged in within the
last AUTH_CONFIRM_TTL.
// ChangePassword changes the logged-in user's password. Their other
// browsers and devices are logged out; this one stays logged in.
func (h Accounts) ChangePassword(c *web.Ctx, in NewPasswordInput) (web.Responder, error) {
u, err := auth.Current[*User](c)
if err != nil {
return nil, err
}
switch err := h.auth.ChangePassword(c, u, in.CurrentPassword, in.Password); {
case errors.Is(err, auth.ErrInvalidCredentials):
return nil, validate.Fail("current_password", "That isn't your password.")
case err != nil:
return nil, err
}
c.Session().Flash("status", "Password changed.")
return web.Redirect("/dashboard"), nil
}(Copied from examples/auth, region change-password.)
make:auth’s settings page has it, with the user’s name,
email address, language and time zone.
8. Give API clients tokens
Add auth.Migrations() to your migrations for the api_tokens table.
Tokens are created for a user with abilities, and shown once:
func (h Accounts) CreateToken(c *web.Ctx, in NewTokenInput) (web.Responder, error) {
u, err := auth.Current[*User](c)
if err != nil {
return nil, err
}
plain, _, err := h.auth.CreateToken(c, u, in.Name, []string{"profile:read"}, 90*24*time.Hour)
if err != nil {
return nil, err
}
c.Session().Flash("token", plain) // shown once
return web.Redirect("/dashboard"), nil
}
// Me is GET /api/me, for API clients with a token.
func (Accounts) Me(c *web.Ctx) error {
if !auth.TokenCan(c, "profile:read") {
return auth.ErrForbidden
}
u, err := auth.Current[*User](c)
if err != nil {
return err
}
return c.JSON(http.StatusOK, u)
}(Copied from examples/auth, region api-tokens.)
Clients send Authorization: Bearer <token> to routes with
a.TokenMiddleware (see the routes above). Keep those routes in their
own group, without the session middleware and web.CSRF: a CSRF check
would refuse API clients’ posts, and without sessions a.Require
answers 401 instead of redirecting. Other Authorization schemes are
ignored (the request is a guest). auth.TokenCan checks a
token’s abilities, and auth.RequireAbilities(…) is middleware
answering 403 to a token without them; a user logged in with a session
(your own pages and front end) may do anything. a.Tokens lists a user’s tokens and
a.RevokeToken deletes one.
Put the route that creates tokens behind a.RequireConfirmed, as the
example does: a token outlives the session, so someone holding a stolen
session shouldn’t be able to make one without the password. CreateToken
refuses while an admin impersonates the user (403), for the same reason.
An API whose clients log in with tokens, without sessions,
uses a.AttemptCredentials(ctx, login, password): Attempt’s
check and throttling, returning the user to give a token to. For a user
with two-factor authentication on, it fails with a *auth.TwoFactorChallenge
whose Token the client sends back with a code to
a.AttemptTwoFactorChallenge. Where pages use RequireConfirmed, an
API asks for the password in the request: a.CheckPassword(ctx, u, password). make:auth in an API project writes all of this:
Add accounts to an API.
9. Test
func TestRegisterAndLogin(t *testing.T) {
app := anetostest.New(t, setup)
app.Get("/register").AssertOK()
app.PostForm("/register", url.Values{"name": {"Ada"}, "email": {"[email protected]"},
"password": {"password1"}, "password_confirmation": {"password1"}}).
AssertRedirect("/dashboard").
Follow().
AssertSee("Hello, Ada", "Please verify your email address")
// The emailed link verifies the address.
app.Get(emailedLink(t, app, "Verify your email address")).AssertRedirect("/dashboard").Follow().
AssertSee("Your email address is verified.").
AssertDontSee("Please verify")
app.PostForm("/logout", nil).AssertRedirect("/login")
app.Get("/dashboard").AssertRedirect("/login") // guests go to the login page
app.PostForm("/login", url.Values{"email": {"[email protected]"}, "password": {"wrong"}}).
AssertValidationErrors("email")
app.PostForm("/login", url.Values{"email": {"[email protected]"}, "password": {"password1"}}).
AssertRedirect("/dashboard") // the page asked for before logging in
}(Copied from examples/auth/main_test.go, region test-auth.)
Tests that need a logged-in user can log in through the form, as above, or create the user and post to your login route. API tokens work in tests like in production:
func TestAPIToken(t *testing.T) {
app := anetostest.New(t, setup)
createUser(t, app, "Ada", "[email protected]", false)
app.Get("/login")
app.PostForm("/login", url.Values{"email": {"[email protected]"}, "password": {"password1"}})
app.PostForm("/confirm-password", url.Values{"password": {"password1"}}) // tokens need it
app.PostForm("/tokens", url.Values{"name": {"cli"}}).AssertRedirect("/dashboard")
token := app.Session().GetString("token") // flashed to show once
// The API routes don't use the session: only the token counts.
app.GetJSON("/api/me").AssertStatus(http.StatusUnauthorized)
app.WithHeader("Authorization", "Bearer "+token).GetJSON("/api/me").
AssertOK().
AssertJSONPath("email", "[email protected]")
}(Copied from examples/auth/main_test.go, region test-api-token.)
How it works
The session holds the user’s ID and a fingerprint of their password hash:
when the password changes, other sessions no longer match and are logged
out. “Remember me” sets a second cookie, encrypted with APP_KEY, holding
the user’s ID and remember token (a column of your users table): when the
session has ended, the cookie logs the user back in to a new session.
Logout replaces the token, which invalidates every remembered browser.
Verification and reset tokens aren’t stored: they are encrypted with
APP_KEY and hold the user’s ID, an expiry and (for resets) the password
fingerprint. API tokens are <id>|<secret>; only a SHA-256 hash of the
secret is stored, and the use is recorded at most once a minute.
Password hashes are argon2id with OWASP’s recommended parameters
(19 MiB, 2 passes); at most a few run at once (as many as there are
CPUs), so a burst of logins waits rather than exhausting memory. Existing
bcrypt hashes (from an existing app, say) still work (bcrypt only checks a
password’s first 72 bytes), and Attempt replaces them, and argon2id
hashes weaker than the defaults, after the next login when you set
Users.SetPassword. The new hash changes the password fingerprint, so
the user’s other sessions are logged out once.
Coming from another framework?
a.Attempt,a.Login,a.Logoutandauth.Userdo what Django’sauthenticate(),login(),logout()andrequest.user, Laravel’sAuth::attempt(),Auth::login(),Auth::logout()andauth()->user(), or theauthenticate_by,start_new_session_for,terminate_sessionandCurrent.userof Rails’ authentication generator do.a.Requireanda.Guestlet only logged-in users, or only guests, through. API tokens with abilities are built in (a.CreateToken,auth.TokenCan).anetos make:authwrites the pages (Add accounts with make:auth), and Social login adds Google, GitHub and any OpenID Connect provider.
Common problems
| Symptom | Cause | Fix |
|---|---|---|
auth: login throttling needs the app's cache at startup | cache.New isn’t called, or is called after auth.New | Set up the cache first |
auth: no auth state in the context | The route lacks a.Middleware | Add it after the session middleware |
auth: New called twice for one app | Two auth.New calls | An app has one Auth, for one user type |
the current user was asked for while it was being loaded | Users.ByID calls auth.User or auth.Check (through a query scope, say) | Don’t ask for the current user while finding it |
| Every page redirects to the login page after logging in | a.Middleware runs before the session middleware | Put the session middleware first |
| Users are logged out when they change their password | By design: other sessions end | Use a.ChangePassword, or call a.LogoutOthers(ctx, u) after storing the new hash: it keeps the current session, bound to the new password |
| “Remember me” returns an error | Users.RememberToken/SetRememberToken are unset | Add a remember_token column and set both |
| API requests get 401 with a valid token | The route uses the session middleware and a.Middleware but not a.TokenMiddleware | Put API routes in a group with a.TokenMiddleware |