Announcing Go-JWT-Middleware V3.0

[developerkunal]

We're pleased to announce the release of Go-JWT-Middleware v3.0. This major release brings modern Go patterns, enhanced security features, and improved developer experience to JWT authentication in Go.

What's New in V3

Pure Options Pattern

V3 adopts a pure functional options pattern across all components, making the API self-documenting and easier to use with IDE autocomplete.

Before (v2):

validator.New(keyFunc, validator.RS256, issuer, audience)

Now (v3):

validator.New(
    validator.WithKeyFunc(keyFunc),
    validator.WithAlgorithm(validator.RS256),
    validator.WithIssuer("https://issuer.example.com/"),
    validator.WithAudience("my-api"),
)

Type Safety with Generics

V3 uses Go generics for type-safe claims retrieval, eliminating runtime type assertions.

Before (v2):

claims := r.Context().Value(jwtmiddleware.ContextKey{}).(*validator.ValidatedClaims)

Now (v3):

claims, err := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context())
if err != nil {
    // Handle gracefully
}

DPoP Support (RFC 9449)

V3 introduces support for Demonstrating Proof-of-Possession (DPoP), which helps prevent token theft and replay attacks.

middleware, err := jwtmiddleware.New(
    jwtmiddleware.WithValidator(jwtValidator),
    jwtmiddleware.WithDPoPMode(jwtmiddleware.DPoPRequired),
)

Modern JWT Library

V3 migrates from square/go-jose to lestrrat-go/jwx v3, an actively-maintained library with modern Go support.

Expanded Algorithm Support

V3 now supports 14 signature algorithms including EdDSA (Ed25519) and ES256K.

Core-Adapter Architecture

V3 introduces a framework-agnostic core package that enables reusable validation logic across different transports (HTTP, gRPC, etc.).

Additional Improvements

• RFC 6750 Compliant Errors - Standardized error responses with proper WWW-Authenticate headers
• Structured Logging - Built-in support for log/slog
• URL Exclusions - Skip JWT validation for health checks and public endpoints
• Custom Claims - Type-safe custom claims with generics

Quick Start

Installation

go get github.com/auth0/go-jwt-middleware/v3

Basic Example

package main

import (
    "context"
    "log"
    "net/http"

    "github.com/auth0/go-jwt-middleware/v3"
    "github.com/auth0/go-jwt-middleware/v3/validator"
)

func main() {
    keyFunc := func(ctx context.Context) (any, error) {
        return []byte("your-256-bit-secret"), nil
    }

    jwtValidator, err := validator.New(
        validator.WithKeyFunc(keyFunc),
        validator.WithAlgorithm(validator.HS256),
        validator.WithIssuer("https://your-issuer.com/"),
        validator.WithAudience("your-api"),
    )
    if err != nil {
        log.Fatalf("failed to set up validator: %v", err)
    }

    middleware, err := jwtmiddleware.New(
        jwtmiddleware.WithValidator(jwtValidator),
    )
    if err != nil {
        log.Fatalf("failed to set up middleware: %v", err)
    }

    http.Handle("/api/private", middleware.CheckJWT(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        claims, _ := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context())
        w.Write([]byte("Hello, " + claims.RegisteredClaims.Subject))
    })))

    log.Println("Server listening on :3000")
    http.ListenAndServe(":3000", nil)
}

Breaking Changes

• Options Pattern - All constructors now use functional options instead of positional parameters
• Context Key - No longer exported; use GetClaims[T]() helper function instead
• Custom Claims - Now use generics for type safety
• TokenExtractor - Returns ExtractedToken with scheme instead of plain string
• Type Naming - ExclusionURLHandler (not ExclusionUrlHandler)

Migration from V2

We've made migration straightforward with a comprehensive Migration Guide.

Key Steps:

1. Update import paths from v2 to v3
2. Convert to options pattern
3. Use GetClaims[T]() instead of context value
4. Update custom token extractors (if any)

Note: You can run v2 and v3 side-by-side during migration.

Examples

Working examples for popular frameworks:

• http-example - Basic HTTP server with HMAC
• http-jwks-example - Production setup with JWKS
• http-dpop-example - DPoP support
• gin-example - Gin framework integration
• echo-example - Echo framework integration
• iris-example - Iris framework integration

Resources

• Documentation - Full API reference
• Migration Guide - Upgrade from v2 to v3
• Examples - Production-ready code samples
• Changelog - Complete changelog
• Issue Tracker - Report bugs or request features

Feedback

We'd love to hear your feedback on v3. Star the repo, join the discussion below, or contribute to make it even better!

---

Go-JWT-Middleware v3.0 - Secure, Modern, Developer-Friendly

Documentation • Migration Guide • Examples