jwtmiddleware

README

GO JWT Middleware

NOTE: We released this version using a fork of jwt-go in order to address a security vulnerability. Due to jwt-go not being actively maintained we will be looking to switch to a more actively maintained package in the near future.

A middleware that will check that a JWT is sent on the Authorization header and will then set the content of the JWT into the user variable of the request.

This module lets you authenticate HTTP requests using JWT tokens in your Go Programming Language applications. JWTs are typically used to protect API endpoints, and are often issued using OpenID Connect.

Key Features

• Ability to check the Authorization header for a JWT
• Decode the JWT and set the content of it to the request context

Installing

go get github.com/auth0/go-jwt-middleware

Using it

You can use jwtmiddleware with default net/http as follows.

// main.go
package main

import (
	"fmt"
	"net/http"

	"github.com/auth0/go-jwt-middleware"
	"github.com/form3tech-oss/jwt-go"
)

var myHandler = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	user := r.Context().Value("user")
	fmt.Fprintf(w, "This is an authenticated request")
	fmt.Fprintf(w, "Claim content:\n")
	for k, v := range user.(*jwt.Token).Claims.(jwt.MapClaims) {
		fmt.Fprintf(w, "%s :\t%#v\n", k, v)
	}
})

func main() {
	jwtMiddleware := jwtmiddleware.New(jwtmiddleware.Options{
		ValidationKeyGetter: func(token *jwt.Token) (interface{}, error) {
			return []byte("My Secret"), nil
		},
		// When set, the middleware verifies that tokens are signed with the specific signing algorithm
		// If the signing method is not constant the ValidationKeyGetter callback can be used to implement additional checks
		// Important to avoid security issues described here: https://auth0.com/blog/critical-vulnerabilities-in-json-web-token-libraries/
		SigningMethod: jwt.SigningMethodHS256,
	})

	app := jwtMiddleware.Handler(myHandler)
	http.ListenAndServe("0.0.0.0:3000", app)
}

You can also use it with Negroni as follows:

// main.go
package main

import (
	"encoding/json"
	"net/http"

	"github.com/auth0/go-jwt-middleware"
	"github.com/form3tech-oss/jwt-go"
	"github.com/gorilla/mux"
	"github.com/urfave/negroni"
)

func main() {
	StartServer()
}

func StartServer() {
	r := mux.NewRouter()

	jwtMiddleware := jwtmiddleware.New(jwtmiddleware.Options{
		ValidationKeyGetter: func(token *jwt.Token) (interface{}, error) {
			return []byte("My Secret"), nil
		},
		SigningMethod: jwt.SigningMethodHS256,
	})

	r.HandleFunc("/ping", PingHandler)
	r.Handle("/secured/ping", negroni.New(
		negroni.HandlerFunc(jwtMiddleware.HandlerWithNext),
		negroni.Wrap(http.HandlerFunc(SecuredPingHandler)),
	))
	http.Handle("/", r)
	http.ListenAndServe(":3001", nil)
}

type Response struct {
	Text string `json:"text"`
}

func respondJSON(text string, w http.ResponseWriter) {
	response := Response{text}

	jsonResponse, err := json.Marshal(response)
	if err != nil {
		http.Error(w, err.Error(), http.StatusInternalServerError)
		return
	}

	w.Header().Set("Content-Type", "application/json")
	w.Write(jsonResponse)
}

func PingHandler(w http.ResponseWriter, r *http.Request) {
	respondJSON("All good. You don't need to be authenticated to call this", w)
}

func SecuredPingHandler(w http.ResponseWriter, r *http.Request) {
	respondJSON("All good. You only get this message if you're authenticated", w)
}

Options

