jwks

Overview ¶

Package jwks provides a production-ready JWKS (JSON Web Key Set) key function for validating JWTs.

The keyfunc wraps the MicahParks/keyfunc library with built-in periodic key refresh, rate-limiting of unknown-KID refresh attempts, and structured logging. It is safe for concurrent use and suitable for use as a jwt.Keyfunc in JWT middleware.

Basic usage:

kf, err := jwks.New(ctx, []string{"https://auth.example.com/.well-known/jwks.json"})
if err != nil {
    return err
}

jwtConfig := middleware.JWTConfig{
    Keyfunc: kf.Keyfunc,
}
e.Use(middleware.JWT(jwtConfig))

The keyfunc automatically refreshes keys in the background. If a JWT references an unknown key ID, it triggers an immediate refresh but rate-limits rapid refresh attempts to prevent thundering herd.