Auth
extension/auth is accounts, credentials and gates in one module. You write one Users type — find an account by its login, load it by id — and nexus does the rest: it issues and checks sessions, bearer tokens and API keys (and verifies JWTs another service issued), runs the sign-in flows, and enforces gates the same way on REST, GraphQL, WebSocket, Inertia pages and views. Settings live in nexus.toml's [auth] table.
Accounts and sign-in
Implement auth.Users — find an account by its login, load it by id — and hand its constructor to auth.Module:
type Users struct{ db *DB }
func NewUsers(db *DB) *Users { return &Users{db: db} }
// FindLogin returns the account a sign-in names and its encoded password.
func (u *Users) FindLogin(ctx context.Context, login string) (*auth.Identity, string, error) {
var row User
if err := u.db.Where("email = ?", login).First(&row).Error; err != nil {
return nil, "", ignoreNotFound(err)
}
return u.identity(row), row.Password, nil
}
// Load rebuilds the identity of a signed-in user, by id.
func (u *Users) Load(ctx context.Context, id string) (*auth.Identity, error) {
var row User
if err := u.db.First(&row, "id = ?", id).Error; err != nil {
return nil, ignoreNotFound(err)
}
return u.identity(row), nil
}
func (u *Users) identity(row User) *auth.Identity {
return &auth.Identity{ID: strconv.FormatInt(row.ID, 10), Kind: row.Kind, Perms: row.Perms, User: &row}
}
nexus.Boot(auth.Module(auth.Config{Users: auth.UseUsers(NewUsers)}), …)A type that doesn't implement Users fails boot, naming the missing method, and so does an optional method spelled right with the wrong signature (a CheckLogin taking a string would otherwise be skipped silently). Config.Users is the one setting auth.Module requires. FindLogin's identity needs the user's Kind when you use areas: signing in under an area, and the next a sign-in returns to, are checked against it. Two optional methods add to it: SetPassword(ctx, id, encoded string) error stores passwords (auth.SetPassword, and a rehash when a stored hash is outdated), and CheckLogin(ctx, id *auth.Identity) error refuses a sign-in, such as a disabled account.
Sign-in is two calls in any handler:
func (s *AccountService) SignIn(ctx context.Context, in SignInForm) (*auth.Credential, error) {
id, err := auth.Login(ctx, auth.Password{Login: in.Email, Password: in.Password})
if err != nil {
return nil, err // "invalid login or password" (422), or CheckLogin's error
}
return auth.SignIn(ctx, id)
}
nexus.AsRest("POST", "/sign-in", (*AccountService).SignIn, auth.Public())auth.Loginfinds the account, checks the password with the[auth.passwords]hashers, rehashes it when it was stored with an older algorithm, and runsCheckLogin. A wrong password and an unknown account give the same error in the same time.auth.SignInissues the credential. With a session scheme it cycles the session id and stores the user's id in it. Withauth.Using("api")it issues a bearer token (or an API key, for anapikeyscheme) and returns it once, as{"access_token", "token_type", "expires_in"}. Only the token's SHA-256 is stored.auth.SignOut(ctx)ends the credential the request came with: it destroys the session, or revokes the token.auth.SetPassword(ctx, id, plain)checks the[auth.passwords]rules, then hashes and stores the password.auth.Refresh(ctx, userID)drops the cachedLoadafter you change a user's roles.
Schemes are declared in nexus.toml. Without any, one session scheme named web is used:
[auth.schemes.web]
type = "session"
[auth.schemes.api]
type = "bearer"
ttl = "12h"A session scheme brings extension/session with it, and turns CSRF protection on. To use your own session store, put session.Module before auth.Module. Tokens are kept in memory by default, which loses them on restart (production logs a warning, and nexus doctor flags it). In production keep them in your database —
import "github.com/paulmanoni/nexus/v2/extension/auth/authdb"
nexus.Boot(db.BindFromConfig[DB]("main"), authdb.Bind[DB](), auth.Module(…))(authdb creates its nexus_auth_tokens table on boot; authdb.NoMigrate() leaves that to you, authdb.Migrate runs it) — or in Redis with Config.Tokens: auth.CacheTokens(cache), or in your own auth.TokenStore.
Every endpoint needs a sign-in on this path unless it is marked auth.Public(); [auth] default = "public" turns that off. Users.Load results are cached per user id for [auth] cache (5 minutes by default). When a credential arrives but doesn't work — an expired or revoked token, a deleted account — the request is anonymous, and under nexus dev the 401 says why. All keys: [auth].
Areas, next and the sign-in page
An area is a path prefix that belongs to some kinds of user, with its own sign-in page:
[auth]
login = "/login" # the sign-in page outside every area
[auth.areas.admin]
prefix = "/admin"
kinds = ["staff"] # empty: any signed-in user
login = "/admin/login"
home = "/admin" # default: the prefix- Every endpoint under the prefix needs a sign-in of one of its kinds — a customer's session on
/admin/ordersis refused with 403 — exceptPublicones, such as the area's own sign-in page. - An unauthenticated page visit goes to the sign-in page with
?next=back to it: a document load gets a 302, an Inertia visit a 409 withX-Inertia-Location. API, GraphQL and WebSocket callers get the 401. - Signing in under an area admits only its kinds. A customer posting to
/admin/logingets the same "invalid login or password" as a wrong password. Credential.Nextis where to go after signing in: the request's?next=(orauth.ReturnTo(next)), when it is a same-site path in an area the user may enter, else the area'shome, else[auth] home. The check refuses//host, backslashes, schemes and control characters, as given and after each round of URL decoding, sonextcan't send anyone off-site.auth.Next(ctx)reads it for your own flows.
A refused page visit — a customer opening /admin/orders — goes to the area's forbidden page when it has one (forbidden = "/admin/forbidden", a page your app serves), else [auth] forbidden; API calls get the 403.
An area can keep its own sign-in. By default every area shares the app's session, so a browser is one user everywhere. Name a session scheme on the area and it holds that area's sign-in alone, under its own cookie scoped to the prefix — a staff member can be signed in to /admin and, in the same browser, to the shop as a customer:
[auth.schemes.web]
type = "session" # the app's session
[auth.schemes.admin]
type = "session" # /admin's own: cookie nexus_admin_session, Path=/admin
[auth.areas.admin]
prefix = "/admin"
kinds = ["staff"]
session = "admin"auth.SignIn under /admin signs in through it (no auth.Using needed), SignOut there ends only it, and impersonating there acts there only. It is a stored token in an HttpOnly cookie, so RevokeUser, Sessions/RevokeSession and the token store cover it like any other credential. Requests outside the prefix never see it — keep the area's API under the prefix too (nexus.Module("admin", nexus.Path("/admin"), …)). [auth.sessions] idle applies to the app's session only.
On every page
Inertia pages get an auth prop on every render — {user, can}, the same shape as the built-in me endpoint — so a layout can show the user and hide what they can't do without a shared prop of your own. [auth] page_prop renames it, "-" turns it off, and an app prop with the same key wins.
auth.SignIn and auth.SignOut give the browser a new CSRF token, so a token planted before a sign-in is worthless after it.
Signing out everywhere
auth.RevokeUser(ctx, userID) // ends every session and token the user holds
auth.Revoke(ctx, token) // ends one bearer token or API keyEach user has an epoch — when their credentials were last ended — and every session and token records the one it was issued under, so ending them all is one write. Open WebSocket and live-page connections check it before each message and close with Unauthenticated once it moves. Other replicas notice within [auth] cache.
[auth.sessions]
single = false # true: signing in ends the user's other sessions
end_on_password_change = true # auth.SetPassword ends every other session and token
idle = "2h" # end a session unused this long (0 = never)Devices and API keys
list, err := auth.Sessions(ctx, userID) // where the user is signed in, newest first
err = auth.RevokeSession(ctx, userID, list[1].ID) // end one of them
key, dev, err := auth.Keys.Create(ctx, userID, "partners", "billing sync") // an apikey scheme
keys, err := auth.Keys.List(ctx, userID)
err = auth.Keys.Revoke(ctx, userID, dev.ID)Each auth.Device has a Kind ("session", "token" or "key"), its scheme, when it was created and expires, the User-Agent and IP it was issued to, and Current for the request's own credential — what a "your devices" page shows. ID is a hash, never the credential. A key is returned once, at Create; only its hash is stored.
Listing needs the token store to list a user's tokens (auth.TokenLister); the memory store and CacheTokens do. Sessions signed in from 2.6 on are listed — each gets a record in the token store, which RevokeSession deletes.
Refresh tokens, OAuth2 and tokens from elsewhere
A bearer scheme with refresh set returns a refresh token with every sign-in; auth.RefreshToken(ctx, refresh) exchanges it for a new pair, and the old one stops working. A refresh token isn't accepted as an access token, and one from before the user's last RevokeUser is refused.
[auth.schemes.api]
type = "bearer"
ttl = "1h"
refresh = "720h"
[auth.endpoints]
token = "/oauth/token" # RFC 6749: grant_type=password and refresh_token
revoke = "/oauth/revoke" # RFC 7009The token endpoint takes form-encoded or JSON bodies, answers errors as {"error": "invalid_grant", …}, and skips CSRF even in an app with sessions — it sets no cookie and answers only the caller, which is also what app.ExemptCSRF(path) is for. A path ending in /* exempts everything under it: app.ExemptCSRF("/api/devices/*").
OAuth2 clients. The token endpoint also knows clients — services and apps that call it — from nexus.toml, or from your database through Config.Clients (an auth.Clients, consulted first):
[auth.oauth2]
require_client = false # true: password and refresh_token need a known client too
[auth.oauth2.clients.billing]
secret = "${BILLING_CLIENT_SECRET}" # or secret_hash, as auth.Hashers encodes; neither: a public client
grants = ["client_credentials"] # empty: all of password, refresh_token, client_credentials
perms = ["reports.view"] # what its client_credentials tokens may do
kind = "service" # their identity's Kind (default "client")A client authenticates with HTTP Basic or client_id/client_secret in the body; a wrong secret is invalid_client (401). With client_credentials a confidential client gets a token as itself — identity client:<id>, its perms and kind, no refresh token — which every gate, area and RevokeUser("client:<id>") treats like a user's.
A jwt scheme verifies tokens another service issued — nexus never issues them — and loads the user named by the subject claim:
[auth.schemes.mobile]
type = "jwt"
jwks = "https://id.example.com/.well-known/jwks.json" # or secret (HS256), or public_key (PEM: RS256/ES256)
issuer = "https://id.example.com"
audience = "orders-mobile"
subject = "sub" # the claim holding the user id (default sub)
leeway = "1m" # clock skew allowed on exp and nbf
revocable = true # auth.RevokeUser reaches these tokens (needs iat)With revocable = true, a token issued (iat) before the user's last RevokeUser is refused — one cached lookup per request, which is why it's opt-in.
Only the algorithms the key is for are accepted (HS256 for a secret, RS256 or ES256 for a public key), so a token can't pick none, or HS256 against an RSA key. JWKS keys are cached for an hour and fetched again for an unknown kid. A jwt scheme and a bearer scheme share the Authorization header: a JWT has three dot-separated parts, a nexus token none.
Sign in with Google, Microsoft, …
An oidc scheme signs people in through an OpenID Connect provider:
[auth.schemes.google]
type = "oidc"
issuer = "https://accounts.google.com" # endpoints come from its discovery document
client_id = "${GOOGLE_CLIENT_ID}"
client_secret = "${GOOGLE_CLIENT_SECRET}"
login = "/auth/google" # link here (?next= is kept)
redirect = "/auth/google/callback" # register this with the provider
claim = "email" # what Users.FindLogin is asked with (default)nexus runs the authorization-code flow with PKCE, a state and a nonce, verifies the ID token with the provider's keys, and finds the account with Users.FindLogin(email) — an address the provider marks unverified is refused. No account: refused, unless your Users has Provision(ctx, scheme, claims) (*auth.Identity, error) to create one. CheckLogin applies, then the user is signed in with the app's session scheme (an oidc scheme needs one) and lands on next.
Roles and the permission catalogue
[auth]
perms = ["orders.view", "orders.refund", "users.manage"] # optional catalogue
[auth.roles]
admin = ["*"]
clerk = ["orders.view", "orders.refund"]An identity's Roles add their permissions to Perms when nexus loads it, so Users.Load can return Roles: []string{"clerk"} and let nexus expand it. With perms set, every permission a gate (Requires, RequiresAny) or a role names must be declared — auth.Requires("ordres.view") fails boot — and a Can / Gates / Check naming an undeclared one is logged. Roles and the catalogue show on the dashboard's Auth tab.
Impersonation
err := auth.Impersonate(ctx, targetID) // the rest of this session acts as targetID
err = auth.StopImpersonating(ctx)[auth.impersonation]
permission = "auth.impersonate" # who may (default)
endpoint = "/admin/impersonate" # POST {user_id} starts, DELETE stopsWhile impersonating, auth.Current(ctx) is the target and .Actor the real user; gates evaluate the target, and auth.reject trace events carry both ids. Nobody can take on a user holding a permission they lack, impersonations don't nest, and the credential stays the real user's — signing them out (or RevokeUser on them) ends it. Works on sessions, bearer tokens and API keys. The me endpoint and the Inertia auth prop add actor, for a "you are acting as …" banner.
Per-object rules
var OrderPolicy = auth.Policy(func(ctx context.Context, me *auth.Identity, perm string, o *Order) bool {
return o.CustomerID == me.ID || me.Has("orders.*")
})
nexus.Boot(OrderPolicy, …)
if err := auth.Check(ctx, "orders.cancel", order); err != nil { // perm, then the *Order policy
return nil, err // Unauthenticated or Forbidden
}
auth.Allowed(ctx, "orders.cancel", order) // the bool, for UI togglesA policy is registered per type — *Order and Order are different — and a type without one is checked on the permission alone; perm may be "" to check only the policy.
Background jobs
A job enqueued from a request records who enqueued it, and runs as that user: their identity is loaded through Users.Load when the job starts, so auth.Current(ctx), auth.Can and auth.Check work inside it with the permissions they have then. A job whose user no longer exists fails without retrying. Define a job with jobs.AsSystem() to run it without anyone's identity — it runs whoever enqueued it. A job enqueued while impersonating runs as the impersonated user, and its record keeps the real one too (Record.Impersonator, run.Impersonator()).
Checking the setup
nexus lint nexus.toml warns about [auth] default = "public". At boot, a sign-in or forbidden page path no route serves is logged (apps with a frontend aren't checked — the SPA may route it).
The dashboard's Auth tab shows the setup — schemes, areas, every endpoint's gate (Public ones flagged), registered policies, throttle locks with Unlock — and looks up a user's sessions and keys, each with a Revoke button.
nexus auth check [nexus.toml] validates [auth] the way boot does — an unknown key, a scheme type nexus doesn't have, a jwt scheme without a key, a duration like "30d" (Go durations stop at hours: write "720h") — and prints the effective setup: schemes in the order they are tried, the default gate, pages and areas, endpoints, and the session, throttle and password rules.
Testing
import "github.com/paulmanoni/nexus/v2/extension/auth/authtest"
users := authtest.NewUsers().
Add(auth.Identity{ID: "7", Kind: "staff", Perms: []string{"orders.*"}}, "ana@example.com", "a long password")
app := nexustest.New(t, config.Runtime{}, auth.Module(auth.Config{Users: auth.StaticUsers(users)}), orders.Module)
app.GET("/admin/orders").AssertStatus(401)
app.With(authtest.As(&auth.Identity{ID: "1", Kind: "staff", Perms: []string{"orders.view"}})).
GET("/admin/orders").AssertOK()
app.With(authtest.AsUser("7")).GET("/admin/orders").AssertOK() // loaded through Usersauthtest.As and AsUser return a header the auth middleware honours only in a test binary, so every gate, area rule and policy runs as for a real sign-in. authtest.Users is an in-memory Users (with SetPassword) for tests and examples. nexustest's App.With(header) sends any header with every request.
Throttling sign-ins
auth.Login counts failures — per account, and per client IP (nexus.ClientIP, which honours trusted proxies) — and answers 429 "too many failed sign-ins" past the limit:
[auth.throttle]
account = "5/15m" # failures per account in a window; "off" disables
ip = "50/15m" # failures per client IP
lockout = "15m" # how long an account stays locked at its limitThe counters live in the process, so each replica counts on its own; set Config.Throttle: auth.CacheThrottle(cache) to share them through Redis. A 429 carries Retry-After.
Built-in endpoints
[auth.endpoints]
login = "/api/auth/login" # POST {login, password, next?, scheme?} → Credential
logout = "/api/auth/logout" # POST
me = "/api/auth/me" # GET {user, can}Each is mounted only when its path is set, and they're tagged for the client SDK's nx.auth.login/logout/me. me answers for anonymous visitors too ("user": null). user is what an optional Public(id *auth.Identity) any method on your Users returns — {id, kind} without one, so Identity.User is never sent by accident. can is auth.OpGates; on this path it is false for any op the visitor couldn't call, signed in or not.
Gates
Gates work the same on REST, GraphQL and WebSocket:
nexus.AsMutation(NewCreateOrder,
auth.Required(), // 401 without an identity
auth.Requires("orders:create"), // 403 without the permission
)Deny by default. Every endpoint, page, view and live page requires a sign-in unless it opts out —
[auth] default = "public"turns that around:gonexus.AsRest("GET", "/health", NewHealth, auth.Public())Permissions and kinds on the identity.
Identity.Permsis matched with wildcards —orders.*grantsorders.viewandorders.refunds.create,*grants everything — andIdentity.Kindsays which kind of user it is ("staff", "customer"). Roles are your concept:Users.Loadexpands them intoPerms.At least one, and user kinds.
auth.RequiresAnypasses with any one of its permissions;auth.Kindgates on the identity's kind. Both imply sign-in and combine withRequires—Kindcovers what a path prefix can't, such as one/graphqlmount serving staff and customers:gonexus.AsMutation((*Orders).Refund, auth.Kind("staff"), auth.RequiresAny("orders.refund", "orders.admin"), )Decorator form. The same gates attach as
//nexus:authmodifiers — bare tokens, capability case-insensitive:go//nexus:mutation //nexus:auth Requires orders:create func NewCreateOrder(...) (...) //nexus:mutation //nexus:auth Kind staff //nexus:auth RequiresAny orders.refund orders.admin func (o *Orders) Refund(...) (...) //nexus:rest GET /health //nexus:auth Public func NewHealth(...) (...)See
//nexus:decorators.
Who is calling
me := auth.Current(ctx) // *Identity, nil when anonymous
user, ok := auth.User[MyUser](ctx) // Identity.User, typed
uid, ok := auth.ID[uint](ctx) // Identity.ID parsed into TOr declare it as a handler parameter — *auth.Identity is the caller (nil when anonymous), auth.Identity requires a sign-in (401 without one):
func (s *Orders) Refund(ctx context.Context, me auth.Identity, in RefundIn) (*Order, error)Any package can add such a parameter type with nexus.RequestParam[T](fill).
UI permissions that can't drift
auth.Can(ctx, "users:delete") and auth.Gates(ctx, ...) use the same rules as Requires. auth.OpGates(ctx, app) goes further. It answers map[opName]bool for every registered op, so the frontend asks by the op names it already calls (can.deleteUser), and no permission string exists outside the registration:
inertia.ShareProvide(func(app *nexus.App) inertia.SharedProvider {
return func(ctx context.Context) (string, any) { return "can", auth.OpGates(ctx, app) }
})OpGates evaluates RequiresAny and Kind gates too. The gate table is compiled once and grouped by permission set. It costs about 4µs for 200 ops, so it is safe on every render.
Passwords
auth.Login checks passwords with the [auth.passwords] hashers, and auth.SetPassword hashes and stores new ones after checking the rules:
[auth.passwords]
hashers = ["bcrypt", "argon2id", "pbkdf2"] # the first hashes new passwords; all verify
min_length = 8
common = true # refuse common passwords
numeric = true # refuse all-digit passwords
similar = true # refuse passwords like the user's id or loginHashes describe their own algorithm (bcrypt$…), so a password stored with another listed hasher still verifies and is rehashed on its next sign-in (through SetPassword on your Users). auth.Hashers, auth.BCrypt()/Argon2id()/PBKDF2() and auth.ValidatePassword are there for code of your own, such as a seed script.
See also: Web security for CSRF and headers, and Sessions for server-side sessions.