Building secure APIs in Go has historically involved a series of trade-offs. We love Go for its strong typing, straightforward concurrency model, and brutal simplicity. Yet, for years, dealing with JSON Web Tokens (JWTs) in Go web servers felt like stepping back into the wild west of dynamic typing. You would carefully validate a token, stuff it into a request context, and simply cross your fingers that the data you pulled out later matched exactly what you expected.
With the release of go-jwt-middleware Version 3 (v3), we are fundamentally shifting how Go developers approach API security. We have completely rewritten the library to leverage modern Go features like generics, standardizing the developer experience while introducing cutting-edge security standards like Demonstrating Proof-of-Possession (DPoP).
This is the story of why we rebuilt it, what the new world looks like, and how you can transition your applications to a safer and more robust architecture.
JWT Middleware That Worked until It Didn't
If you have been writing Go for a while, the pain points of older middleware libraries are likely burned into your memory. Version 2 (v2) of go-jwt-middleware was widely adopted and incredibly useful, but it was designed in an era before Go 1.18. It suffered from the limitations of the time. Let's look at the painful reality of maintaining a v2 integration.
The type assertion time bomb
Every Go developer who has used JWT middleware in the past has written a variation of this exact line of code:
claims, ok := r.Context().Value(jwtmiddleware.ContextKey{}).(*validator.ValidatedClaims) if !ok { http.Error(w, "failed to get validated claims", http.StatusInternalServerError) return }
The careful developer remembers the comma-ok pattern, but the API does not enforce it. Nothing stops someone from writing the bare assertion claims := r.Context().Value(jwtmiddleware.ContextKey{}).(*validator.ValidatedClaims) — which compiles perfectly, passes code review, works in unit tests, and then one day, in production at 2:00 AM, panics and crashes your server.
Maybe someone added a new logging middleware that accidentally rewrites the context without copying the values. Maybe a new route skipped authentication but still tried to access the user ID. Whatever the reason, a raw type assertion on a generic context value is a crash waiting to happen. In v2, this was not a bug. It was a design limitation baked into an API written before Go supported generics, and it was the absolute only way to retrieve your authenticated claims.
The positional parameter guessing game
Setting up a v2 validator was an exercise in pure memorization. It looked like this:
jwtValidator, err := validator.New( provider.KeyFunc, validator.RS256, issuerURL.String(), []string{audience}, )
You had four positional parameters. There were no labels. If you accidentally swapped the issuer and the audience, which are both just strings, the Go compiler would not catch it. You would only discover the mistake at runtime when every single token got rejected for having an invalid audience. If you needed to add clock skew tolerance to account for drifting server times, you had to scour the documentation to remember which optional parameter came fifth. It was an API that made it incredibly easy to do the wrong thing.
Bearer tokens in a post-bearer world
OAuth 2.0 bearer tokens have a fundamental security flaw: if someone steals the token, they effectively become you. Token theft via log exposure, man-in-the-middle attacks, or compromised intermediaries is not a theoretical academic exercise. It is one of the most common OAuth attack vectors in the wild.
The industry responded to this threat with RFC 9449: Demonstrating Proof-of-Possession (DPoP). This standard cryptographically binds tokens to the specific client software that requested them. A stolen DPoP token is completely useless to an attacker without the private key, which never leaves the original client.
v2 lacked DPoP support. If your security team mandated proof-of-possession, you were completely on your own to implement the complex cryptographic validations required by the RFC.
Tightly coupled architecture
v2 did separate its validator into its own package, but the middleware layer — token extraction, error responses, and context management — was built strictly for net/http. There was no formally defined boundary between transport concerns and core validation logic. If you wanted to validate a token outside of a standard HTTP request flow, you had to reach into the validator package directly and wire up the pieces yourself, with no guidance from the library on how to do it correctly.
What JWT Authentication Should Feel Like
Now, imagine what your development lifecycle would look like with these historical paper cuts removed. Version 3 represents a ground-up rethink of how authentication middleware should behave in modern Go.
Type-safe claims retrieval
Imagine retrieving your JWT claims and knowing, before your code ever actually runs, that the types are strictly correct:
claims, err := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context()) if err != nil { // Handle gracefully: no panic, no crash http.Error(w, "Unauthorized", http.StatusUnauthorized) return }
The generic type parameter [*validator.ValidatedClaims] is verified by the Go compiler. If you pass the wrong type, your code simply will not build. If the claims are missing from the context, you receive a standard Go error instead of a catastrophic nil pointer dereference.
For routes where authentication is optional, you can check for the presence of claims safely:
if jwtmiddleware.HasClaims(r.Context()) { claims, err := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context()) if err != nil { http.Error(w, "Unauthorized", http.StatusUnauthorized) return } // Serve personalized response } else { // Serve public response }
No more runtime panics. No more guessing. Just rock-solid type safety.
An API that documents itself
Imagine setup code where every single parameter declares exactly what it does:
jwtValidator, err := validator.New( validator.WithKeyFunc(provider.KeyFunc), validator.WithAlgorithm(validator.RS256), validator.WithIssuer(issuerURL.String()), validator.WithAudience(audience), validator.WithAllowedClockSkew(30 * time.Second), )
Using the functional options pattern, you literally cannot accidentally swap the issuer and audience. Your IDE will autocomplete every available option. Adding clock skew tolerance is a single readable line rather than a mystery parameter. Furthermore, if you forget a required option, the constructor returns a descriptive error at startup, saving you from a silent misconfiguration that might otherwise surface hours later in production.
Tokens that prove who sent them
Imagine a world where a stolen JWT is utterly worthless to the attacker. With v3, enforcing this level of security takes exactly two lines of code:
middleware, err := jwtmiddleware.New( jwtmiddleware.WithValidator(jwtValidator), jwtmiddleware.WithDPoPMode(jwtmiddleware.DPoPRequired), )
With DPoP required, every incoming request must cryptographically prove that the sender holds the private key associated with the access token. The middleware automatically validates the DPoP proof signature, checks the HTTP method and URL binding, verifies the access token hash, and enforces timestamp freshness.
Are you running your Go service behind a reverse proxy? You just need one more line to ensure URL validation works correctly:
jwtmiddleware.WithStandardProxy()
How go-jwt-middleware Gets You There
How did we achieve this leap in developer experience and security? The journey from v2 to v3 required fundamental architectural changes. Here is a deep dive into the engineering decisions that make v3 tick.
A new cryptographic foundation
The biggest change you will likely never see is the engine running under the hood. v3 completely replaces square/go-jose with lestrrat-go/jwx v3 as the primary JWT and JSON Web Key (JWK) processing library. We made this switch for several critical reasons.
First is performance. The new engine provides faster token parsing, more efficient JWKS operations, and lower memory allocation. For middleware that executes on every authenticated request, these improvements compound rapidly.
Second is algorithm coverage. v2 already supported RSA-PSS and EdDSA. v3 adds ES256K (crucial for blockchain and decentralized identity applications), bringing the total to 14 distinct signature algorithms.
Finally, active maintenance is vital for security infrastructure. The lestrrat-go/jwx ecosystem has frequent releases, highly responsive security patch management, and strict alignment with current Go language versions.
The core-adapter architecture
v3 introduces a dedicated core package that isolates all the complex validation logic. This includes JWT verification, DPoP proof validation, claims management, and error classification. Crucially, this core package has absolutely zero dependencies on net/http.
The HTTP middleware provided in the root package is now just a thin transport adapter. Its only jobs are to extract tokens from Authorization headers, pass them to the core engine, and translate the core engine's results into standardized HTTP error responses. By cleanly decoupling the core validation from the transport layer, we ensure that the most security-critical code is isolated, fully testable, and easier to maintain. Whenever we release bug fixes or security patches to the validation logic, those improvements apply reliably without tangling with HTTP semantics.
Full standardized DPoP support
The implementation of RFC 9449 (DPoP) is the most significant security enhancement in this release. When you enable DPoP, the middleware executes a rigorous validation sequence on every request.
- Proof Signature: The middleware verifies that the DPoP proof JWT was signed with the correct asymmetric key.
- HTTP Method Binding: It checks that a proof generated for a
GETrequest cannot be reused by an attacker for aPOSTrequest. - URL Binding: It ensures a proof meant for
/api/userswill fail if sent to/api/admin. - Access Token Hash: It validates the hash to guarantee the proof matches the specific access token provided.
- Key Binding: It matches the access token's confirmation claim against the thumbprint of the proof's public key.
- Timestamp Verification: It checks the proof's age to prevent replay attacks.
To help you roll this out safely, v3 supports three operational modes:
| Mode | Behavior | Use Case |
|---|---|---|
| DPoPAllowed | Accepts both Bearer and DPoP tokens. | The default setting. Perfect for starting your migration. |
| DPoPRequired | Rejects standard Bearer tokens entirely. | The ultimate end goal for maximum API security. |
| DPoPDisabled | Standard Bearer-only mode. | Explicitly opting out of proof-of-possession. |
Read Protect Your Access Tokens with DPoP (Demonstrating Proof of Possession) to learn more about DPoP.
For services operating behind Nginx, Apache, HAProxy, or cloud API gateways, URL validation can be tricky due to forwarded headers. v3 includes built-in trusted proxy configuration to handle this seamlessly:
jwtmiddleware.WithStandardProxy() // For Nginx, Apache, HAProxy jwtmiddleware.WithAPIGatewayProxy() // For AWS API Gateway, Azure APIM jwtmiddleware.WithRFC7239Proxy() // For RFC 7239 Forwarded headers
RFC 6750 compliant error responses
Error handling in v2 was quite basic. You had to call an error handler function and figure out the HTTP semantics yourself. v3's default error handler produces fully standards-compliant RFC 6750 responses immediately out of the box.
If a token is missing, your API will correctly respond with a 401 Unauthorized status and a WWW-Authenticate: Bearer realm="api" header.
If a token is expired, the middleware provides a detailed JSON response alongside the required headers, including a machine-readable error_code like token_expired.
If you are using DPoP mode, the middleware automatically issues the proper cryptographic challenges required by RFC 9449 Section 6.1, signaling to the client exactly which algorithms are supported. This level of precision allows your frontend applications or API consumers to handle authentication failures programmatically, rather than just guessing what went wrong based on a generic 401 status code.
Structured logging integration
Monitoring authentication failures is critical for security auditing. v3 integrates natively with Go's standard log/slog package:
logger := slog.Default() middleware, err := jwtmiddleware.New( jwtmiddleware.WithValidator(jwtValidator), jwtmiddleware.WithLogger(logger), )
By passing in your logger, you instantly get rich, structured log entries detailing token extraction attempts, validation outcomes with exact timings, DPoP proof verification steps, and JWKS cache events. You gain total observability using your existing logging infrastructure without writing custom wrapper functions.
Support for multiple issuers and audiences
Modern microservice architectures frequently need to accept tokens from multiple distinct identity providers. v2 already supported multiple audiences through its []string parameter, but was limited to a single issuer. v3 removes that limitation with WithIssuers():
jwtValidator, err := validator.New( validator.WithKeyFunc(provider.KeyFunc), validator.WithAlgorithm(validator.RS256), validator.WithIssuers([]string{ "https://auth.company.com/", "https://partner-idp.example.com/", }), validator.WithAudiences([]string{"api-v1", "api-v2"}), )
You no longer need to chain multiple middleware instances together to support multiple identity providers. One validator handles multiple trust boundaries.
Migrating from v2 to v3
We designed the migration process to be entirely mechanical. Because we leveraged Go's strong typing, every single breaking change will produce a loud, clear compiler error. You will not miss anything.
Updating the module path
Begin by pulling the new major version into your go.mod file:
go get github.com/auth0/go-jwt-middleware/v3@latest
Note: v3 requires *Go 1.24 or later*.
Next, update your import statements across your project to point to the v3 paths instead of v2.
Converting to the options pattern
You will need to rewrite your validator and middleware constructors to use the new functional options pattern.
// The v3 approach jwtValidator, err := validator.New( validator.WithKeyFunc(provider.KeyFunc), validator.WithAlgorithm(validator.RS256), validator.WithIssuer(issuerURL.String()), validator.WithAudience(audience), )
Do the same for your JWKS provider, utilizing jwks.WithIssuerURL() and jwks.WithCacheTTL().
Updating context claims access
Replace all instances of raw context type assertions with the new generic helper function:
// The v3 approach claims, err := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context()) if err != nil { http.Error(w, "Unauthorized", http.StatusUnauthorized) return }
Running side by side
Because v2 and v3 use entirely different module paths, you are not forced into a massive rewrite all at once. You can import both versions simultaneously and migrate your application route by route safely.
import ( v2mw "github.com/auth0/go-jwt-middleware/v2" v3mw "github.com/auth0/go-jwt-middleware/v3" )
What Is Coming Next: Multiple Custom Domains
The WithIssuers() option shown above handles static multi-issuer setups well. But real-world multi-tenant applications often need more — issuers that come and go as tenants are provisioned, mixed key types across tenants, and visibility into which issuers are active.
We are actively building Multiple Custom Domains (MCD) support that will bring:
- A dedicated
MultiIssuerProviderthat automatically discovers and caches JWKS endpoints per issuer, with LRU eviction for large tenant populations. - Dynamic issuer resolution via
WithIssuersResolver(), allowing you to resolve allowed issuers from a database at request time without restarting your service. - Mixed key types in a single validator — combine OIDC-based asymmetric issuers (RS256) with pre-shared symmetric issuers (HS256) using
WithIssuerKeyConfig(). - Per-tenant context helpers like
IssuerFromContext()for routing logic based on which identity provider issued the token. - Observability via
Stats()andProviderCount()for monitoring issuer activity, key types, and last-used timestamps.
Stay tuned for a dedicated deep dive once MCD ships.
Getting Started with Go JWT Middleware v3
v3 of go-jwt-middleware is stable, production-ready, and available today. Here is a minimal working example:
package main import ( "log" "net/http" jwtmiddleware "github.com/auth0/go-jwt-middleware/v3" "github.com/auth0/go-jwt-middleware/v3/jwks" "github.com/auth0/go-jwt-middleware/v3/validator" ) func main() { provider, err := jwks.NewCachingProvider( jwks.WithIssuerURL("https://your-tenant.auth0.com/"), ) if err != nil { log.Fatalf("failed to create JWKS provider: %v", err) } jwtValidator, err := validator.New( validator.WithKeyFunc(provider.KeyFunc), validator.WithAlgorithm(validator.RS256), validator.WithIssuer("https://your-tenant.auth0.com/"), validator.WithAudience("https://your-api.example.com"), ) if err != nil { log.Fatalf("failed to create validator: %v", err) } middleware, err := jwtmiddleware.New( jwtmiddleware.WithValidator(jwtValidator), ) if err != nil { log.Fatalf("failed to create middleware: %v", err) } handler := middleware.CheckJWT(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { claims, err := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context()) if err != nil { http.Error(w, "Unauthorized", http.StatusUnauthorized) return } w.Write([]byte("Hello, " + claims.RegisteredClaims.Subject)) })) log.Print("listening on :3000") log.Fatal(http.ListenAndServe(":3000", handler)) }
Note: Adjust the import paths and claims fields to match your actual v3 API. See our examples directory for fully working code covering HTTP, Gin, Echo, DPoP, and multi-issuer setups, and our pkg.go.dev documentation for advanced options.
Explore the Documentation: For a deeper dive into all the available functional options and advanced custom claims parsing, be sure to review our official pkg.go.dev documentation.
About the author
Kunal Dawar
Software Engineer II