middleware

Documentation

Overview

Package middleware provides a standard set of middleware implementations for pomerium.

Index

• func Healthcheck(endpoint, msg string) func(http.Handler) http.Handler
• func SameDomain(u, j *url.URL) bool
• func SetHeaders(securityHeaders map[string]string) func(next http.Handler) http.Handler
• func SignRequest(signer cryptutil.JWTSigner, id, email, groups, header string) func(next http.Handler) http.Handler
• func StripPomeriumCookie(cookieName string) func(next http.Handler) http.Handler
• func ValidSignature(redirectURI, sigVal, timestamp, secret string) bool
• func ValidateClientSecret(sharedSecret string) func(next http.Handler) http.Handler
• func ValidateHost(validHost func(host string) bool) func(next http.Handler) http.Handler
• func ValidateRedirectURI(rootDomain *url.URL) func(next http.Handler) http.Handler
• func ValidateSignature(sharedSecret string) func(next http.Handler) http.Handler
• type Chain
  • func NewChain(constructors ...Constructor) Chain
  • func (c Chain) Append(constructors ...Constructor) Chain
  • func (c Chain) Extend(chain Chain) Chain
  • func (c Chain) Then(h http.Handler) http.Handler
  • func (c Chain) ThenFunc(fn http.HandlerFunc) http.Handler
• type Constructor
• type SharedSecretCred
  • func NewSharedSecretCred(secret string) *SharedSecretCred
  • func (s SharedSecretCred) GetRequestMetadata(context.Context, ...string) (map[string]string, error)
  • func (s SharedSecretCred) RequireTransportSecurity() bool
  • func (s SharedSecretCred) ValidateRequest(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, ...) (interface{}, error)

Functions

func Healthcheck

func Healthcheck(endpoint, msg string) func(http.Handler) http.Handler

Healthcheck endpoint middleware useful to setting up a path like `/ping` that load balancers or uptime testing external services can make a request before hitting any routes. It's also convenient to place this above ACL middlewares as well.

func SameDomain

func SameDomain(u, j *url.URL) bool

SameDomain checks to see if two URLs share the top level domain (TLD Plus One).

func SetHeaders

func SetHeaders(securityHeaders map[string]string) func(next http.Handler) http.Handler

SetHeaders ensures that every response includes some basic security headers

func SignRequest

func SignRequest(signer cryptutil.JWTSigner, id, email, groups, header string) func(next http.Handler) http.Handler

func StripPomeriumCookie

func StripPomeriumCookie(cookieName string) func(next http.Handler) http.Handler

StripPomeriumCookie ensures that every response includes some basic security headers

func ValidSignature

func ValidSignature(redirectURI, sigVal, timestamp, secret string) bool

ValidSignature checks to see if a signature is valid. Compares hmac of redirect uri, timestamp, and secret and signature.

func ValidateClientSecret

func ValidateClientSecret(sharedSecret string) func(next http.Handler) http.Handler

ValidateClientSecret checks the request header for the client secret and returns an error if it does not match the proxy client secret

func ValidateHost

func ValidateHost(validHost func(host string) bool) func(next http.Handler) http.Handler

ValidateHost ensures that each request's host is valid

func ValidateRedirectURI

func ValidateRedirectURI(rootDomain *url.URL) func(next http.Handler) http.Handler

ValidateRedirectURI checks the redirect uri in the query parameters and ensures that the its domain is in the list of proxy root domains.

func ValidateSignature

func ValidateSignature(sharedSecret string) func(next http.Handler) http.Handler

ValidateSignature ensures the request is valid and has been signed with the correspdoning client secret key

Types

type Chain

type Chain struct {
	// contains filtered or unexported fields
}

Chain acts as a list of http.Handler constructors. Chain is effectively immutable: once created, it will always hold the same set of constructors in the same order.

func NewChain

func NewChain(constructors ...Constructor) Chain

