Defaults and hard limits¶
Every default value the package applies, and every limit it enforces that you cannot change.
Configurable defaults¶
Applied by NewJWTVerifier when the corresponding JWTConfig field is left at its zero
value. Full descriptions are in JWTConfig fields.
| Setting | Default | Set it via |
|---|---|---|
| JWT leeway | 60s |
JWTConfig.Leeway |
| JWKS staleness threshold | 15m |
JWTConfig.RefreshInterval |
| Accepted algorithms | RS256 RS384 RS512 ES256 ES384 ES512 |
JWTConfig.AllowedAlgorithms |
| HTTP client | &http.Client{Timeout: 10 * time.Second} |
JWTConfig.HTTPClient |
| mTLS subject derivation | Common Name → first DNS SAN → first URI SAN | WithCertSubject |
| Audience check | disabled | JWTConfig.Audiences |
Leeway and RefreshInterval are replaced by their defaults whenever the supplied
value is less than or equal to zero, so neither can be set to zero or to a negative
duration.
Hard limits you cannot configure¶
These are package constants. There is no option, field or environment variable that changes them.
| Limit | Value | What it protects against | What happens when exceeded |
|---|---|---|---|
| JWKS document size | 1 MiB | a hostile or misconfigured endpoint streaming forever | fetch fails: authn: JWKS document exceeds 1048576 bytes |
| Keys per JWKS document | 64 | an endpoint publishing an unbounded key set | fetch fails: authn: JWKS document has 65 keys, max 64 |
| Minimum interval between JWKS fetch attempts | 30s | a stream of unknown-kid tokens hammering the endpoint |
the refresh is skipped; the token is rejected against the current cache |
| JWKS fetch timeout | 10s | a hanging endpoint stalling requests | fetch fails with a context deadline error |
| OIDC discovery timeout | 10s | as above, for the discovery document | discovery fails with a context deadline error |
| OIDC discovery document size | 1 MiB | as above | the body is truncated at the limit, so parsing fails with authn: parse OIDC discovery document: … |
The 10-second fetch timeout applies as a context deadline on top of whatever timeout
your own HTTPClient carries, so supplying a client with a 60-second timeout does not
extend it.
Enforced protocol constraints¶
| Constraint | Behaviour when violated |
|---|---|
JWKSURL scheme must be https |
construction fails: authn: JWKS URL must be HTTPS, got "http" |
OIDC issuer URL scheme must be https |
construction fails: authn: OIDC issuer URL must be HTTPS, got "http" |
OIDC document issuer must equal the URL passed to WithOIDCDiscovery |
construction fails: authn: OIDC document issuer "…" does not match "…" |
alg: none is never accepted |
construction fails: authn: algorithm "none" is never allowed |
| HMAC algorithms are never accepted | construction fails: authn: HMAC algorithm "HS256" is not allowed with a JWKS (alg-confusion defence) |
exp is required on every token |
verification fails: token is missing required claim: exp claim is required |
iss is required on every token |
verification fails: token is missing required claim: iss claim is required |
| At least one API key must be configured | construction fails: authn: API-key verifier requires at least one key (fail-closed) |
Supported key material¶
JWK kty |
Supported | Notes |
|---|---|---|
RSA |
Yes | modulus and exponent as base64url; the exponent must be between 2 and 2³¹−1 |
EC |
Yes | curves P-256, P-384, P-521 only |
anything else (oct, OKP, …) |
No | the key is skipped silently and the rest of the document is kept |
OKP being unsupported means Ed25519 signing keys published in a JWKS cannot be
used, even though golang-jwt can verify EdDSA tokens.