keyfetch

package
v0.6.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 2, 2020 License: MIT Imports: 11 Imported by: 2

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

Constants

This section is empty.

Variables

View Source
var DefaultKeyDuration = 48 * time.Hour

DefaultKeyDuration defines how long a key should be considered fresh (48 hours by default)

View Source
var EInvalidJWKURL = errors.New("url does not lead to valid JWKs")

EInvalidJWKURL means that the url did not provide JWKs

View Source
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

View Source
var KeyCache = map[string]CachableKey{}

KeyCache is an in-memory key cache

View Source
var KeyCacheMux = sync.Mutex{}

KeyCacheMux is used to guard the in-memory cache

View Source
var MaximumKeyDuration = 72 * time.Hour

MaximumKeyDuration defines the maximum time that a key will be cached (72 hours by default)

View Source
var MinimumKeyDuration = time.Hour

MinimumKeyDuration defines the minimum time that a key will be cached (1 hour by default)

View Source
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

Directories

Path Synopsis
Package uncached provides uncached versions of go-keypairs/keyfetch
Package uncached provides uncached versions of go-keypairs/keyfetch

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL