Complete Setup Example

The flagship 5-line-integration example. It shows how securityhttp.NewHandler assembles the entire security middleware chain — secure headers, session-backed authentication, CSRF, default-deny authorization, and a JSON login endpoint — around a plain application handler, with secure defaults and fail-loud validation.

go run ./examples/securityhttp

The five lines

handler, err := securityhttp.NewHandler(app,
    securityhttp.WithSessionStore(store, users),
    securityhttp.WithLogin("/login", manager),
    securityhttp.WithAuthorize(authz.Routes(
        authz.Match("/admin/**").HasRole("ADMIN"),
        authz.AnyRequest().Authenticated(),
    )),
)

CSRF is on by default (synchronizer token, session-backed), security headers are on, the session cookie is Secure+HttpOnly+SameSite=Lax, and authorization is default-deny (AnyRequest().Authenticated()) — none of which the integrator has to remember to enable.

Full source

package main

import (
    "log"
    "net/http"

    "github.com/thuongh2/go-security/authn"
    "github.com/thuongh2/go-security/authz"
    "github.com/thuongh2/go-security/core"
    "github.com/thuongh2/go-security/crypto/password"
    "github.com/thuongh2/go-security/securityhttp"
    "github.com/thuongh2/go-security/web/session"
)

func main() {
    // --- user store, encoder, provider, manager ----------------------------
    encoder := password.NewBcryptEncoder(password.DefaultBcryptCost)
    adminHash, _ := encoder.Encode("s3cret")
    userHash, _ := encoder.Encode("hunter2")

    users := authn.NewInMemoryUserService()
    users.Add(authn.User{
        Username:     "alice",
        PasswordHash: adminHash,
        Authorities:  core.Roles("ADMIN"),
    })
    users.Add(authn.User{
        Username:     "bob",
        PasswordHash: userHash,
        Authorities:  core.Roles("USER"),
    })
    manager := authn.NewManager([]authn.Provider{
        authn.NewPasswordProvider(users, encoder),
    })

    // --- session store ------------------------------------------------------
    store := session.NewMemoryStore(session.Options{})

    // --- the application handler the security chain protects ----------------
    app := http.NewServeMux()
    app.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        auth := core.MustAuthentication(r.Context())
        _, _ = w.Write([]byte("hello " + auth.Name()))
    })
    app.HandleFunc("/admin/panel", func(w http.ResponseWriter, r *http.Request) {
        _, _ = w.Write([]byte("admin panel"))
    })

    // --- the 5-line integration: assemble the secured handler ---------------
    handler, err := securityhttp.NewHandler(app,
        securityhttp.WithSessionStore(store, users),
        securityhttp.WithLogin("/login", manager),
        securityhttp.WithAuthorize(authz.Routes(
            authz.Match("/admin/**").HasRole("ADMIN"),
            authz.AnyRequest().Authenticated(),
        )),
    )
    if err != nil {
        log.Fatalf("assemble security chain: %v", err)
    }

    log.Println("listening on :8443 (use TLS in production; cookies are Secure by default)")
    if err := http.ListenAndServe(":8443", handler); err != nil {
        log.Fatal(err)
    }
}

The example listens on :8443 (see http.ListenAndServe(":8443", handler)), served over plain HTTP for local testing — no TLS certificate is configured in this example. Because the session cookie defaults to Secure, a browser will not send it back over plain HTTP; use curl, which doesn’t enforce that, or configure TLS termination for a real deployment.

Trying it out

curl -i http://localhost:8443/
# → 401 (default-deny: AnyRequest().Authenticated(), no session yet)

curl -i -X POST http://localhost:8443/login \
     -H 'Content-Type: application/json' \
     -d '{"username":"alice","password":"s3cret"}'
# → 403 Forbidden: invalid CSRF token

Verified by running the example: that second command returns 403, not a successful login. WithAuthorize() here is AnyRequest().Authenticated() with no PermitAll carve-out for /login, and CSRF defaults to the session-backed synchronizer token — but nothing in this exact five-line configuration ever creates a session or issues a token before login, because every anonymous request (including GET / and GET /login) is already denied by the authz leg. There is no bare-curl path through this literal configuration that reaches the login handler.To see the chain’s pieces work end-to-end against real HTTP requests, use examples/playground or examples/webapp instead — both add an explicit PermitAll (or an unguarded mux) for the login path, and playground pairs it with a double-submit CSRF repository that doesn’t need a pre-existing session. To exercise this exact configuration, either add authz.Match("/login").PermitAll() to authz.Routes(...), or see securityhttp_test.go’s TestIntegration_CookieSecureDefaults, which drives the login handler directly with securityhttp.CSRFDisabled() and securityhttp.AllowLoginWithoutCSRF().

Once a session exists (e.g. by adjusting the authorize rules as above, or in a test that seeds one directly), the rest of the chain behaves as documented:

curl -b jar.txt http://localhost:8443/
# → hello alice

curl -b jar.txt http://localhost:8443/admin/panel
# → admin panel  (alice holds ROLE_ADMIN)

curl -b jar2.txt http://localhost:8443/admin/panel
# → 403 (a session authenticated as bob, who lacks ROLE_ADMIN)

What you get for free

X-Content-Type-Options: nosniff, X-Frame-Options: DENY, and the other security-header defaults on every response
Session cookie with Secure; HttpOnly; SameSite=Lax
CSRF synchronizer token (session-backed) protecting every unsafe request
Default-deny authorization: AnyRequest().Authenticated() means an unmatched path requires a session, not open access
Session fixation protection: the session ID rotates on login
Fail-loud assembly: New() or NewHandler() — a misconfigured chain (e.g. no terminal authorization rule) errors at startup, not at request time

​The five lines

​Full source

​Trying it out

​What you get for free

The five lines

Full source

Trying it out

What you get for free