NewChain creates a new chain, memorizing the given list of middleware constructors. New serves no other function, constructors are only called upon a call to Then().

func (Chain) Append

func (c Chain) Append(constructors ...Constructor) Chain

Append extends a chain, adding the specified constructors as the last ones in the request flow.

Append returns a new chain, leaving the original one untouched.

stdChain := middleware.NewChain(m1, m2)
extChain := stdChain.Append(m3, m4)
// requests in stdChain go m1 -> m2
// requests in extChain go m1 -> m2 -> m3 -> m4

func (Chain) Extend

func (c Chain) Extend(chain Chain) Chain

Extend extends a chain by adding the specified chain as the last one in the request flow.

Extend returns a new chain, leaving the original one untouched.

stdChain := middleware.NewChain(m1, m2)
ext1Chain := middleware.NewChain(m3, m4)
ext2Chain := stdChain.Extend(ext1Chain)
// requests in stdChain go  m1 -> m2
// requests in ext1Chain go m3 -> m4
// requests in ext2Chain go m1 -> m2 -> m3 -> m4

Another example:

 aHtmlAfterNosurf := middleware.NewChain(m2)
	aHtml := middleware.NewChain(m1, func(h http.Handler) http.Handler {
		csrf := nosurf.NewChain(h)
		csrf.SetFailureHandler(aHtmlAfterNosurf.ThenFunc(csrfFail))
		return csrf
	}).Extend(aHtmlAfterNosurf)
		// requests to aHtml hitting nosurfs success handler go m1 -> nosurf -> m2 -> target-handler
		// requests to aHtml hitting nosurfs failure handler go m1 -> nosurf -> m2 -> csrfFail

func (Chain) Then

func (c Chain) Then(h http.Handler) http.Handler

Then chains the middleware and returns the final http.Handler.

NewChain(m1, m2, m3).Then(h)

is equivalent to:

m1(m2(m3(h)))

When the request comes in, it will be passed to m1, then m2, then m3 and finally, the given handler (assuming every middleware calls the following one).

A chain can be safely reused by calling Then() several times.

stdStack := middleware.NewChain(ratelimitHandler, csrfHandler)
indexPipe = stdStack.Then(indexHandler)
authPipe = stdStack.Then(authHandler)

Note that constructors are called on every call to Then() and thus several instances of the same middleware will be created when a chain is reused in this way. For proper middleware, this should cause no problems.

Then() treats nil as http.DefaultServeMux.

func (Chain) ThenFunc

func (c Chain) ThenFunc(fn http.HandlerFunc) http.Handler

ThenFunc works identically to Then, but takes a HandlerFunc instead of a Handler.

The following two statements are equivalent:

c.Then(http.HandlerFunc(fn))
c.ThenFunc(fn)

ThenFunc provides all the guarantees of Then.

type Constructor

type Constructor func(http.Handler) http.Handler

Constructor is a type alias for func(http.Handler) http.Handler

type SharedSecretCred

type SharedSecretCred struct {
	// contains filtered or unexported fields
}

SharedSecretCred is a simple token-based method of mutual authentication.

func NewSharedSecretCred

func NewSharedSecretCred(secret string) *SharedSecretCred

NewSharedSecretCred returns a new instance of shared secret credential middleware for gRPC clients

func (SharedSecretCred) GetRequestMetadata

func (s SharedSecretCred) GetRequestMetadata(context.Context, ...string) (map[string]string, error)

GetRequestMetadata sets the value for "authorization" key

func (SharedSecretCred) RequireTransportSecurity

func (s SharedSecretCred) RequireTransportSecurity() bool

RequireTransportSecurity should be true as we want to have it encrypted over the wire.

func (SharedSecretCred) ValidateRequest

func (s SharedSecretCred) ValidateRequest(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error)

ValidateRequest ensures a valid token exists within a request's metadata. If the token is missing or invalid, the interceptor blocks execution of the handler and returns an error. Otherwise, the interceptor invokes the unary handler.