Documentation
¶
Overview ¶
Package jwt provides JWT authentication middleware for the optional contrib module.
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 JWT integration adds environment loading around this middleware.
Purpose: See the package summary above. Import: `github.com/aatuh/api-toolkit/contrib/v4/middleware/auth/jwt`. Example: See docs/api-reference.md for package example links and docs/cookbook.md for task recipes. Errors: Constructors, parsers, and handlers return or write documented errors according to their signatures; packages with plain data types do not add hidden error channels. Concurrency: Treat configured middleware and helpers as immutable after construction; request and response values remain request-scoped unless a type documents stronger guarantees. Stability: Contrib API; it is not part of the stable root API promise. When not to use: Prefer net/http, application-owned types, or narrower helpers when this package contract is not needed.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func HealthChecker ¶
HealthChecker returns a JWKS health checker or nil when disabled.
func WithSubject ¶
WithSubject stores an authenticated subject in context.
Example ¶
package main
import (
"context"
"fmt"
"github.com/aatuh/api-toolkit/contrib/v4/middleware/auth/jwt"
)
func main() {
ctx := jwt.WithSubject(context.Background(), jwt.Subject{
UserID: "user-1",
Email: "user@example.test",
})
subject, ok := jwt.SubjectFromContext(ctx)
fmt.Println(ok)
fmt.Println(subject.UserID)
}
Output: true user-1
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