Documentation
¶
Overview ¶
Package jwks is the issuer key cache behind every AuthKit verifier: it fetches an issuer's JWKS, serves it stale-while-revalidate up to a max staleness, refetches on key rotation, and reports health. Public verify uses it for the issuers a host adds; the engine for remote applications.
Index ¶
Constants ¶
const ( DefaultTTL = 10 * time.Minute DefaultMaxStale = 4 * time.Hour )
Default cache policy.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Cache ¶
type Cache struct {
// AttemptTimeout bounds one fetch; a failing issuer is retried in the
// background with capped full-jitter backoff. RefetchMin spaces the
// refetches an unknown kid or bad signature forces. Now is the clock.
AttemptTimeout time.Duration
BackoffBase, BackoffMax time.Duration
RefetchMin time.Duration
Now func() time.Time
// contains filtered or unexported fields
}
Cache holds fetched keys per issuer. Every count in it is bounded by the issuers its owner registered, never by request traffic.
func New ¶
New returns a cache fetching with client (nil: a timeout-bounded client that may reach private addresses).
func (*Cache) Check ¶
Check is a no-I/O health probe: it fails naming every issuer whose last fetch failed, with the age of its keys and whether they are past MaxStale.
func (*Cache) Key ¶
Key returns the key kid names from is's JWKS. A request waits only when the issuer has no usable keys, and then for at most one bounded attempt; an unknown kid on a healthy issuer forces one throttled refetch (rotation).
type Issuer ¶
type Issuer struct {
Issuer string
URL string
// TTL is how long fetched keys are fresh (default 10m).
TTL time.Duration
// MaxStale bounds how long after the last successful fetch keys keep
// verifying while refreshes fail, so a peer's revocation cannot be
// suppressed by blocking the fetch (default 4h, never below TTL).
MaxStale time.Duration
}
Issuer is one issuer's JWKS endpoint and cache policy.
type Status ¶
type Status struct {
Issuer string
JWKSURI string
Keys int
Fresh bool // keys are within the cache TTL
FetchedAt time.Time // last successful fetch; zero before the first
Age time.Duration
MaxStale time.Duration
Expired bool // Age exceeds MaxStale: verification fails closed
CheckedAt time.Time // last fetch attempt; zero before the first
Failures int // consecutive failed fetches
LastError string
}
Status is one issuer's key-refresh state. Age is the time since the last successful fetch (export Age.Seconds() as a gauge); past MaxStale its tokens fail with 503 issuer_keys_unavailable (Expired).
Source Files