Documentation
¶
Overview ¶
Package rs provides bearer-token middleware for resource servers protected by an authlet AS.
Index ¶
Constants ¶
const DefaultMinRefreshInterval = time.Minute
DefaultMinRefreshInterval is the minimum spacing between upstream JWKS fetches once the cache is stale. It bounds how often a stale cache (e.g. during an upstream outage, or a flood of unknown kids arriving after expiry) can trigger a serialized upstream refresh.
Variables ¶
var ErrNoKey = errors.New("rs: no matching JWKS key")
ErrNoKey is returned by JWKSClient.Key when the requested kid is not present in the freshly fetched JWKS document.
Functions ¶
func FromContext ¶
FromContext retrieves the claims attached by Middleware. The second return value is false when no claims were stored (e.g. the request bypassed the middleware).
func Middleware ¶
Middleware wraps next with bearer-token validation. On success it invokes next with the parsed claims placed on the request context under ContextKey{}. On any failure it writes a 401 with an RFC 9728-style WWW-Authenticate challenge and does not call next.
Types ¶
type Config ¶
type Config struct {
// ExpectedIssuer is the iss value tokens must carry. Empty disables the
// issuer check.
ExpectedIssuer string
// ExpectedAudience is the aud value tokens must carry. Empty disables
// the audience check.
ExpectedAudience string
// JWKS resolves token kids to RSA public keys.
JWKS *JWKSClient
// ResourceMetadata is the absolute URL of this resource's Protected
// Resource Metadata document (RFC 9728). When set it is embedded in the
// WWW-Authenticate challenge so clients can discover the AS.
ResourceMetadata string
}
Config configures bearer validation. JWKS is required; the other fields narrow what tokens are accepted and shape the 401 challenge response.
type ContextKey ¶
type ContextKey struct{}
ContextKey is the value type used to stash validated claims on the request context. Use FromContext to retrieve them in protected handlers.
type JWKSClient ¶
type JWKSClient struct {
// contains filtered or unexported fields
}
JWKSClient fetches and caches a remote JWKS, honouring ETag-based conditional refresh so unchanged documents incur no redundant decoding.
func NewJWKSClient ¶
func NewJWKSClient(jwksURL string, ttl time.Duration) *JWKSClient
NewJWKSClient builds a client that fetches the JWKS document at jwksURL and caches parsed keys for ttl. A ttl of 0 selects the default of one hour.
func (*JWKSClient) Key ¶
Key returns the RSA public key for kid.
The cache is refreshed from the upstream JWKS endpoint ONLY when it is actually stale (past expiresAt). A cache miss while the cache is still fresh returns ErrNoKey without any upstream fetch — otherwise a flood of bearer tokens carrying random unknown kids would force a serialized refresh on every request and stall all token validation (DoS).
When the cache is stale, refreshes are additionally rate-limited to at most one per minRefreshInterval so repeated misses during an upstream outage (or a stale-window flood) cannot trigger unbounded serialized fetches. Within that backoff window the (stale) cache is served as-is.
The lock is held for the entire refresh so concurrent callers serialise rather than producing a thundering herd of upstream JWKS fetches.
Source Files