From 06ad81c205afb476200800409931685d03703c75 Mon Sep 17 00:00:00 2001 From: Jon Carl Date: Fri, 16 Jul 2021 15:27:41 -0600 Subject: [PATCH 1/2] add migration guide Signed-off-by: Jon Carl --- README.md | 78 ++++++++++++++++++++++++++++++++++++++++++++++++ jwtmiddleware.go | 9 ------ 2 files changed, 78 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index a82672c9..4a386183 100644 --- a/README.md +++ b/README.md @@ -102,6 +102,84 @@ should give you a response like ... ``` +## Migration Guide +If you are moving from v1 to v2 this is the place for you. + +### `jwtmiddleware.Options` +Now handled by individual [jwtmiddleware.Option](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#Option) items. They can be passed to [jwtmiddleware.New](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#New) after the [jwtmiddleware.ValidateToken](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#ValidateToken) input: +```golang +jwtmiddleware.New(validator, WithCredentialsOptional(true), ...) +``` + +#### `ValidationKeyGetter` +Token validation is now handled via a token provider which can be learned about in the section on [jwtmiddleware.New](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#New). + +#### `UserProperty` +This is now handled in the validation provider. + +#### `ErrorHandler` +We now provide a public [jwtmiddleware.ErrorHandler](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#ErrorHandler) type: +```golang +type ErrorHandler func(w http.ResponseWriter, r *http.Request, err error) +``` + +A [default](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#DefaultErrorHandler) is provided which translates errors into HTTP status codes. + +You might want to wrap the default so you can hook things into logging: +```golang +myErrHandler := func(w http.ResponseWriter, r *http.Request, err error) { + fmt.Printf("error in token validation: %+v\n", err) + + jwtmiddleware.DefaultErrorHandler(w, r, err) +} + +jwtMiddleware := jwtmiddleware.New(validator.ValidateToken, jwtmiddleware.WithErrorHandler(myErrHandler)) +``` + +#### `CredentialsOptional` +Use the option function [jwtmiddleware.WithCredentialsOptional(true|false)](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#WithCredentialsOptional). Default is false. + +#### `Extractor` +Use the option function [jwtmiddleware.WithTokenExtractor](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#WithTokenExtractor). Default is to extract tokens from the auth header. + +We provide 3 different token extractors: +- [jwtmiddleware.AuthHeaderTokenExtractor](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#AuthHeaderTokenExtractor) a rename of `jwtmiddleware.FromAuthHeader`. +- [jwtmiddleware.CookieTokenExtractor](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#CookieTokenExtractor) a new extractor. +- [jwtmiddleware.ParameterTokenExtractor](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#ParameterTokenExtractor) a rename of `jwtmiddleware.FromParameter`. + +And also an extractor which can combine multiple different extractors together: [jwtmiddleware.MultiTokenExtractor](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#MultiTokenExtractor) a rename of `jwtmiddleware.FromFirst`. + +#### `Debug` +Dropped. We don't believe that libraries should be logging so we have removed this option. +If you need more details of when things go wrong the errors should give the details you need. + +#### `EnableAuthOnOptions` +Use the option function [jwtmiddleware.WithValidateOnOptions(true|false)](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#WithValidateOnOptions). Default is true. + +#### `SigningMethod` +This is now handled in the validation provider. + +### `jwtmiddleware.New` +A token provider is setup in the middleware by passing a [jwtmiddleware.ValidateToken](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#ValidateToken) function: +```golang +func(context.Context, string) (interface{}, error) +``` +to [jwtmiddleware.New](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#New). + +In the example above you can see [github.com/auth0/go-jwt-middleware/validate/josev2](https://pkg.go.dev/github.com/auth0/go-jwt-middleware@v2.0.0/validate/josev2) being used. + +This change was made in order to allow JWT validation provider to be easily switched out. + +Options are passed into `jwtmiddleware.New` after validation provider and use the `jwtmiddleware.With...` functions to set options. + +### `jwtmiddleware.Handler*` +Both `jwtmiddleware.HandlerWithNext` and `jwtmiddleware.Handler` have been dropped. +You can use [jwtmiddleware.CheckJWT](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#CheckJWT) instead which takes in an `http.Handler` and returns an `http.Handler`. + +### `jwtmiddleware.CheckJWT` +This function has been reworked to be the main middleware handler piece and so we've dropped the functionality of it returning and error. +If you need to handle any errors please use the [jwtmiddleware.WithErrorHandler](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#WithErrorHandler) function. + ## Issue Reporting If you have found a bug or if you have a feature request, please report them at this repository issues section. Please do not report security vulnerabilities on the public GitHub issue tracker. The [Responsible Disclosure Program](https://auth0.com/whitehat) details the procedure for disclosing security issues. diff --git a/jwtmiddleware.go b/jwtmiddleware.go index 18c9577a..79d070a1 100644 --- a/jwtmiddleware.go +++ b/jwtmiddleware.go @@ -76,15 +76,6 @@ type JWTMiddleware struct { // Option is how options for the middleware are setup. type Option func(*JWTMiddleware) -// WithValidateToken sets up the function to be used to validate all tokens. -// See the ValidateToken type for more information. -// Default: TODO: after merge into `v2` -func WithValidateToken(vt ValidateToken) Option { - return func(m *JWTMiddleware) { - m.validateToken = vt - } -} - // WithErrorHandler sets the handler which is called when there are errors in // the middleware. See the ErrorHandler type for more information. // Default value: DefaultErrorHandler From d67ba569d921e5cc2d4f4c0c2679855194e79d2b Mon Sep 17 00:00:00 2001 From: Jon Carl Date: Fri, 16 Jul 2021 15:32:59 -0600 Subject: [PATCH 2/2] fix wrong link Signed-off-by: Jon Carl --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 4a386183..d5fbd68a 100644 --- a/README.md +++ b/README.md @@ -174,7 +174,7 @@ Options are passed into `jwtmiddleware.New` after validation provider and use th ### `jwtmiddleware.Handler*` Both `jwtmiddleware.HandlerWithNext` and `jwtmiddleware.Handler` have been dropped. -You can use [jwtmiddleware.CheckJWT](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#CheckJWT) instead which takes in an `http.Handler` and returns an `http.Handler`. +You can use [jwtmiddleware.CheckJWT](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#JWTMiddleware.CheckJWT) instead which takes in an `http.Handler` and returns an `http.Handler`. ### `jwtmiddleware.CheckJWT` This function has been reworked to be the main middleware handler piece and so we've dropped the functionality of it returning and error.