// Options is a struct for specifying configuration options for the middleware.
type Options struct {
	// The function that will return the Key to validate the JWT.
	// It can be either a shared secret or a public key.
	// Default value: nil
	ValidationKeyGetter jwt.Keyfunc
	// The name of the property in the request where the user information
	// from the JWT will be stored.
	// Default value: "user"
	UserProperty string
	// The function that will be called when there's an error validating the token
	// Default value:
	ErrorHandler errorHandler
	// A boolean indicating if the credentials are required or not
	// Default value: false
	CredentialsOptional bool
	// A function that extracts the token from the request
	// Default: FromAuthHeader (i.e., from Authorization header as bearer token)
	Extractor TokenExtractor
	// Debug flag turns on debugging output
	// Default: false
	Debug bool
	// When set, all requests with the OPTIONS method will use authentication
	// Default: false
	EnableAuthOnOptions bool
	// When set, the middelware verifies that tokens are signed with the specific signing algorithm
	// If the signing method is not constant the ValidationKeyGetter callback can be used to implement additional checks
	// Important to avoid security issues described here: https://auth0.com/blog/critical-vulnerabilities-in-json-web-token-libraries/
	// Default: nil
	SigningMethod jwt.SigningMethod
}

Token Extraction

The default value for the Extractor option is the FromAuthHeader function which assumes that the JWT will be provided as a bearer token in an Authorization header, i.e.,

Authorization: bearer {token}

To extract the token from a query string parameter, you can use the FromParameter function, e.g.,

jwtmiddleware.New(jwtmiddleware.Options{
  Extractor: jwtmiddleware.FromParameter("auth_code"),
})

In this case, the FromParameter function will look for a JWT in the auth_code query parameter.

Or, if you want to allow both, you can use the FromFirst function to try and extract the token first in one way and then in one or more other ways, e.g.,

jwtmiddleware.New(jwtmiddleware.Options{
  Extractor: jwtmiddleware.FromFirst(jwtmiddleware.FromAuthHeader,
                                     jwtmiddleware.FromParameter("auth_code")),
})

Examples

You can check out working examples in the examples folder

What is Auth0?

Auth0 helps you to:

• Add authentication with multiple authentication sources, either social like Google, Facebook, Microsoft Account, LinkedIn, GitHub, Twitter, Box, Salesforce, amont others, or enterprise identity systems like Windows Azure AD, Google Apps, Active Directory, ADFS or any SAML Identity Provider.
• Add authentication through more traditional username/password databases.
• Add support for linking different user accounts with the same user.
• Support for generating signed Json Web Tokens to call your APIs and flow the user identity securely.
• Analytics of how, when and where users are logging in.
• Pull data from other sources and add it to the user profile, through JavaScript rules.

Create a free Auth0 Account

1. Go to Auth0 and click Sign Up.
2. Use Google, GitHub or Microsoft Account to login.

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 details the procedure for disclosing security issues.

Author

Auth0

License

This project is licensed under the MIT license. See the LICENSE file for more info.

Documentation

Index

• func FromAuthHeader(r *http.Request) (string, error)
• func OnError(w http.ResponseWriter, r *http.Request, err string)
• type Claims
• type JWTMiddleware
  • func New(options ...Options) *JWTMiddleware
  • func (m *JWTMiddleware) CheckJWT(w http.ResponseWriter, r *http.Request) error
  • func (m *JWTMiddleware) Handler(h http.Handler) http.Handler
  • func (m *JWTMiddleware) HandlerWithNext(w http.ResponseWriter, r *http.Request, next http.HandlerFunc)
• type Options
• type StandardClaims
  • func (c StandardClaims) Valid() error
  • func (c *StandardClaims) VerifyAudience(cmp string, req bool) bool
  • func (c *StandardClaims) VerifyExpiresAt(cmp int64, req bool) bool
  • func (c *StandardClaims) VerifyIssuedAt(cmp int64, req bool) bool
  • func (c *StandardClaims) VerifyIssuer(cmp string, req bool) bool
  • func (c *StandardClaims) VerifyNotBefore(cmp int64, req bool) bool
• type TokenExtractor
  • func FromFirst(extractors ...TokenExtractor) TokenExtractor
  • func FromParameter(param string) TokenExtractor

Functions

func FromAuthHeader

func FromAuthHeader(r *http.Request) (string, error)

FromAuthHeader is a "TokenExtractor" that takes a give request and extracts the JWT token from the Authorization header.

func OnError

func OnError(w http.ResponseWriter, r *http.Request, err string)

Types

type Claims

type Claims interface {
	Valid() error
}

For a type to be a Claims object, it must just have a Valid method that determines if the token is invalid for any supported reason

type JWTMiddleware

