jwks

Documentation

Overview

Package jwks is the issuer key cache behind every AuthKit verifier: an issuer's JWKS read through helpers/cache under cachepolicy.IssuerKeys, refetched on key rotation, with per-issuer health. Public verify uses it for the issuers a host adds; the engine for remote applications.

Index

• func Select(keys map[string]crypto.PublicKey, kid string) (crypto.PublicKey, error)
• type Cache
  • func New(client *http.Client, o cache.Options) *Cache
  • func (c *Cache) Check(ctx context.Context) error
  • func (c *Cache) Close()
  • func (c *Cache) Drop(iss string)
  • func (c *Cache) Key(ctx context.Context, is Issuer, kid string) (crypto.PublicKey, error)
  • func (c *Cache) Refresh(ctx context.Context, is Issuer) bool
  • func (c *Cache) Register(is Issuer)
  • func (c *Cache) Statuses() []Status
• type Issuer
• type Status

Functions

func Select

func Select(keys map[string]crypto.PublicKey, kid string) (crypto.PublicKey, error)

Select picks kid's key; an empty kid names the only key.

Types

type Cache

type Cache struct {
	// 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

func New(client *http.Client, o cache.Options) *Cache

New returns a cache fetching with client (nil: a timeout-bounded client that may reach private addresses) under policy o.

func (*Cache) Check

func (c *Cache) Check(ctx context.Context) error

Check is a health probe. It reads each issuer a token has needed through the cache, so a failing one is retried without token traffic (at most once per failure backoff), then fails naming every issuer whose last fetch failed, with the age of its keys and whether they are past MaxStale.

func (*Cache) Close

func (c *Cache) Close()

Close stops the cache's background work; it keeps serving.

func (*Cache) Drop

func (c *Cache) Drop(iss string)

Drop forgets iss's keys.

func (*Cache) Key

func (c *Cache) Key(ctx context.Context, is Issuer, kid string) (crypto.PublicKey, error)

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 load; an unknown kid on a healthy issuer forces one throttled refetch (rotation).

func (*Cache) Refresh

func (c *Cache) Refresh(ctx context.Context, is Issuer) bool

Refresh forces one throttled refetch of a healthy issuer's keys after a signature failed under them: a rotated key that kept its kid. It reports whether a refetch ran, so the caller retries once.

func (*Cache) Register

func (c *Cache) Register(is Issuer)

Register trusts is.URL for is.Issuer's keys, forgetting keys fetched from an earlier endpoint.

func (*Cache) Statuses

func (c *Cache) Statuses() []Status

Statuses reports every registered issuer, sorted by issuer.

type Issuer

type Issuer struct {
	Issuer string
	URL    string
}

Issuer is one issuer's JWKS endpoint.

type Status

type Status struct {
	Issuer    string
	JWKSURI   string
	Keys      int
	Fresh     bool      // keys are within the refresh interval
	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).