jwx

README

echo-middleware-jwx

JWT middleware for github.com/labstack/echo using github.com/lestrrat-go/jwx

WARNING: As of this writing, this is a proof of concept. The author does not usually develop web applications using github.com/labstack/echo. This library is provided in hopes that it will help you, but there may be bugs lurking. Contributions are welcome.

DESCRIPTION

This is pretty much a straight port of "github.com/labstack/echo/v4/middleware".JWT. The difference is this module uses github.com/lestrrat-go/jwx instead of github.com/dgrijalva/jwt-go to handle the JWT tokens.

Please note that there are a few differences. You are advised to read the code before using it.

SYNOPSIS

func main() {
  const googleCerts = `https://www.googleapis.com/oauth2/v3/certs`

  ctx, cancel := context.WithCancel(context.Background())
  defer cancel()

  e := echo.New()

  ar := jwk.NewAutoRefresh(ctx)
  ar.Configure(`https://www.googleapis.com/oauth2/v3/certs`, jwk.WithMinRefreshInterval(15*time.Minute))
  ks, err := ar.Refresh(ctx, googleCerts)
  if err != nil {
    panic(fmt.Sprintf("failed to refresh google JWKS: %s\n", err))
  }

  e.Use(jwx.JWX(ks))
  e.GET("/", func(c echo.Context) error {
    return c.String(http.StatusOK, "Hello, World!")
  })

  e.Start(":8000")
}

Documentation

Index

• Variables
• func DefaultSkipper(c echo.Context) bool
• func JWX(v interface{}) echo.MiddlewareFunc
• func WithConfig(config Config) echo.MiddlewareFunc
• type BeforeFunc
• type Config
• type JWTErrorHandler
• type JWTErrorHandlerWithContext
• type JWTSuccessHandler
• type Skipper

Variables

var (
	// DefaultConfig is the default JWX auth middleware config.
	DefaultConfig = Config{
		Skipper:            DefaultSkipper,
		SignatureAlgorithm: jwa.HS256,
		ContextKey:         "user",
		TokenLookup:        "header:" + echo.HeaderAuthorization,
		AuthScheme:         "Bearer",
		TokenFactory:       defaultTokenFactory,
	}
)

var ErrJWTInvalid = middleware.ErrJWTInvalid

var ErrJWTMissing = middleware.ErrJWTMissing

Functions

func DefaultSkipper

func DefaultSkipper(c echo.Context) bool

func JWX

func JWX(v interface{}) echo.MiddlewareFunc

func WithConfig

func WithConfig(config Config) echo.MiddlewareFunc

Types

type BeforeFunc

type BeforeFunc = middleware.BeforeFunc

type Config

type Config struct {
	// Skipper defines a function to skip middleware.
	Skipper Skipper

	// BeforeFunc defines a function which is executed just before the middleware.
	BeforeFunc BeforeFunc

	// SuccessHandler defines a function which is executed for a valid token.
	SuccessHandler JWTSuccessHandler

	// Context key to store user information from the token into context.
	// Optional. Default value "user".
	ContextKey string

	// ErrorHandler defines a function which is executed for an invalid token.
	// It may be used to define a custom JWT error.
	ErrorHandler JWTErrorHandler

	// ErrorHandlerWithContext is almost identical to ErrorHandler, but it's passed the current context.
	ErrorHandlerWithContext JWTErrorHandlerWithContext

	// TokenLookup is a string in the form of "<source>:<name>" that is used
	// to extract token from the request.
	// Optional. Default value "header:Authorization".
	// Possible values:
	// - "header:<name>"
	// - "query:<name>"
	// - "param:<name>"
	// - "cookie:<name>"
	// - "form:<name>"
	TokenLookup string

	// AuthScheme to be used in the Authorization header.
	// Optional. Default value "Bearer".
	AuthScheme string

	// KeySet defines the JWKS that is used to verify the keys against.
	//
	// Each key in the JWKS must have a valid "alg" field.
	//
	// If the JWS message contains a "kid" field, one of the keys in the JWKS must have a matching "kid" (on top of the "alg" field) for the verification to succeed
	// If the key needs periodic rotation, use jwk.AutoRefresh
	KeySet jwk.Set

	// KeyFunc is a user-defined function that supplies the key or key set for
	// token verification.
	//
	// If you simply want to refresh the key(s) to verify the token with, consider using
	// `github.com/lestrrat-go/jwx/jwk.AutoRefresh`, and set the key set in the KeySet field.
	KeyFunc func(echo.Context) (interface{}, error)

	// ValidateOptions defines the set of options to pass to jwt.Validate() in order to validate the JWT.
	//
	// See github.com/lestrrat-go/jwx/jwt for the various options available.
	ValidateOptions []jwt.ValidateOption

	// TokenFactory is a function that creates a new instance of a token.
	// Use it to tell jwx to use a different underlying token type (such as github.com/lestrrat-go/jwx/jwt/openid)
	//
	// Optional. Default function always creates a new token using jwt.New
	TokenFactory func(echo.Context) jwt.Token

	// Signing key to verify the token.
	//
	// If the key contains the "alg" header, its value is used when verifying the token.
	// Otherwise, the value in config.SignatureAlgorithm will be used.
	// If neither values are properly initialized, verification of the tokens will always fail.
	//
	// This is one of the three options to provide a token validation key.
	// The order of precedence is a user-defined KeyFunc, KeySet and Key.
	// Required if neither user-defined KeyFunc nor Keys is provided.
	Key jwk.Key

	// Signing algorithm used to verify the signature of the token
	// Optional. Default value HS256.
	SignatureAlgorithm jwa.SignatureAlgorithm
}

Config defines the config for JWT middleware (using github.com/lestrrat-go/jwx/jwt).

type JWTErrorHandler

type JWTErrorHandler = middleware.JWTErrorHandler

type JWTErrorHandlerWithContext

type JWTErrorHandlerWithContext = middleware.JWTErrorHandlerWithContext

type JWTSuccessHandler

type JWTSuccessHandler = middleware.JWTSuccessHandler

type Skipper

type Skipper = middleware.Skipper