Jwx Guide V4

jwx-guide-v4

This skill helps you assist Go developers who are using github.com/lestrrat-go/jwx/v4 in their own projects. It is scoped to v4 only. There is no equivalent skill for v3 or v2; for those, work from the version's own docs/ directory and pkg.go.dev. Do not apply v4 rules to a v3 or v2 codebase — the jwa identifiers are constants there, not functions, and the jwk and error APIs differ.

Where to look things up

You will not have this repository checked out. To verify an API claim before answering, use these sources, in order of preference:

1. Go module cache — if the user's project depends on jwx, the source is on disk:

   echo "$(go env GOMODCACHE)/github.com/lestrrat-go/jwx/v4@$(go list -m -f '{{.Version}}' github.com/lestrrat-go/jwx/v4)"

   This directory contains the full source tree including docs/, jwt/, jws/, jwe/, jwk/, jwa/.
2. pkg.go.dev — canonical API reference for any exported symbol:
   • https://pkg.go.dev/github.com/lestrrat-go/jwx/v4
   • https://pkg.go.dev/github.com/lestrrat-go/jwx/v4/jwt (etc. per subpackage)
3. GitHub — narrative documentation lives at the repo:
   • https://github.com/lestrrat-go/jwx/blob/develop/v4/docs/01-jwt.md
   • https://github.com/lestrrat-go/jwx/blob/develop/v4/docs/02-jws.md
   • https://github.com/lestrrat-go/jwx/blob/develop/v4/docs/03-jwe.md
   • https://github.com/lestrrat-go/jwx/blob/develop/v4/docs/04-jwk.md
   • https://github.com/lestrrat-go/jwx/blob/develop/v4/docs/10-extensions.md
   • https://github.com/lestrrat-go/jwx/blob/develop/v4/docs/99-faq.md
4. Examples repo — runnable usage patterns. The repo's README.md is a topical index that maps "what do I want to do" → "which *_example_test.go file." Fetch the README first when looking for an example by topic; then fetch the linked file:
   • https://github.com/jwx-go/examples/blob/develop/v4/README.md

When the user's question goes beyond the patterns in this skill (custom claim types, JWE recipients with per-recipient headers, custom key providers, base64 backend swap, performance tuning), fetch from these sources rather than guessing.

Prerequisites

• Go 1.26+ is required. v4 uses generics features and stdlib additions (errors.AsType[T]) that are new in 1.26.
• GOEXPERIMENT=jsonv2 must be set on Go 1.26 for every go build/go test/go run, because v4 depends on encoding/json/v2. Without it → builds fail with build constraints exclude all Go files. NEVER set it on Go 1.27+ → encoding/json/v2 is in the standard library there, and naming the experiment rebuilds the standard library under a non-default configuration.

Sub-package map:

Critical rules (read first)

1. jwt.Parse verifies AND validates by default. A bare jwt.Parse(data) errors because no key was supplied. To intentionally skip both, use jwt.ParseInsecure. To verify but skip claim validation, pass jwt.WithValidate(false). This is deliberately asymmetric vs. jws.Parse/jwe.Parse (which only parse). Do not "correct" it.
2. Always pin the algorithm on the verify side. jwt.WithKey(jwa.RS256(), key), jws.WithKey(jwa.ES256(), key). Never trust the alg from the incoming header alone.
3. Never use jwt.ParseInsecure for tokens received from the network. It is for testing or for extracting claims from a token whose origin is already trusted by other means.
4. jwa algorithms are functions in v4, not constants. Write jwa.RS256(), not jwa.RS256. This trips up users migrating from v2/v3.
5. kid matching is enforced when verifying with a JWK Set. If a token omits kid and the set contains exactly one key, use jwt.WithKeySet(set, jws.WithUseDefault(true)). Use jws.WithRequireKid(false) only when verification must consider multiple keys without matching kid values.
6. jku (key URL in the JWS header) is attacker-controlled. Use jwt.WithVerifyAuto only with a jwkfetch.Client configured with a jwkfetch.NewMapWhitelist() of allowed URLs.
7. HMAC keys are []byte, not string. Pass []byte("secret"), or better, a jwk.Key imported from those bytes.
8. jwk.Import and jwk.Export require explicit type parameters. jwk.Import[jwk.Key](raw), jwk.Export[*rsa.PublicKey](key). Their type argument is not inferable from the call, so bare jwk.Import(raw) does not compile.
9. jwk.ParseKey is not generic. jwk.ParseKey(data) returns (jwk.Key, error). Use jwk.ParseKeyAs[jwk.RSAPublicKey](data) when a concrete JWK type is required.

