Framework Integration

Five programs, one app. Each serves identical routes with identical security options; the only difference is how that framework’s router is attached to the go-security chain. Because every leg of the chain is a func(http.Handler) http.Handler and securityhttp.NewHandler returns a single http.Handler, four of the five need no adapter at all.

cd examples/frameworks
go run ./gin     # or ./echo, ./chi, ./mux, ./fiber

These live in a separate Go module (replaced onto the parent) so Gin, Echo, chi, gorilla/mux, and Fiber never enter the library’s dependency graph — the root module stays standard library plus golang.org/x/crypto.For the full integration reference — support matrix, per-route middleware adapters, role-hierarchy caveats — see the Web Frameworks guide.

The integration story, end to end

app.go holds everything the five programs share: two in-memory users (alice/ADMIN, bob/USER), a session store, cookies, and the securityhttp option list.
Each main.go builds its framework’s router and registers four routes.
The chain wraps the whole router — securityhttp.NewHandler(router, opts...) — so headers, session lookup, CSRF, and default-deny authorization run before the framework routes anything.
Admin access is enforced inside each framework’s own route group, so both enforcement layers appear in one program.

Route	Access
`GET /csrf`	anonymous — issues the CSRF token
`POST /login`	anonymous — JSON form login mounted by `WithLogin`
`GET /`	any authenticated user
`GET /admin/panel`	`ROLE_ADMIN`, enforced by the framework route group

Shared security options

// Options is the securityhttp option list every example passes to New or
// NewHandler.
func (d Deps) Options() []securityhttp.Option {
    return []securityhttp.Option{
        securityhttp.WithSessionStore(d.Store, d.Users, d.Cookie),
        securityhttp.WithLogin("/login", d.Manager),
        securityhttp.WithCSRF(csrf.NewDoubleSubmitRepository(d.CSRFCookie)),
        securityhttp.WithAuthorize(authz.Routes(
            authz.Match("/login").PermitAll(),
            authz.Match("/csrf").PermitAll(),
            authz.AnyRequest().Authenticated(),
        )),
    }
}