type JWTMiddleware struct {
	Options Options
}

func New

func New(options ...Options) *JWTMiddleware

New constructs a new Secure instance with supplied options.

func (*JWTMiddleware) CheckJWT

func (m *JWTMiddleware) CheckJWT(w http.ResponseWriter, r *http.Request) error

func (*JWTMiddleware) Handler

func (m *JWTMiddleware) Handler(h http.Handler) http.Handler

func (*JWTMiddleware) HandlerWithNext

func (m *JWTMiddleware) HandlerWithNext(w http.ResponseWriter, r *http.Request, next http.HandlerFunc)

HandlerWithNext is a special implementation for Negroni, but could be used elsewhere.

type Options

type Options struct {
	// The function that will return the Key to validate the JWT.
	// It can be either a shared secret or a public key.
	// Default value: nil
	ValidationKeyGetter jwt.Keyfunc
	// The name of the property in the request where the user information
	// from the JWT will be stored.
	// Default value: "user"
	UserProperty string
	// The function that will be called when there's an error validating the token
	// Default value:
	ErrorHandler errorHandler
	// A boolean indicating if the credentials are required or not
	// Default value: false
	CredentialsOptional bool
	// A function that extracts the token from the request
	// Default: FromAuthHeader (i.e., from Authorization header as bearer token)
	Extractor TokenExtractor
	// Debug flag turns on debugging output
	// Default: false
	Debug bool
	// When set, all requests with the OPTIONS method will use authentication
	// Default: false
	EnableAuthOnOptions bool
	// When set, the middelware verifies that tokens are signed with the specific signing algorithm
	// If the signing method is not constant the ValidationKeyGetter callback can be used to implement additional checks
	// Important to avoid security issues described here: https://auth0.com/blog/critical-vulnerabilities-in-json-web-token-libraries/
	// Default: nil
	SigningMethod jwt.SigningMethod
}

Options is a struct for specifying configuration options for the middleware.

type StandardClaims

type StandardClaims struct {
	Audience  []string `json:"aud,omitempty"`
	ExpiresAt int64    `json:"exp,omitempty"`
	Id        string   `json:"jti,omitempty"`
	IssuedAt  int64    `json:"iat,omitempty"`
	Issuer    string   `json:"iss,omitempty"`
	NotBefore int64    `json:"nbf,omitempty"`
	Subject   string   `json:"sub,omitempty"`
}

Structured version of Claims Section, as referenced at https://tools.ietf.org/html/rfc7519#section-4.1 See examples for how to use this with your own claim types

func (StandardClaims) Valid

func (c StandardClaims) Valid() error

Validates time based claims "exp, iat, nbf". There is no accounting for clock skew. As well, if any of the above claims are not in the token, it will still be considered a valid claim.

func (*StandardClaims) VerifyAudience

func (c *StandardClaims) VerifyAudience(cmp string, req bool) bool

Compares the aud claim against cmp. If required is false, this method will return true if the value matches or is unset

func (*StandardClaims) VerifyExpiresAt

func (c *StandardClaims) VerifyExpiresAt(cmp int64, req bool) bool

Compares the exp claim against cmp. If required is false, this method will return true if the value matches or is unset

func (*StandardClaims) VerifyIssuedAt

func (c *StandardClaims) VerifyIssuedAt(cmp int64, req bool) bool

Compares the iat claim against cmp. If required is false, this method will return true if the value matches or is unset

func (*StandardClaims) VerifyIssuer

func (c *StandardClaims) VerifyIssuer(cmp string, req bool) bool

Compares the iss claim against cmp. If required is false, this method will return true if the value matches or is unset

func (*StandardClaims) VerifyNotBefore

func (c *StandardClaims) VerifyNotBefore(cmp int64, req bool) bool

Compares the nbf claim against cmp. If required is false, this method will return true if the value matches or is unset

type TokenExtractor

type TokenExtractor func(r *http.Request) (string, error)

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 FromFirst

func FromFirst(extractors ...TokenExtractor) TokenExtractor

FromFirst returns a function that runs multiple token extractors and takes the first token it finds

func FromParameter

func FromParameter(param string) TokenExtractor

FromParameter returns a function that extracts the token from the specified query string parameter