README
¶
📚 Documentation • 🚀 Getting Started • 💬 Feedback
Documentation
- Godoc - explore the go-jwt-middleware documentation.
- Docs site — explore our docs site and learn more about Auth0.
- Quickstart - our guide for adding go-jwt-middleware to your app.
Getting started
Requirements
This library follows the same support policy as Go. The last two major Go releases are actively supported and compatibility issues will be fixed. While you may find that older versions of Go may work, we will not actively test and fix compatibility issues with these versions.
- Go 1.22+
Installation
go get github.com/auth0/go-jwt-middleware/v2
Usage
package main
import (
"context"
"encoding/json"
"log"
"net/http"
"github.com/auth0/go-jwt-middleware/v2"
"github.com/auth0/go-jwt-middleware/v2/validator"
jwtmiddleware "github.com/auth0/go-jwt-middleware/v2"
)
var handler = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
claims, ok := r.Context().Value(jwtmiddleware.ContextKey{}).(*validator.ValidatedClaims)
if !ok {
http.Error(w, "failed to get validated claims", http.StatusInternalServerError)
return
}
payload, err := json.Marshal(claims)
if err != nil {
http.Error(w, err.Error(), http.StatusInternalServerError)
return
}
w.Header().Set("Content-Type", "application/json")
w.Write(payload)
})
func main() {
keyFunc := func(ctx context.Context) (interface{}, error) {
// Our token must be signed using this data.
return []byte("secret"), nil
}
// Set up the validator.
jwtValidator, err := validator.New(
keyFunc,
validator.HS256,
"https://<issuer-url>/",
[]string{"<audience>"},
)
if err != nil {
log.Fatalf("failed to set up the validator: %v", err)
}
// Set up the middleware.
middleware := jwtmiddleware.New(jwtValidator.ValidateToken)
http.ListenAndServe("0.0.0.0:3000", middleware.CheckJWT(handler))
}
After running that code (go run main.go) you can then curl the http server from another terminal:
$ curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyLCJpc3MiOiJnby1qd3QtbWlkZGxld2FyZS1leGFtcGxlIiwiYXVkIjoiZ28tand0LW1pZGRsZXdhcmUtZXhhbXBsZSJ9.xcnkyPYu_b3qm2yeYuEgr5R5M5t4pN9s04U1ya53-KM" localhost:3000
That should give you the following response:
{
"CustomClaims": null,
"RegisteredClaims": {
"iss": "go-jwt-middleware-example",
"aud": "go-jwt-middleware-example",
"sub": "1234567890",
"iat": 1516239022
}
}
The JWT included in the Authorization header above is signed with secret.
To test how the response would look like with an invalid token:
$ curl -v -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.yiDw9IDNCa1WXCoDfPR_g356vSsHBEerqh9IvnD49QE" localhost:3000
That should give you the following response:
...
< HTTP/1.1 401 Unauthorized
< Content-Type: application/json
{"message":"JWT is invalid."}
...
For more examples please check the examples folder.
Feedback
Contributing
We appreciate feedback and contribution to this repo! Before you get started, please see the following:
Raise an issue
To provide feedback or report a bug, please raise an issue on our issue tracker.
Vulnerability Reporting
Please do not report security vulnerabilities on the public Github issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.
Auth0 is an easy to implement, adaptable authentication and authorization platform.
To learn more checkout Why Auth0?
This project is licensed under the MIT license. See the LICENSE file for more info.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrJWTMissing is returned when the JWT is missing. ErrJWTMissing = errors.New("jwt missing") // ErrJWTInvalid is returned when the JWT is invalid. ErrJWTInvalid = errors.New("jwt invalid") )
Functions ¶
func AuthHeaderTokenExtractor ¶
AuthHeaderTokenExtractor is a TokenExtractor that takes a request and extracts the token from the Authorization header.
func DefaultErrorHandler ¶
func DefaultErrorHandler(w http.ResponseWriter, r *http.Request, err error)
DefaultErrorHandler is the default error handler implementation for the JWTMiddleware. If an error handler is not provided via the WithErrorHandler option this will be used.
Types ¶
type ContextKey ¶
type ContextKey struct{}
ContextKey is the key used in the request context where the information from a validated JWT will be stored.
type ErrorHandler ¶
type ErrorHandler func(w http.ResponseWriter, r *http.Request, err error)
ErrorHandler is a handler which is called when an error occurs in the JWTMiddleware. Among some general errors, this handler also determines the response of the JWTMiddleware when a token is not found or is invalid. The err can be checked to be ErrJWTMissing or ErrJWTInvalid for specific cases. The default handler will return a status code of 400 for ErrJWTMissing, 401 for ErrJWTInvalid, and 500 for all other errors. If you implement your own ErrorHandler you MUST take into consideration the error types as not properly responding to them or having a poorly implemented handler could result in the JWTMiddleware not functioning as intended.
type JWTMiddleware ¶
type JWTMiddleware struct {
// contains filtered or unexported fields
}
func New ¶
func New(validateToken ValidateToken, opts ...Option) *JWTMiddleware
New constructs a new JWTMiddleware instance with the supplied options. It requires a ValidateToken function to be passed in, so it can properly validate tokens.
type Option ¶
type Option func(*JWTMiddleware)
Option is how options for the JWTMiddleware are set up.
func WithCredentialsOptional ¶
WithCredentialsOptional sets up if credentials are optional or not. If set to true then an empty token will be considered valid.
Default value: false.
func WithErrorHandler ¶
func WithErrorHandler(h ErrorHandler) Option
WithErrorHandler sets the handler which is called when we encounter errors in the JWTMiddleware. See the ErrorHandler type for more information.
Default value: DefaultErrorHandler.
func WithTokenExtractor ¶
func WithTokenExtractor(e TokenExtractor) Option
WithTokenExtractor sets up the function which extracts the JWT to be validated from the request.
Default value: AuthHeaderTokenExtractor.
func WithValidateOnOptions ¶
WithValidateOnOptions sets up if OPTIONS requests should have their JWT validated or not.
Default value: true.
type TokenExtractor ¶
TokenExtractor is a function that takes a request as input and returns either a token or an error. An error should only be returned if an attempt to specify a token was found, but the information was somehow incorrectly formed. In the case where a token is simply not present, this should not be treated as an error. An empty string should be returned in that case.
func CookieTokenExtractor ¶
func CookieTokenExtractor(cookieName string) TokenExtractor
CookieTokenExtractor builds a TokenExtractor that takes a request and extracts the token from the cookie using the passed in cookieName.
func MultiTokenExtractor ¶
func MultiTokenExtractor(extractors ...TokenExtractor) TokenExtractor
MultiTokenExtractor returns a TokenExtractor that runs multiple TokenExtractors and takes the one that does not return an empty token. If a TokenExtractor returns an error that error is immediately returned.
func ParameterTokenExtractor ¶
func ParameterTokenExtractor(param string) TokenExtractor
ParameterTokenExtractor returns a TokenExtractor that extracts the token from the specified query string parameter.
type ValidateToken ¶
ValidateToken takes in a string JWT and makes sure it is valid and returns the valid token. If it is not valid it will return nil and an error message describing why validation failed. Inside ValidateToken things like key and alg checking can happen. In the default implementation we can add safe defaults for those.
Source Files
Directories