v3.0.0

BEFORE YOU UPGRADE

• This is a major release that includes breaking changes. Please see MIGRATION_GUIDE.md before upgrading. This release will require changes to your application.

Added

• Pure options pattern for validator, middleware, and JWKS provider (#357, #358, #360)
• DPoP (Demonstrating Proof-of-Possession) support per RFC 9449 (#363)
• Framework-agnostic core package for reusable validation logic (#356)
• Type-safe claims retrieval with generics (GetClaims[T](), MustGetClaims[T](), HasClaims())
• Structured logging support compatible with log/slog
• Support for 14 signature algorithms (HS256/384/512, RS256/384/512, PS256/384/512, ES256/384/512, ES256K, EdDSA)
• Enhanced error responses with RFC 6750 compliance
• Trusted proxy configuration for DPoP behind reverse proxies
• Multiple issuer and audience support with new APIs
• Documentation and linting configuration (#361)

Changed

• Migrated from square/go-jose to lestrrat-go/jwx v3 (#358)
• Module path updated to github.com/auth0/go-jwt-middleware/v3 (#355)
• Minimum Go version updated to 1.24 (#355)
• Update examples for v3 module path and new APIs

Breaking

• Pure options pattern: All constructors (New()) now require functional options instead of positional parameters
• Context key: ContextKey{} is no longer exported - use GetClaims[T]() helper function
• Custom claims now use generics for type safety
• TokenExtractor returns ExtractedToken (with scheme) instead of string
• Type naming: ExclusionUrlHandler renamed to ExclusionURLHandler

Migration Example

v2:

// Validator with positional parameters
jwtValidator, err := validator.New(
    keyFunc,
    validator.RS256,
    "https://issuer.example.com/",
    []string{"my-api"},
)

// Middleware
middleware := jwtmiddleware.New(jwtValidator.ValidateToken)

// Claims access via context key
claims := r.Context().Value(jwtmiddleware.ContextKey{}).(*validator.ValidatedClaims)

v3:

// Validator with pure options
jwtValidator, err := validator.New(
    validator.WithKeyFunc(keyFunc),
    validator.WithAlgorithm(validator.RS256),
    validator.WithIssuer("https://issuer.example.com/"),
    validator.WithAudience("my-api"),
)

// Middleware with options
middleware, err := jwtmiddleware.New(
    jwtmiddleware.WithValidator(jwtValidator),
)

// Type-safe claims with generics
claims, err := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context())

See MIGRATION_GUIDE.md for complete migration instructions.

v3.0.0-beta.0

BEFORE YOU UPGRADE

• This is a major release that includes breaking changes. Please see MIGRATION_GUIDE.md before upgrading. This release will require changes to your application.

Added

• Pure options pattern for validator, middleware, and JWKS provider (#357, #358, #360)
• DPoP (Demonstrating Proof-of-Possession) support per RFC 9449 (#363)
• Framework-agnostic core package for reusable validation logic (#356)
• Type-safe claims retrieval with generics (GetClaims[T](), MustGetClaims[T](), HasClaims())
• Structured logging support compatible with log/slog
• Support for 14 signature algorithms (HS256/384/512, RS256/384/512, PS256/384/512, ES256/384/512, ES256K, EdDSA)
• Enhanced error responses with RFC 6750 compliance
• Trusted proxy configuration for DPoP behind reverse proxies
• Multiple issuer and audience support with new APIs
• Documentation and linting configuration (#361)

Changed

• Migrated from square/go-jose to lestrrat-go/jwx v3 (#358)
• Module path updated to github.com/auth0/go-jwt-middleware/v3 (#355)
• Minimum Go version updated to 1.24 (#355)
• Update examples for v3 module path and new APIs

Breaking

• Pure options pattern: All constructors (New()) now require functional options instead of positional parameters
• Context key: ContextKey{} is no longer exported - use GetClaims[T]() helper function
• Custom claims now use generics for type safety
• TokenExtractor returns ExtractedToken (with scheme) instead of string
• Type naming: ExclusionUrlHandler renamed to ExclusionURLHandler

Migration Example

v2:

// Validator with positional parameters
jwtValidator, err := validator.New(
    keyFunc,
    validator.RS256,
    "https://issuer.example.com/",
    []string{"my-api"},
)

// Middleware
middleware := jwtmiddleware.New(jwtValidator.ValidateToken)

// Claims access via context key
claims := r.Context().Value(jwtmiddleware.ContextKey{}).(*validator.ValidatedClaims)

v3:

// Validator with pure options
jwtValidator, err := validator.New(
    validator.WithKeyFunc(keyFunc),
    validator.WithAlgorithm(validator.RS256),
    validator.WithIssuer("https://issuer.example.com/"),
    validator.WithAudience("my-api"),
)

// Middleware with options
middleware, err := jwtmiddleware.New(
    jwtmiddleware.WithValidator(jwtValidator),
)

// Type-safe claims with generics
claims, err := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context())

See MIGRATION_GUIDE.md for complete migration instructions.

v2.3.1

Security

• security: CVE-2025-27144 mitigation for v2.3.1 #344 (developerkunal)

v2.3.0

Added

• Bump Go version to 1.23 and update example dependencies #328 (developerkunal)
• [GH-288] Add Support for WithSynchronousRefresh Option in CachingProvider for Blocking/Non-Blocking Key Refresh #314 (developerkunal)
• SDK-5703 [GH-283] Add support for exclusion URLs in JWT middleware #319 (developerkunal)

Fixed

• fix(oidc): Validate HTTP response status and improve error messaging in OIDC (#308) #316 (developerkunal)

v2.2.2

Security

• Bump gopkg.in/go-jose/go-jose.v2 from 2.6.2 to 2.6.3 #258 (dependabot[bot])

v2.2.1

Security

• Bump golang.org/x/crypto from 0.4.0 to 0.17.0 #234 (dependabot[bot])
• Bump gopkg.in/go-jose/go-jose.v2 from 2.6.1 to 2.6.2 #229 (dependabot[bot])

v2.2.0

Added

• add echo example #208 (mehulgohil)
• added example for iris web framework #199 (mehulgohil)

Changed

• ESD-32688: Improve locking and blocking associated with key retrieval #225 (ewanharris)
• Replace deprecated pkg/errors in favor of Go's standard library #189 (molaga)
• Replace square/go-jose with go-jose/go-jose #188 (sergiught)
• Fail to instantiate validator when audience is an empty string #183 (sergiught)

v2.1.0

Added

• Allow setting a custom http.Client on the jwks.Provider (#151)
• Add example tests (#157)
• Add example for the gin web framework (#175)

Fixed

• Fix CookieTokenExtractor to not throw error when no cookie present (#172)
• Fix panic threat when using type-cast for customClaims in validator (#165)
• Fix authentication error when setting multiple audiences on validator (#176)

v2.0.1

Security

• Update Crypto dependency (#146)

v2.0.0

BEFORE YOU UPGRADE

• This is a major release that includes breaking changes. Please see MIGRATION_GUIDE before
  upgrading. This release will require changes to your application.

Added

• Use github.com/pkg/errors (#98)
• Add a migration guide (#99)
• Add cookie token extractor (#93, #63)
• Add token validator using square/go-jose.v2 (#84, #81, #79, #74, #53)
• Add allowed signing algorithms in validator (#128)
• Add issuer and audience as required params in validator (#119)
• Add support for jwks

Changed

• Update docs (#72)
• Reorganize imports across the project
• Reorder fields to use less memory
• Split jwtmiddleware into multiple files

Breaking

• Simplify JWT library functionality into an interface (#77)
• Rename Claims to RegisteredClaims in validator pkg
• Refactor main middleware (#90, #51, #51)
• Write back error messages on DefaultErrorHandler

Fixed

• Fix code smells and code style