Documentation
¶
Overview ¶
Package jwt provides stable JWT authentication middleware.
NewMiddleware validates bearer tokens with configured issuer, audience, JWKS, algorithm allowlist, clock skew, and optional claim requirements. Subject helpers store and retrieve authenticated identity from request context.
Dangerous bypass and skip-header behavior must be configured explicitly and should be restricted to trusted proxies. The contrib JWT integration adds environment loading around this stable middleware.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func HealthChecker ¶
func HealthChecker(cfg Config, client *http.Client) ports.HealthChecker
HealthChecker returns a JWKS health checker or nil when disabled.
Types ¶
type ClaimRequirements ¶
type ClaimRequirements struct {
RequireSubject *bool
RequireExpiration *bool
RequireIssuedAt *bool
RequireNotBefore *bool
}
ClaimRequirements configures required JWT claims (nil preserves defaults).
type Config ¶
type Config struct {
Enabled bool
JWKSURL string
Issuer string
Audience string
// AllowedAlgorithms constrains JWT signing methods (defaults to RS256).
AllowedAlgorithms []string
AllowedClockSkew time.Duration
JWKSRefreshTimeout time.Duration
JWKSRefreshInterval time.Duration
// RequiredClaims enforces presence of specific JWT claims (defaults to sub + exp).
RequiredClaims ClaimRequirements
// AllowDangerousDevBypasses enables skip headers only from trusted proxies.
AllowDangerousDevBypasses bool
SkipHeaderEnabled bool
SkipHeaderName string
// SkipTrustedProxies configures trusted CIDRs for skip header usage.
SkipTrustedProxies []string
}
Config controls JWT validation.
type Middleware ¶
type Middleware struct {
// contains filtered or unexported fields
}
Middleware validates JWTs and stores the subject.
func NewMiddleware ¶
NewMiddleware creates a middleware instance. If JWKS refresh is enabled, Close() must be called or the passed context canceled on shutdown.
func (*Middleware) Close ¶
func (m *Middleware) Close()
Close stops background JWKS refresh work, if enabled.
func (*Middleware) Handler ¶
func (m *Middleware) Handler(next http.Handler) http.Handler
Handler returns the http middleware enforcing authentication.
func (*Middleware) OptionalHandler ¶
func (m *Middleware) OptionalHandler(next http.Handler) http.Handler
OptionalHandler attaches a subject when a valid token is present, but allows requests without authentication to continue.
type Subject ¶
type Subject struct {
UserID string `json:"user_id,omitempty"`
Email string `json:"email,omitempty"`
First string `json:"first,omitempty"`
Last string `json:"last,omitempty"`
Language string `json:"language,omitempty"`
Claims map[string]any `json:"claims,omitempty"`
}
Subject contains identity information extracted from a JWT.
Source Files