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.
A fresh cache hit returns immediately with no upstream fetch. Any MISS — an unknown kid on a still-fresh cache, or any lookup on a stale cache — attempts a refresh, because a signing-key rotation immediately mints tokens under a new kid the fresh cache does not yet know; without this, every newly issued token would 401 until the TTL lapsed.
Refreshes (on either path) are rate-limited to at most one per minRefreshInterval, so a flood of bearer tokens carrying random unknown kids cannot force more than one serialized upstream fetch per interval (DoS guard); within that backoff window the cache is served as-is. A rotated kid is thus picked up within minRefreshInterval rather than the full cache TTL.
The lock is held for the entire refresh so concurrent callers serialise rather than producing a thundering herd of upstream JWKS fetches.
Source Files