middleware

README

middleware

This is a shared middleware library for api development based on MUX. It uses Custom Auth module to validate AZURE AD JWT and provides some additional features like Content Validation and Logging.

• Installation

  • go get gitlab.com/terminix/middleware

• Features

  • JWT Authorization that works with Azure Active Directory
  • Support for scope validations from JWT (* Scope is pulled from "scp" claim)
  • Assignable scope per named route
  • Content type validations per named route
  • GZip compression leveraging https://github.com/gorilla/mux 's handler.CompressHandler
  • Apache Standard log formatting leveraging https://github.com/gorilla/mux 's handler.CombinedLoggingHandler

---

Authorization Example

//be sure and name your MUX routes
r.Handle("/hello", appHandler{config, HandleHello}).Methods(http.MethodPost).Name("Hello")
r.Handle("/goodbye", appHandler{config, HandleHello}).Methods(http.MethodPost).Name("Goodbye")

//define scopes for auth validation
const (
	writeScope = "Hello.Write"
	readScope = "Hello.Read"
)
//define a map table of scopes for each route.
routeAuthScopes = map[string]string{
	"Hello": writeScope,
	"Goodbye": readScope,
}
//define any routes that should not be authorized (such as healthcheck)
// a true value in the map will bypass auth
routeBypassScopes = map[string]bool{
	"Hello": false,
	"HealthCheck": true,
}

//Apply the settings
//use authorization middleware
amw := middleware.AuthMiddleWare{}
amw.SetAuthScopes(routeAuthScopes)
amw.SetAuthBypass(routeBypassScopes)
amw.SetOpenIDConfigURL("https://login.microsoft.com/....") //used to get openIDConfig
amw.SetValidAudience("api://ApplicationIDURI/") //used to validate the Audience in the token matches the Application ID URI from the AzureAppRegistration
r.Use(amw.Middleware)

Content Type Validation Example

//be sure and name your MUX routes
r.Handle("/hello", appHandler{config, HandleHello}).Methods(http.MethodPost).Name("Hello")
r.Handle("/goodbye", appHandler{config, HandleHello}).Methods(http.MethodPost).Name("Goodbye")
//define slice of accepted content types. 
contentTypeHello = []string{"application/json", "application/protobuf"}
contentTypeGoodbye = []string{"application/json"}
//create a map to hold the type for each route
routeAcceptedContents = map[string][]string{
	"Hello": contentTypeHello ,
	"Goodbye": contentTypeGoodbye ,
}

//Apply the settings
vmw := middleware.ValidatorMiddleWare{}
vmw.SetAcceptedContent(routeAcceptedContents)
//use validation middleware
r.Use(vmw.Middleware)

Logging Example

lmw := middleware.LoggingMiddleware{}
lmw.SetOutput(os.Stdout)//output accepts *os.File
r.Use(lmw.Middleware)

Compression Example

//set up compression for responses
cmw := middleware.CompressionMiddleware{}
r.Use(cmw.Middleware)

Documentation

Index

• type AuthMiddleWare
  • func (amw *AuthMiddleWare) Middleware(next http.Handler) http.Handler
  • func (amw *AuthMiddleWare) SetAuthBypass(bypassRoutes map[string]bool)
  • func (amw *AuthMiddleWare) SetAuthScopes(scopes map[string]string)
  • func (amw *AuthMiddleWare) SetOpenIDConfigURL(url string)
  • func (amw *AuthMiddleWare) SetValidAudience(audience string)
• type Claims
• type CompressionMiddleware
  • func (cmw *CompressionMiddleware) Middleware(next http.Handler) http.Handler
• type LoggingMiddleware
  • func (lmw *LoggingMiddleware) Middleware(next http.Handler) http.Handler
  • func (lmw *LoggingMiddleware) SetOutput(writer *os.File)
• type ValidatorMiddleWare
  • func (vmw *ValidatorMiddleWare) Middleware(next http.Handler) http.Handler
  • func (vmw *ValidatorMiddleWare) SetAcceptedContent(accepted map[string][]string)
  • func (vmw *ValidatorMiddleWare) SetValidationBypass(bypassRoutes map[string]bool)

Types

type AuthMiddleWare

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

AuthMiddleWare is the struct that contains the auth scope

func (*AuthMiddleWare) Middleware

func (amw *AuthMiddleWare) Middleware(next http.Handler) http.Handler

Middleware is the handler that checks validation.

func (*AuthMiddleWare) SetAuthBypass

func (amw *AuthMiddleWare) SetAuthBypass(bypassRoutes map[string]bool)

SetAuthBypass allows the server to specify a bypass on some routes

func (*AuthMiddleWare) SetAuthScopes

func (amw *AuthMiddleWare) SetAuthScopes(scopes map[string]string)

SetAuthScopes sets auth scopes

func (*AuthMiddleWare) SetOpenIDConfigURL

func (amw *AuthMiddleWare) SetOpenIDConfigURL(url string)

SetOpenIDConfigURL sets the endpoint for open id connect

func (*AuthMiddleWare) SetValidAudience

func (amw *AuthMiddleWare) SetValidAudience(audience string)

SetOpenIDConfigURL sets the endpoint for open id connect

type Claims

type Claims struct {
	Scp string `json:"scp"`
	jwt.StandardClaims
}

Claims is the object model of claims

type CompressionMiddleware

type CompressionMiddleware struct {
}

CompressionMiddleware applies gzip compression to requests

func (*CompressionMiddleware) Middleware

func (cmw *CompressionMiddleware) Middleware(next http.Handler) http.Handler

Middleware is the handler for compression

type LoggingMiddleware

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

LoggingMiddleware applies logging

func (*LoggingMiddleware) Middleware

func (lmw *LoggingMiddleware) Middleware(next http.Handler) http.Handler

Middleware is the handler for logging middleware

func (*LoggingMiddleware) SetOutput

func (lmw *LoggingMiddleware) SetOutput(writer *os.File)

SetOutput accepts an io.writer for log output

type ValidatorMiddleWare

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

ValidatorMiddleWare validates the content typs of a request

func (*ValidatorMiddleWare) Middleware

func (vmw *ValidatorMiddleWare) Middleware(next http.Handler) http.Handler

Middleware is the handler for content type validation

func (*ValidatorMiddleWare) SetAcceptedContent

func (vmw *ValidatorMiddleWare) SetAcceptedContent(accepted map[string][]string)

SetAcceptedContent sets the accepted content for a route.

func (*ValidatorMiddleWare) SetValidationBypass

func (vmw *ValidatorMiddleWare) SetValidationBypass(bypassRoutes map[string]bool)

SetValidationBypass sets routes that can be bypassed. For example, healthcheck routes