Login & Logout

The web/auth package provides the JSON login and logout handlers, plus MFA, magic-link, and passkey HTTP flows. Every handler is built the same way: construct a *Config struct and pass it to a constructor function that returns an http.Handler. There are no functional options (WithX(...)) — all configuration is struct fields, with a Manager/Store (or equivalent) required and everything else defaulted.

Import

import "github.com/thuongh2/go-security/web/auth"

The internal sequence — including the session-fixation protection folded in after credential validation:

loginHandler := auth.LoginHandler(auth.LoginConfig{
    Manager: manager,                      // *authn.Manager (required)
    Store:   store,                        // session.Store (required)
    Cookie:  session.DefaultCookieConfig(),
})
mux.Handle("POST /login", loginHandler)

LoginConfig.Manager and .Store are required — LoginHandler panics at construction time if either is nil. Session-fixation protection runs on every successful login (a pre-auth session is migrated to a fresh id, never reused).

Request format

Only a JSON body is accepted — there is no application/x-www-form-urlencoded support.

POST /login
Content-Type: application/json

{"username": "alice", "password": "s3cret"}

Success response (default)

HTTP/1.1 200 OK
Set-Cookie: SESSION=...; Path=/; Secure; HttpOnly; SameSite=Lax
Content-Type: application/json

{"authenticated": true}

Failure response (default)

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{"error": "bad credentials"}

LoginConfig fields

Field	Description
`Manager`	Authenticates the submitted credentials (required)
`Store`	Mints/migrates the post-login session (required)
`Cookie`	`session.CookieConfig`; zero value is insecure — use `session.DefaultCookieConfig()`
`RememberMe`	`rememberme.Service`; when set and the request opts in, issues a remember-me cookie
`OnSuccess`	Custom success handler. Default: 200 + `{"authenticated":true}`. Use this for a redirect instead of JSON — there is no built-in `WithSuccessRedirect`
`OnFailure`	Custom failure handler. Default: 401 + `{"error":"bad credentials"}`. Use this to change the status code — there is no built-in `WithFailureStatus`
`UsernameField` / `PasswordField`	JSON field names. Default `"username"` / `"password"`
`RememberMeField`	JSON field for remember-me opt-in. Default `"remember-me"`
`MaxBodyBytes`	Caps the request body. Default 4096; an oversized body gets 413

There is no built-in login rate limiter — front the handler with ratelimit.LoginThrottle yourself (this is what securityhttp.WithLoginThrottle wires up).

Logout handler

logoutHandler := auth.LogoutHandler(auth.LogoutConfig{
    Store:  store,
    Cookie: session.DefaultCookieConfig(),
})
mux.Handle("POST /logout", logoutHandler)

LogoutConfig.Store is required (panics if nil). Logout is POST-only (a GET gets 405) and idempotent — an absent or invalid session still clears cookies and returns success.

What happens

Session is invalidated (store.Delete(sessionID)), best-effort
Session cookie is cleared
Remember-me cookie is cleared, if LogoutConfig.RememberMe is set
Response: 200 JSON {"loggedOut": true} (note the field is loggedOut, not logout) — override with LogoutConfig.OnLogout

CSRF is not checked by the handler itself; if you front it with web/csrf.Middleware (or securityhttp.New/NewHandler, which enables CSRF by default once a session store is configured) requests need a valid X-CSRF-Token — see csrf.

MFA handlers

Two-step login: MFALoginHandler runs the primary credential and begins the challenge; MFAStepHandler completes it. Both take an authn.MFAManager (see authn for MFAManagerConfig, MFAFactor, and MFAPolicy).

mfaManager := authn.NewMFAManager(authn.MFAManagerConfig{
    Store:   authn.NewMemoryMFAStore(),
    Factors: map[string]authn.MFAFactor{"totp": totpFactor}, // totpFactor: see the authn page's MFAFactor example
    Policy:  authn.NewFixedMFAPolicy("totp"),
})

mux.Handle("POST /mfa/login", auth.MFALoginHandler(auth.MFAConfig{
    Primary:    manager,     // primary (e.g. password) authn.Manager
    MFAManager: mfaManager,
    Store:      store,
    Cookie:     session.DefaultCookieConfig(),
    FactorType: "totp",
}))
mux.Handle("POST /mfa/step", auth.MFAStepHandler(auth.MFAConfig{
    MFAManager: mfaManager,
    Store:      store,
    Cookie:     session.DefaultCookieConfig(),
    FactorType: "totp",
}))

MFALoginHandler panics if Primary, MFAManager, or Store is nil. MFAStepHandler panics if MFAManager or Store is nil (it does not use Primary).

