Web Frameworks - go-security

go-security is net/http middleware: every leg of the chain is a func(http.Handler) http.Handler, and securityhttp.NewHandler returns a single http.Handler. Any Go router that implements http.Handler — which is nearly all of them — therefore integrates in one line, with no adapter and no framework-specific package to install.

handler, err := securityhttp.NewHandler(router, opts...) // router = *gin.Engine, *echo.Echo, *chi.Mux, *mux.Router, *http.ServeMux…

Support matrix

Framework	Router is an `http.Handler`	Wrap the whole app	Per-route middleware
`net/http` `ServeMux`	yes	`securityhttp.NewHandler(mux, …)`	`chain.Then(h)` per handler
chi	yes	`securityhttp.NewHandler(r, …)`	`r.Use(mw)` — same signature
gorilla/mux	yes	`securityhttp.NewHandler(r, …)`	`r.Use(mux.MiddlewareFunc(mw))`
httprouter	yes	`securityhttp.NewHandler(r, …)`	wrap the handler: `mw(h)`
Echo	yes	`securityhttp.NewHandler(e, …)`	`echo.WrapMiddleware(mw)`
Gin	yes	`securityhttp.NewHandler(r, …)`	10-line adapter (below)
Fiber	no (fasthttp)	`adaptor.HTTPMiddleware(chain.Then)`	`adaptor.HTTPMiddleware(mw)`

Pattern 1 — wrap the router (recommended)

The security chain sits outside the framework’s router, so it runs before routing happens. That is what you want: security headers, CORS, rate limiting, session lookup, CSRF, and default-deny authorization all apply to every request, including the ones your router has no route for. It is also the only way to get the login endpoint securityhttp.WithLogin mounts.

r := gin.New()
r.GET("/", func(c *gin.Context) {
    c.String(http.StatusOK, "hello "+core.MustAuthentication(c.Request.Context()).Name())
})

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

e := echo.New()
e.GET("/", func(c echo.Context) error {
    return c.String(http.StatusOK, "hello "+core.MustAuthentication(c.Request().Context()).Name())
})

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

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

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

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

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

Then serve it like any handler:

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