Verifying a JWT (the 90% case)

import (
    "github.com/lestrrat-go/jwx/v4/jwa"
    "github.com/lestrrat-go/jwx/v4/jwt"
)

tok, err := jwt.Parse(raw, jwt.WithKey(jwa.RS256(), publicKey))
if err != nil {
    // signature failed, claim validation failed, or parse failed
    return err
}
// tok is verified + validated; safe to read claims

publicKey may be:

• a *rsa.PublicKey / *ecdsa.PublicKey / ed25519.PublicKey from crypto/*
• []byte for HMAC algorithms
• a jwk.Key

To validate against expected claim values, pass jwt.WithIssuer(...), jwt.WithAudience(...), jwt.WithSubject(...), and jwt.WithJwtID(...). Validation uses exact timestamps by default. Configure clock skew tolerance with jwt.WithAcceptableSkew(30 * time.Second).

Verifying with a JWK Set (kid-based key selection)

set, err := jwk.Parse(jwksBytes)
if err != nil { return err }

tok, err := jwt.Parse(raw, jwt.WithKeySet(set))

If the JWS header has a kid, the matching key is selected from the set. The algorithm comes from each key's alg field. If a token omits kid and the set contains exactly one key, use jwt.WithKeySet(set, jws.WithUseDefault(true)). Use jws.WithRequireKid(false) only when every key in the set should be considered without matching kid values.

A key with no alg field is skipped, not guessed at. Inference from the key type is opt-in via jwt.WithKeySet(set, jws.WithInferAlgorithmFromKey(true)), and it is a fallback, not a default. When the protected header has an alg, inference tries only that algorithm against compatible keys. When the header omits alg, inference tries every compatible algorithm; combined with jws.WithRequireKid(false), verification can perform N_keys × N_algs_per_keytype attempts. Keep JWKS inputs bounded. The right fix is almost always to add alg to the keys in the JWKS. If verification against a JWKS finds no usable key, check for missing alg fields first.

jwk.Parse retains an unparseable JWKS entry as a jwk.UnsupportedKey by default, so one unknown key type does not make the whole set fail. Use jwk.IsUnsupportedKey when inspecting entries. Pass jwk.WithStrictKeySetParsing(true) when every entry must parse or the whole operation must fail.

Verifying via JWKS endpoint

HTTP fetching is not in the core jwk package in v4. It lives in a companion module:

import "github.com/jwx-go/jwkfetch/v4"

client := jwkfetch.NewClient()
set, err := client.Fetch(ctx, "https://issuer.example/jwks.json")
// then: jwt.Parse(raw, jwt.WithKeySet(set))

For repeated fetches with background refresh, use jwkfetch.NewCache. For jku-driven verification, build a jwkfetch.Client with a jwkfetch.NewMapWhitelist() of allowed URLs and pass it to jwt.WithVerifyAuto(client).

Signing a JWT

tok, err := jwt.NewBuilder().
    Issuer("https://issuer.example").
    Audience([]string{"https://api.example"}).
    Subject("user-123").
    IssuedAt(time.Now()).
    Expiration(time.Now().Add(15 * time.Minute)).
    Claim("scope", "read:things").
    Build()
if err != nil { return err }

signed, err := jwt.Sign(tok, jwt.WithKey(jwa.RS256(), privateKey))

privateKey may be a *rsa.PrivateKey/*ecdsa.PrivateKey/ed25519.PrivateKey/HMAC []byte, or a jwk.Key.

Match algorithm to key type:

JWK basics

jwk.Import and jwk.Export require the type parameter. The parsers do not: jwk.ParseKey and jwk.Parse are non-generic, and jwk.ParseKeyAs[T] is the typed variant.

// Parse a single JWK (returns jwk.Key):
key, err := jwk.ParseKey(jwkBytes)

// Parse a single JWK with a concrete type (fails if not that type):
rsaKey, err := jwk.ParseKeyAs[jwk.RSAPublicKey](jwkBytes)

// Parse a JWK Set (returns jwk.Set, not generic):
set, err := jwk.Parse(jwksBytes)

// Wrap an existing crypto.* key as a jwk.Key:
key, err := jwk.Import[jwk.Key](rsaPrivKey)

// Or with a concrete jwk type:
typed, err := jwk.Import[jwk.RSAPrivateKey](rsaPrivKey)

// Export a jwk.Key back to a crypto.* key:
raw, err := jwk.Export[*rsa.PublicKey](key)

jwk.Import[jwk.Key] is the default. Use a concrete type parameter (jwk.RSAPrivateKey, jwk.ECDSAPublicKey, jwk.SymmetricKey, jwk.OKPPublicKey, etc.) only when you want compile-time guarantees and acceptance of failure when the input is anything else.

Generating keys

import (
    "crypto/rand"
    "crypto/rsa"

    "github.com/lestrrat-go/jwx/v4/jwa"
    "github.com/lestrrat-go/jwx/v4/jwk"
)

raw, _ := rsa.GenerateKey(rand.Reader, 2048)
key, _ := jwk.Import[jwk.Key](raw)
key.Set(jwk.KeyIDKey, "2025-q1")
key.Set(jwk.AlgorithmKey, jwa.RS256())

pubKey, _ := jwk.PublicKeyOf(key)

jwk.KeyIDKey and jwk.AlgorithmKey are string constants for the standard JWK fields kid and alg.

JWS (signing arbitrary payloads)

sig, err := jws.Sign(payload, jws.WithKey(jwa.ES256(), privateKey))
payload, err := jws.Verify(sig, jws.WithKey(jwa.ES256(), publicKey))

jws.Parse only parses the structure — it does not verify. Use jws.Verify (which returns the verified payload) for verification.

For RFC 7518 ECDSA signing or verification, pass jws.WithStrictECDSA(true) to reject ES256/P-256, ES384/P-384, and ES512/P-521 curve mismatches. The check is opt-in. Pass it through JWT signing as jwt.WithSignOption(jws.WithStrictECDSA(true)), or JWT parsing as jwt.WithVerifyOption(jws.WithStrictECDSA(true)). This also applies to keys selected from a JWKS. jws.VerifyCompactFast does not accept options; use jws.Verify for strict ECDSA verification.

The protected alg must match the verifying algorithm exactly

jws.Verify rejects a message whose protected header advertises one algorithm while it is verified under another. The comparison is plain string equality with no aliasing, and it applies to every key source (jws.WithKey, jws.WithKeySet, jws.WithVerifyAuto, custom jws.WithKeyProvider). The check only fires when the protected header actually carries an alg.

The practical consequence involves EdDSA. Per RFC 9864, EdDSA, Ed25519 and Ed448 are three distinct alg values, so a token whose header says alg: Ed25519 does not verify under jws.WithKey(jwa.EdDSA(), key), and vice versa. Match the identifier the producer actually emitted.

jws.WithSkipAlgorithmMatch(true) bypasses the check. It exists for interop with non-conforming producers, and it weakens a real safety guard, so treat it the way you treat jws.WithRequireKid(false).

JWE (encrypting payloads)

enc, err := jwe.Encrypt(
    payload,
    jwe.WithKey(jwa.RSA_OAEP_256(), recipientPublicKey),
    jwe.WithContentEncryption(jwa.A256GCM()),
)

plain, err := jwe.Decrypt(enc, jwe.WithKey(jwa.RSA_OAEP_256(), recipientPrivateKey))

jwe.WithKey(alg, key) is the same on both encrypt and decrypt sides — this symmetry is intentional.

Nested JWT (sign, then encrypt)

Use jwt.NewSerializer() to sign a token and then encrypt the result. The steps run in the order they are called, so Sign(...) followed by Encrypt(...) produces a JWE whose payload is the signed JWT.

nested, err := jwt.NewSerializer().
    Sign(jwt.WithKey(jwa.RS256(), signerPrivateKey)).
    Encrypt(
        jwt.WithKey(jwa.RSA_OAEP_256(), recipientPublicKey),
        jwt.WithEncryptOption(jwe.WithContentEncryption(jwa.A256GCM())),
    ).
    Serialize(tok)

• Pass jwe options to the encrypt step with jwt.WithEncryptOption, and jws options to the sign step with jwt.WithSignOption. The content encryption defaults to A256GCM when jwe.WithContentEncryption is not given.
• jwt.Parse does not decrypt. On the receiving side, decrypt the JWE first, then verify and validate the inner JWT:

signed, err := jwe.Decrypt(nested, jwe.WithKey(jwa.RSA_OAEP_256(), recipientPrivateKey))
if err != nil { return err }

tok, err := jwt.Parse(signed, jwt.WithKey(jwa.RS256(), signerPublicKey))

• Serialize returns the JWE in compact form as []byte, and jwe.Decrypt returns the inner signed JWT as []byte.
• Decrypting only proves the message was encrypted to the recipient. The jwt.Parse step is what proves who signed the token, so NEVER skip it or replace it with jwt.ParseInsecure after decrypting.