POST /mfa/login  {"username":"alice","password":"s3cret"}
→ 200 {"mfaRequired": true, "factorType": "totp"}   (sets session cookie)

POST /mfa/step   {"code":"123456"}   (with the session cookie from above)
→ 200 {"authenticated": true}                        (all factors satisfied)
→ 200 {"mfaRequired": true, "pending": true}          (more factors remain)
→ 401 {"error":"bad credentials"}                     (wrong code)

Magic link handlers

Issue and consume single-use authentication links via authn.MagicLinkStore (see authn):

store := authn.NewMemoryMagicLinkStore()
manager := authn.NewManager([]authn.Provider{
    authn.NewMagicLinkProvider(store, authn.MagicLinkWithUserService(users)),
})

mux.Handle("POST /auth/magic", auth.MagicLinkRequestHandler(auth.MagicLinkConfig{
    Store:    store,
    Sender:   emailSender,       // implements authn.MagicLinkSender
    LinkBase: "https://app.example.com/auth/magic/verify",
}))
mux.Handle("GET /auth/magic/verify", auth.MagicLinkVerifyHandler(auth.MagicLinkConfig{
    Store:   store,
    Manager: manager,
    Session: sessionStore, // session.Store for the post-login session
    Cookie:  session.DefaultCookieConfig(),
}))

emailSender is anything implementing authn.MagicLinkSender:

type emailSender struct{ /* SMTP client, etc. */ }

func (s emailSender) Send(ctx context.Context, identifier, magicLinkURL string) error {
    // deliver magicLinkURL to identifier
    return nil
}

MagicLinkRequestHandler requires Store and Sender. MagicLinkVerifyHandler requires Store, Manager, and Session.

POST /auth/magic  {"email":"alice@example.com"}
→ 202 {"message":"magic link sent"}   (always 202, even for unknown identifiers — anti-enumeration)

GET /auth/magic/verify?token=<raw-token>
→ 200 {"authenticated": true}          (sets session cookie)
→ 401 {"error":"invalid or expired link"}

Passkey handlers

WebAuthn registration and assertion (sign-in), backed by an authn.PasskeyAuthenticator you implement (see authn):

cfg := auth.PasskeyConfig{
    Authenticator: webAuthnAuthenticator, // your authn.PasskeyAuthenticator
    Session:       store,
    Cookie:        session.DefaultCookieConfig(),
    GetUserHandle: getUserHandle,
}

// Sign-in (assertion) — no prior authentication required
mux.Handle("POST /passkey/assertion/begin", auth.PasskeyAssertionBeginHandler(cfg))
mux.Handle("POST /passkey/assertion/finish", auth.PasskeyAssertionFinishHandler(cfg))

// Registration — the request MUST already be authenticated
mux.Handle("POST /passkey/register/begin", auth.PasskeyRegistrationBeginHandler(cfg))
mux.Handle("POST /passkey/register/finish", auth.PasskeyRegistrationFinishHandler(cfg))

GetUserHandle extracts the WebAuthn user handle for the current caller and is required by both registration handlers:

func getUserHandle(r *http.Request) ([]byte, error) {
    a, ok := core.AuthenticationFrom(r.Context())
    if !ok || !a.Authenticated() {
        return nil, errors.New("unauthenticated")
    }
    return []byte(a.Name()), nil
}

Mount the registration routes behind session or bearer auth middleware so core.AuthenticationFrom resolves — the handlers return 401 otherwise.

POST /passkey/assertion/begin   {"userHandle":"<base64url, optional>"}
→ 200 <PublicKeyCredentialRequestOptions JSON, from the authenticator>

POST /passkey/assertion/finish  <raw WebAuthn assertion response JSON>
→ 200 {"authenticated": true}    (sets session cookie)
→ 401 {"error":"bad credentials"}

POST /passkey/register/begin    (authenticated)
→ 200 <PublicKeyCredentialCreationOptions JSON, from the authenticator>

POST /passkey/register/finish   <raw WebAuthn registration response JSON>
→ 200 {"registered": true, "credentialId": "<base64url>"}
→ 400 {"error":"registration failed"}

Foundation

Authentication

Authorization

Session & Cookies

OAuth2 & JWT

HTTP Layer

Resilience

Observability

Distributed Stores

Import

Request format

Success response (default)

Failure response (default)

LoginConfig fields

Logout handler

What happens

MFA handlers

Magic link handlers

Passkey handlers

​Import

​Login handler

​Request format

​Success response (default)

​Failure response (default)

​LoginConfig fields

​Logout handler

​What happens

​MFA handlers

​Magic link handlers

​Passkey handlers

Import

Login handler

Request format

Success response (default)

Failure response (default)

LoginConfig fields

Logout handler

What happens

MFA handlers

Magic link handlers

Passkey handlers