Two deliberate choices. CSRF uses the double-submit-cookie repository instead of the session-backed synchronizer default, because the login POST happens before any session exists for a synchronizer token to live in. And there is no /admin rule here — that check belongs to the framework groups below. Route patterns are matched against the raw request path, before your framework parses path parameters, so write them as paths (/admin/**) and never as route templates (/users/:id, /users/{id}) — those strings never appear in a URL.

One line per framework

r := gin.New()
r.GET("/csrf", func(c *gin.Context) {
    c.String(http.StatusOK, frameworks.CSRFToken(c.Request.Context()))
})
r.GET("/", func(c *gin.Context) {
    c.String(http.StatusOK, "hello "+frameworks.Principal(c.Request.Context()))
})

// Per-route enforcement via the secure() adapter below.
admin := r.Group("/admin", secure(secmw.RequireRole("ADMIN")))
admin.GET("/panel", func(c *gin.Context) {
    c.String(http.StatusOK, "admin panel")
})

handler, err := securityhttp.NewHandler(r, d.Options()...)

e := echo.New()
e.GET("/csrf", func(c echo.Context) error {
    return c.String(http.StatusOK, frameworks.CSRFToken(c.Request().Context()))
})
e.GET("/", func(c echo.Context) error {
    return c.String(http.StatusOK, "hello "+frameworks.Principal(c.Request().Context()))
})

// Echo ships the adapter.
admin := e.Group("/admin", echo.WrapMiddleware(secmw.RequireRole("ADMIN")))
admin.GET("/panel", func(c echo.Context) error {
    return c.String(http.StatusOK, "admin panel")
})

handler, err := securityhttp.NewHandler(e, d.Options()...)

r := chi.NewRouter()
r.Get("/csrf", func(w http.ResponseWriter, r *http.Request) {
    _, _ = w.Write([]byte(frameworks.CSRFToken(r.Context())))
})
r.Get("/", func(w http.ResponseWriter, r *http.Request) {
    _, _ = w.Write([]byte("hello " + frameworks.Principal(r.Context())))
})

// chi.Router.Use takes exactly func(http.Handler) http.Handler — no adapter.
r.Route("/admin", func(r chi.Router) {
    r.Use(secmw.RequireRole("ADMIN"))
    r.Get("/panel", func(w http.ResponseWriter, _ *http.Request) {
        _, _ = w.Write([]byte("admin panel"))
    })
})

handler, err := securityhttp.NewHandler(r, d.Options()...)

r := mux.NewRouter()
r.HandleFunc("/csrf", func(w http.ResponseWriter, r *http.Request) {
    _, _ = w.Write([]byte(frameworks.CSRFToken(r.Context())))
}).Methods(http.MethodGet)
r.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
    _, _ = w.Write([]byte("hello " + frameworks.Principal(r.Context())))
}).Methods(http.MethodGet)

// MiddlewareFunc is a named func(http.Handler) http.Handler — a type conversion.
admin := r.PathPrefix("/admin").Subrouter()
admin.Use(mux.MiddlewareFunc(secmw.RequireRole("ADMIN")))
admin.HandleFunc("/panel", func(w http.ResponseWriter, _ *http.Request) {
    _, _ = w.Write([]byte("admin panel"))
}).Methods(http.MethodGet)

handler, err := securityhttp.NewHandler(r, d.Options()...)

// Fiber is fasthttp, so there is no http.Handler to wrap: New, not NewHandler.
chain, err := securityhttp.New(d.Options()...)
if err != nil {
    log.Fatalf("assemble security chain: %v", err)
}

app := fiber.New(fiber.Config{DisableStartupMessage: true})
app.Use(adaptor.HTTPMiddleware(chain.Then)) // Chain.Then already has the right shape

// securityhttp.New mounts no login endpoint — mount web/auth's handler yourself.
app.Post("/login", adaptor.HTTPHandler(auth.LoginHandler(auth.LoginConfig{
    Manager: d.Manager,
    Store:   d.Store,
    Cookie:  d.Cookie,
})))

app.Get("/csrf", func(c *fiber.Ctx) error {
    return c.SendString(frameworks.CSRFToken(c.Context()))
})
app.Get("/", func(c *fiber.Ctx) error {
    return c.SendString("hello " + frameworks.Principal(c.Context()))
})

admin := app.Group("/admin", adaptor.HTTPMiddleware(secmw.RequireRole("ADMIN")))
admin.Get("/panel", func(c *fiber.Ctx) error {
    return c.SendString("admin panel")
})

Then serve it like any handler (Fiber uses app.Listen instead):

if err != nil {
    log.Fatalf("assemble security chain: %v", err)
}
log.Fatal(http.ListenAndServe(":8080", handler))

frameworks.Principal(ctx) is just core.MustAuthentication(ctx).Name() — the authentication lives on the request context, so only the way each framework hands you that context differs.

Gin’s middleware adapter

Gin has gin.WrapH for handlers but nothing for middleware, so the Gin example carries a ten-line adapter:

// secure adapts a net/http middleware to a gin.HandlerFunc.
func secure(mw func(http.Handler) http.Handler) gin.HandlerFunc {
    return func(c *gin.Context) {
        passed := false
        next := http.HandlerFunc(func(_ http.ResponseWriter, r *http.Request) {
            passed = true
            c.Request = r // carries the authentication context
        })
        mw(next).ServeHTTP(c.Writer, c.Request)
        if !passed {
            c.Abort() // the middleware answered (401/403) — do not run the handler
            return
        }
        c.Next()
    }
}

Both lines matter. Without c.Request = r, any context the middleware added is lost downstream. Without c.Abort(), a denied request still reaches your handler, which writes a 200 body over the 403 — a fail-open bug. gin/main_test.go pins both behaviours.

Why Fiber differs

*fiber.App is not an http.Handler, so the chain is mounted as Fiber middleware and the login endpoint is mounted by hand. Reading the principal still works: the adaptor copies the request-context values into fasthttp user values, and *fasthttp.RequestCtx — what c.Context() returns — is itself a context.Context whose Value reads them back.

Trying it out

Same transcript against every one of the five:

tok=$(curl -s -c jar http://localhost:8080/csrf)

curl -s -b jar -c jar -X POST http://localhost:8080/login \
     -H 'Content-Type: application/json' -H "X-CSRF-Token: $tok" \
     -d '{"username":"alice","password":"s3cret"}'   # {"authenticated":true}

curl -s -b jar http://localhost:8080/                # hello alice
curl -s -b jar http://localhost:8080/admin/panel     # admin panel
curl -s -o /dev/null -w '%{http_code}' http://localhost:8080/   # 401 (anonymous)

Log in as bob/hunter2 instead and /admin/panel returns 403 — the framework route group rejects a caller without ROLE_ADMIN. Posting to /login with no X-CSRF-Token returns 403 on all five, and every response carries the default security headers.

Role hierarchy caveat

middleware.RequireRole is a literal authority check — it consults no role hierarchy. Under ADMIN > STAFF > USER, an ADMIN caller is denied by RequireRole("STAFF"). For a hierarchy-aware per-route guard, use a scoped rule set (also middleware, so it drops into the same adapters):

adminGuard, err := authz.Routes(
    authz.WithHierarchy(hierarchy),
    authz.AnyRequest().HasRole("STAFF"),
)

Details and the chain-level alternative: Web Frameworks → Role hierarchy in per-route checks.

What these examples prove

One securityhttp.NewHandler call secures Gin, Echo, chi, and gorilla/mux identically — no framework-specific package, no adapter
Framework-native route groups compose with go-security’s guards in every framework, including Fiber
The authentication is reachable from every framework’s handler, because it travels on the request context
The cookies here are Secure: false so the examples work over plain HTTP on localhost. In production keep the secure defaults and serve TLS.

​The integration story, end to end

​Shared security options

​One line per framework

​Gin’s middleware adapter

​Why Fiber differs

​Trying it out

​Role hierarchy caveat

​What these examples prove

The integration story, end to end

Shared security options

One line per framework

Gin’s middleware adapter

Why Fiber differs

Trying it out

Role hierarchy caveat

What these examples prove