middlewares

Documentation

Overview

Package middlewares provides reusable Gin security middleware for the security module.

It includes:

• JWT Bearer authentication middleware
• cookie-based JWT authentication middleware
• common HTTP security headers

The authentication middlewares validate the incoming token, decode claims, and store both the parsed token and the claims in the Gin context so handlers can consume them without repeating auth logic.

Main entry points:

• RequireJWT for Authorization header validation
• RequireJWTCookie for cookie-based token validation
• SecurityHeaders for standard defensive HTTP headers

Index

• Variables
• func RequireJWT(options ...JWTMiddlewareOption) gin.HandlerFunc
• func RequireJWTCookie(options ...CookieMiddlewareOption) gin.HandlerFunc
• func SecurityHeaders() gin.HandlerFunc
• type ClaimsFactory
• type CookieMiddlewareOption
  • func WithJWTCookieClaimsFactory(factory ClaimsFactory) CookieMiddlewareOption
  • func WithJWTCookieContextKeys(tokenKey GinContextKey, claimsKey GinContextKey) CookieMiddlewareOption
  • func WithJWTCookieServiceConfig(input cookiesauth.ConfigServiceInput) CookieMiddlewareOption
  • func WithJWTCookieUnauthorizedHandler(handler func(*gin.Context, error)) CookieMiddlewareOption
  • func WithJWTCookieValidator(validator jwtservice.Validator) CookieMiddlewareOption
• type GinContextKey
  • func (key GinContextKey) String() string
• type JWTMiddlewareOption
  • func WithJWTClaimsFactory(factory ClaimsFactory) JWTMiddlewareOption
  • func WithJWTContextKeys(tokenKey GinContextKey, claimsKey GinContextKey) JWTMiddlewareOption
  • func WithJWTServiceConfig(input jwtservice.ConfigServiceInput) JWTMiddlewareOption
  • func WithJWTUnauthorizedHandler(handler func(*gin.Context, error)) JWTMiddlewareOption
  • func WithJWTValidator(validator jwtservice.Validator) JWTMiddlewareOption

Variables

var (
	ErrNilJWTService            = errors.New("middlewares: jwt service is required")
	ErrMissingAuthorization     = errors.New("middlewares: authorization header is required")
	ErrInvalidAuthorizationType = errors.New("middlewares: authorization header must use Bearer scheme")
)

Functions

func RequireJWT

func RequireJWT(options ...JWTMiddlewareOption) gin.HandlerFunc

RequireJWT returns a Gin middleware that extracts a Bearer token from the request, validates it through the JWT service, and stores the parsed token and decoded claims in the Gin context.

By default, claims are decoded into a map[string]any and stored under the JWTClaimsContextKey, while the parsed token is stored under JWTTokenContextKey.

func RequireJWTCookie

func RequireJWTCookie(options ...CookieMiddlewareOption) gin.HandlerFunc

RequireJWTCookie returns a Gin middleware that extracts a JWT from a cookie, validates it, and stores the parsed token and claims in the Gin context.

func SecurityHeaders

func SecurityHeaders() gin.HandlerFunc

SecurityHeaders returns a Gin middleware that adds a set of common HTTP security headers to every response.

It currently sets:

• X-Frame-Options to reduce clickjacking risk.
• Content-Security-Policy to restrict allowed content sources.
• X-XSS-Protection to enable legacy XSS browser protections.
• Strict-Transport-Security to enforce HTTPS on future requests.
• Referrer-Policy to control referrer information.
• X-Content-Type-Options to disable MIME type sniffing.
• Permissions-Policy to limit access to browser capabilities.

This middleware should be placed early in the chain so the headers are added consistently to protected routes.

Types

type ClaimsFactory

type ClaimsFactory func() any

ClaimsFactory creates a destination value where JWT claims will be decoded before being stored in the Gin context.

type CookieMiddlewareOption

type CookieMiddlewareOption func(*cookieMiddlewareConfig)

CookieMiddlewareOption customizes cookie-based JWT middleware behavior.

func WithJWTCookieClaimsFactory

func WithJWTCookieClaimsFactory(factory ClaimsFactory) CookieMiddlewareOption

WithJWTCookieClaimsFactory configures the claims destination created per request.

func WithJWTCookieContextKeys

func WithJWTCookieContextKeys(tokenKey GinContextKey, claimsKey GinContextKey) CookieMiddlewareOption

WithJWTCookieContextKeys overrides the Gin context keys used to store the parsed token and decoded claims.

func WithJWTCookieServiceConfig

func WithJWTCookieServiceConfig(input cookiesauth.ConfigServiceInput) CookieMiddlewareOption

WithJWTCookieServiceConfig customizes how the cookie middleware builds its auth service from viper-backed configuration.

func WithJWTCookieUnauthorizedHandler

func WithJWTCookieUnauthorizedHandler(handler func(*gin.Context, error)) CookieMiddlewareOption

WithJWTCookieUnauthorizedHandler overrides the default 401 JSON response.

func WithJWTCookieValidator

func WithJWTCookieValidator(validator jwtservice.Validator) CookieMiddlewareOption

WithJWTCookieValidator registers an extra validator for the internally built JWT service used by the cookie middleware.

type GinContextKey

type GinContextKey string

GinContextKey represents a typed key used to store values in a Gin context.

const (
	JWTTokenContextKey  GinContextKey = "jwt.token"
	JWTClaimsContextKey GinContextKey = "jwt.claims"
)

func (GinContextKey) String

func (key GinContextKey) String() string

String returns the string value stored in Gin's context map.

type JWTMiddlewareOption

type JWTMiddlewareOption func(*jwtMiddlewareConfig)

JWTMiddlewareOption customizes the JWT middleware behavior.

func WithJWTClaimsFactory

func WithJWTClaimsFactory(factory ClaimsFactory) JWTMiddlewareOption

WithJWTClaimsFactory configures the claims destination created per request. This is useful when handlers expect a strongly typed claims struct.

func WithJWTContextKeys

func WithJWTContextKeys(tokenKey GinContextKey, claimsKey GinContextKey) JWTMiddlewareOption

WithJWTContextKeys overrides the Gin context keys used to store the parsed token and decoded claims.

func WithJWTServiceConfig

func WithJWTServiceConfig(input jwtservice.ConfigServiceInput) JWTMiddlewareOption

WithJWTServiceConfig customizes how the middleware builds the JWT service from viper-backed configuration.

func WithJWTUnauthorizedHandler

func WithJWTUnauthorizedHandler(handler func(*gin.Context, error)) JWTMiddlewareOption

WithJWTUnauthorizedHandler overrides the default 401 JSON response emitted when token extraction or validation fails.

func WithJWTValidator

func WithJWTValidator(validator jwtservice.Validator) JWTMiddlewareOption

WithJWTValidator registers an extra validator for the service built by the middleware.