keyfetch

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
  • func JWKs(jwksurl string) (PublicKeysMap, error)
  • func OIDCJWKs(baseURL string) (PublicKeysMap, error)
  • func WellKnownJWKs(kidOrThumb, iss string) (PublicKeysMap, error)
• type Whitelist
  • func NewWhitelist(issuers []string, privateList ...[]string) (Whitelist, error)
  • func (w Whitelist) IsTrustedIssuer(iss string, rs ...*http.Request) bool
  • func (w Whitelist) String() string

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 Fetch

func Fetch(url string) (keypairs.PublicKey, error)

Fetch returns a key from cache, falling back to an exact url as the "issuer"

func Get

func Get(kidOrThumb, iss string) keypairs.PublicKey

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

func JWK(kidOrThumb, iss string) (keypairs.PublicKey, error)

JWK tries to return a key from cache, falling back to the /.well-known/jwks.json of the issuer

func OIDCJWK

func OIDCJWK(kidOrThumb, iss string) (keypairs.PublicKey, error)

OIDCJWK fetches baseURL + ".well-known/openid-configuration" and then returns the key matching kid (or thumbprint)

func PEM

func PEM(url string) (keypairs.PublicKey, error)

PEM tries to return a key from cache, falling back to the specified PEM url

func WellKnownJWK

func WellKnownJWK(kidOrThumb, iss string) (keypairs.PublicKey, error)

WellKnownJWK fetches baseURL + ".well-known/jwks.json" and returns the key matching kid (or thumbprint)

Types

type CachableKey

type CachableKey struct {
	Key    keypairs.PublicKey
	Expiry time.Time
}

CachableKey represents

type PublicKeysMap

type PublicKeysMap map[string]keypairs.PublicKey

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

type Whitelist []*url.URL

Whitelist is a newtype for an array of URLs

func NewWhitelist

func NewWhitelist(issuers []string, privateList ...[]string) (Whitelist, error)

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

func (w Whitelist) IsTrustedIssuer(iss string, rs ...*http.Request) bool

  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.

func (Whitelist) String

func (w Whitelist) String() string

String will generate a space-delimited list of whitelisted URLs