Route patterns in authz.Match are matched against the raw request path, before your framework parses path parameters. Write them as paths (/admin/**, /api/v1/**), not as framework route templates (/users/:id, /users/{id}) — those template strings never appear in a request URL.

Pattern 2 — middleware inside the framework

Chain-level authz.Match rules cover most needs, but sometimes you want the guard next to the route, in the framework’s own idiom (r.Group, e.Group, r.Route). Every guard in web/middleware — RequireAuthenticated, RequireRole, RequireAuthority, BasicAuth — is a plain net/http middleware, so it composes with whatever adapter the framework offers. Use both layers together: keep the chain outside (headers, session, CSRF, default-deny) and add per-route role checks inside.

chi and gorilla/mux

Both are net/http-native, so the middleware is used as-is:

// chi
r.Route("/admin", func(r chi.Router) {
    r.Use(middleware.RequireRole("ADMIN"))
    r.Get("/panel", panelHandler)
})

// gorilla/mux — MiddlewareFunc is a named func(http.Handler) http.Handler
admin := r.PathPrefix("/admin").Subrouter()
admin.Use(mux.MiddlewareFunc(middleware.RequireRole("ADMIN")))

Echo

Echo ships the adapter:

admin := e.Group("/admin", echo.WrapMiddleware(middleware.RequireRole("ADMIN")))

echo.WrapMiddleware puts the request the middleware passed down back on the Echo context, so handlers downstream see the authentication.

Gin

Gin has gin.WrapH for handlers but no wrapper for middleware, so write the adapter once:

// 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()
    }
}

admin := r.Group("/admin", secure(middleware.RequireRole("ADMIN")))

Both details matter. Skip c.Request = r and any context the middleware added is lost downstream. Skip c.Abort() and a denied request still reaches your handler, which then writes a 200 body after the 401 — a fail-open bug.

Role hierarchy in per-route checks

middleware.RequireRole / RequireAuthority are literal authority checks — they compare what the principal holds against what you asked for, and consult no role hierarchy. Under ADMIN > STAFF > USER, an ADMIN caller is denied by middleware.RequireRole("STAFF"). Chain-level rules are hierarchy-aware, because WithHierarchy is a Routes() option:

securityhttp.WithAuthorize(authz.Routes(
    authz.WithHierarchy(hierarchy),          // ADMIN implies STAFF implies USER
    authz.Match("/admin/**").HasRole("STAFF"),
    authz.AnyRequest().Authenticated(),
))

If you want the hierarchy-aware check next to the route instead, build a scoped single-rule rule set — authz.Routes returns ordinary middleware, so it goes through the same adapters as everything above (AnyRequest here means “any request that reaches this group”):

adminGuard, err := authz.Routes(
    authz.WithHierarchy(hierarchy),
    authz.AnyRequest().HasRole("STAFF"),
)
if err != nil {
    log.Fatalf("admin guard: %v", err)
}

admin := r.Group("/admin", secure(adminGuard))         // Gin
admin := e.Group("/admin", echo.WrapMiddleware(adminGuard)) // Echo
r.Route("/admin", func(r chi.Router) { r.Use(adminGuard) })  // chi

authz.Guard is the third option, but it is not middleware — it returns func(ctx, target) error for service-layer calls, where the decision depends on the domain object rather than the path.

Reading the principal

The authentication lives on the request context, so it is always core.MustAuthentication(ctx) — only the way to reach ctx differs:

Framework	Context accessor
net/http, chi, gorilla/mux, httprouter	`r.Context()`
Gin	`c.Request.Context()`
Echo	`c.Request().Context()`
Fiber	`c.Context()`

auth := core.MustAuthentication(ctx)
auth.Name()                                     // principal name
auth.Authenticated()                            // false for the anonymous token
core.HasAuthority(auth.Authorities(), core.RoleAuthority("ADMIN"))

Fiber

Fiber runs on fasthttp, not net/http, so *fiber.App is not an http.Handler and securityhttp.NewHandler cannot wrap it. Use securityhttp.New to get the chain and mount it with Fiber’s adaptor — middleware.Chain.Then already has the func(http.Handler) http.Handler shape adaptor.HTTPMiddleware expects:

chain, err := securityhttp.New(opts...)
if err != nil {
    log.Fatalf("assemble security chain: %v", err)
}

app := fiber.New()
app.Use(adaptor.HTTPMiddleware(chain.Then))

// securityhttp.New does not mount a login endpoint (it has no handler to wrap),
// so mount web/auth's handler yourself.
app.Post("/login", adaptor.HTTPHandler(auth.LoginHandler(auth.LoginConfig{
    Manager: manager,
    Store:   store,
    Cookie:  cookie,
})))

app.Get("/", func(c *fiber.Ctx) error {
    return c.SendString("hello " + core.MustAuthentication(c.Context()).Name())
})

core.MustAuthentication(c.Context()) works because 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.

Every other fasthttp-based framework (Atreugo, fasthttp-routing) has the same constraint and the same fix: bridge with an adaptor, and remember that any security middleware you skip on that path is simply not running.

Runnable examples

The repository ships one small program per framework — same routes, same security options, only the framework wiring differs — in a separate Go module so the library itself keeps its standard-library-plus-x/crypto dependency guarantee:

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

→ Framework integration walkthrough Each serves GET / (any authenticated user), GET /admin/panel (ADMIN, enforced by the framework’s own route group), GET /csrf, and the POST /login endpoint:

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"}'
curl -s -b jar http://localhost:8080/             # hello alice
curl -s -b jar http://localhost:8080/admin/panel  # admin panel

The examples set Secure: false on their cookies so they work over plain HTTP on localhost. In production keep the secure defaults and serve TLS.

​Support matrix

​Pattern 1 — wrap the router (recommended)

​Pattern 2 — middleware inside the framework

​chi and gorilla/mux

​Echo

​Gin

​Role hierarchy in per-route checks

​Reading the principal

​Fiber

​Runnable examples

Support matrix

Pattern 1 — wrap the router (recommended)

Pattern 2 — middleware inside the framework

chi and gorilla/mux

Echo

Gin

Role hierarchy in per-route checks

Reading the principal

Fiber

Runnable examples