Documentation
¶
Overview ¶
Package keyfetch retrieve and cache PublicKeys from OIDC (https://example.com/.well-known/openid-configuration) and Auth0 (https://example.com/.well-known/jwks.json) JWKs URLs and expires them when `exp` is reached (or a default expiry if the key does not provide one). It uses the keypairs package to Unmarshal the JWKs into their native types (with a very thin shim to provide the type safety that Go's crypto.PublicKey and crypto.PrivateKey interfaces lack).
Index ¶
- Variables
- func Fetch(url string) (keypairs.PublicKey, error)
- func Get(kidOrThumb, iss string) keypairs.PublicKey
- func JWK(kidOrThumb, iss string) (keypairs.PublicKey, error)
- func OIDCJWK(kidOrThumb, iss string) (keypairs.PublicKey, error)
- func PEM(url string) (keypairs.PublicKey, error)
- func WellKnownJWK(kidOrThumb, iss string) (keypairs.PublicKey, error)
- type CachableKey
- type PublicKeysMap
- type Whitelist
Constants ¶
This section is empty.
Variables ¶
var DefaultKeyDuration = 48 * time.Hour
DefaultKeyDuration defines how long a key should be considered fresh (48 hours by default)
var EInvalidJWKURL = errors.New("url does not lead to valid JWKs")
EInvalidJWKURL means that the url did not provide JWKs
var ErrInsecureDomain = errors.New("Whitelists should only allow secure URLs (i.e. https://). To allow unsecured private networking (i.e. Docker) pass PrivateWhitelist as a list of private URLs")
ErrInsecureDomain means that plain http was used where https was expected
var KeyCache = map[string]CachableKey{}
KeyCache is an in-memory key cache
var KeyCacheMux = sync.Mutex{}
KeyCacheMux is used to guard the in-memory cache
var MaximumKeyDuration = 72 * time.Hour
MaximumKeyDuration defines the maximum time that a key will be cached (72 hours by default)
var MinimumKeyDuration = time.Hour
MinimumKeyDuration defines the minimum time that a key will be cached (1 hour by default)
var StaleTime = 15 * time.Minute
StaleTime defines when public keys should be renewed (15 minutes by default)
Functions ¶
func Get ¶
Get retrieves a key from cache, or returns an error. The issuer string may be empty if using a thumbprint rather than a kid.
func JWK ¶
JWK tries to return a key from cache, falling back to the /.well-known/jwks.json of the issuer
func OIDCJWK ¶
OIDCJWK fetches baseURL + ".well-known/openid-configuration" and then returns the key matching kid (or thumbprint)
Types ¶
type CachableKey ¶
CachableKey represents
type PublicKeysMap ¶
PublicKeysMap is a newtype for a map of keypairs.PublicKey
func JWKs ¶
func JWKs(jwksurl string) (PublicKeysMap, error)
JWKs returns a map of keys identified by their thumbprint (since kid may or may not be present)
func OIDCJWKs ¶
func OIDCJWKs(baseURL string) (PublicKeysMap, error)
OIDCJWKs fetches baseURL + ".well-known/openid-configuration" and then fetches and returns the Public Keys.
func WellKnownJWKs ¶
func WellKnownJWKs(kidOrThumb, iss string) (PublicKeysMap, error)
WellKnownJWKs fetches baseURL + ".well-known/jwks.json" and caches and returns the keys
type Whitelist ¶
Whitelist is a newtype for an array of URLs
func NewWhitelist ¶
NewWhitelist turns an array of URLs (such as https://example.com/) into a parsed array of *url.URLs that can be used by the IsTrustedIssuer function
func (Whitelist) IsTrustedIssuer ¶
IsTrustedIssuer returns true when the `iss` (i.e. from a token) matches one
in the provided whitelist (also matches wildcard domains).
You may explicitly allow insecure http (i.e. for automated testing) by
including http:// Otherwise the scheme in each item of the whitelist should
include the "https://" prefix.
SECURITY CONSIDERATIONS (Please Read)
You'll notice that *http.Request is optional. It should only be used under these
three circumstances:
1) Something else guarantees http -> https redirection happens before the
connection gets here AND this server directly handles TLS/SSL.
2) If you're using a load balancer or web server, and this doesn't handle
TLS/SSL directly, that server is _explicitly_ configured to protect
against Domain Fronting attacks. As of 2019, most web servers and load
balancers do not protect against that by default.
3) If you only use it to make your automated integration testing more
and it isn't enabled in production.
Otherwise, DO NOT pass in *http.Request as you will introduce a 0-day
vulnerability allowing an attacker to spoof any token issuer of their choice.
The only reason I allowed this in a public library where non-experts would
encounter it is to make testing easier.
Source Files
Directories