jwtauth

README

jwtauth - JWT authentication middleware for Go HTTP services

Port of go-chi/jwtauth middleware for Phi router

The jwtauth http middleware package provides a simple way to verify a JWT token from a http request and send the result down the request context (context.Context).

Please note, jwtauth works with any Go http router, but resides under the go-chi group for maintenance and organization - its only 3rd party dependency is the underlying jwt library "github.com/dgrijalva/jwt-go".

This package uses the new context package in Go 1.7 stdlib and net/http#Request.Context to pass values between handler chains.

In a complete JWT-authentication flow, you'll first capture the token from a http request, decode it, verify it and then validate that its correctly signed and hasn't expired - the jwtauth.Verifier middleware handler takes care of all of that. The jwtauth.Verifier will set the context values on keys jwtauth.TokenCtxKey and jwtauth.ErrorCtxKey.

Next, it's up to an authentication handler to respond or continue processing after the jwtauth.Verifier. The jwtauth.Authenticator middleware responds with a 401 Unauthorized plain-text payload for all unverified tokens and passes the good ones through. You can also copy the Authenticator and customize it to handle invalid tokens to better fit your flow (ie. with a JSON error response body).

By default, the Verifier will search for a JWT token in a http request, in the order:

1. 'jwt' URI query parameter
2. 'Authorization: BEARER T' request header
3. 'jwt' Cookie value

The first JWT string that is found as a query parameter, authorization header or cookie header is then decoded by the jwt-go library and a *jwt.Token object is set on the request context. In the case of a signature decoding error the Verifier will also set the error on the request context.

The Verifier always calls the next http handler in sequence, which can either be the generic jwtauth.Authenticator middleware or your own custom handler which checks the request context jwt token and error to prepare a custom http response.

Note: jwtauth supports custom verification sequences for finding a token from a request by using the Verify middleware instantiator directly. The default Verifier is instantiated by calling Verify(ja, TokenFromQuery, TokenFromHeader, TokenFromCookie).

Usage

See the full example.

package main

import (
	"fmt"
	jwt "github.com/dgrijalva/jwt-go"
	"github.com/fate-lovely/phi"
	"github.com/litemq/jwtauth"
	"github.com/valyala/fasthttp"
)

var tokenAuth *jwtauth.JWTAuth

func init() {
	tokenAuth = jwtauth.New("HS256", []byte("secret"), nil)

	// For debugging/example purposes, we generate and print
	// a sample jwt token with claims `user_id:123` here:
	_, tokenString, _ := tokenAuth.Encode(jwt.MapClaims{"user_id": 123})
	fmt.Printf("DEBUG: a sample jwt is %s\n\n", tokenString)
}

func main() {
	addr := ":3333"
	fmt.Printf("Starting server on %v\n", addr)
	fasthttp.ListenAndServe(addr, router())
}

func router() fasthttp.RequestHandler {
	r := phi.NewRouter()

	// Protected routes
	r.Group(func(r phi.Router) {
		// Seek, verify and validate JWT tokens
		r.Use(jwtauth.Verifier(tokenAuth))

		// Handle valid / invalid tokens. In this example, we use
		// the provided authenticator middleware, but you can write your
		// own very easily, look at the Authenticator method in jwtauth.go
		// and tweak it, its not scary.
		r.Use(jwtauth.Authenticator)

		r.Get("/admin", func(ctx *fasthttp.RequestCtx) {
			_, claims, _ := jwtauth.FromContext(ctx)
			ctx.Write([]byte(fmt.Sprintf("protected area. hi %v", claims["user_id"])))
		})
	})

	// Public routes
	r.Group(func(r phi.Router) {
		r.Get("/", func(ctx *fasthttp.RequestCtx) {
			ctx.Write([]byte("welcome anonymous"))
		})
	})

	return r.ServeFastHTTP
}

LICENSE

MIT

Documentation

Index

• Constants
• Variables
• func Authenticator(next phi.HandlerFunc) phi.HandlerFunc
• func EpochNow() int64
• func ExpireIn(tm time.Duration) int64
• func FromContext(ctx *fasthttp.RequestCtx) (*jwt.Token, jwt.MapClaims, error)
• func SetExpiry(claims jwt.MapClaims, tm time.Time)
• func SetExpiryIn(claims jwt.MapClaims, tm time.Duration)
• func SetIssuedAt(claims jwt.MapClaims, tm time.Time)
• func SetIssuedNow(claims jwt.MapClaims)
• func TokenFromCookie(r *fasthttp.RequestCtx) string
• func TokenFromHeader(r *fasthttp.RequestCtx) string
• func TokenFromQuery(r *fasthttp.RequestCtx) string
• func UnixTime(tm time.Time) int64
• func Verifier(ja *JWTAuth) phi.Middleware
• func Verify(ja *JWTAuth, findTokenFns ...func(r *fasthttp.RequestCtx) string) func(phi.Handler) phi.HandlerFunc
• func VerifyRequest(ja *JWTAuth, r *fasthttp.RequestCtx, ...) (*jwt.Token, error)
• type JWTAuth
  • func New(alg string, signKey interface{}, verifyKey interface{}) *JWTAuth
  • func NewWithParser(alg string, parser *jwt.Parser, signKey interface{}, verifyKey interface{}) *JWTAuth
  • func (ja *JWTAuth) Decode(tokenString string) (t *jwt.Token, err error)
  • func (ja *JWTAuth) Encode(claims jwt.Claims) (t *jwt.Token, tokenString string, err error)

Constants

const (
	TokenCtxKey = "Token"
	ErrorCtxKey = "Error"
)

Context keys

Variables

var (
	ErrUnauthorized = errors.New("jwtauth: token is unauthorized")
	ErrExpired      = errors.New("jwtauth: token is expired")
	ErrNBFInvalid   = errors.New("jwtauth: token nbf validation failed")
	ErrIATInvalid   = errors.New("jwtauth: token iat validation failed")
	ErrNoTokenFound = errors.New("jwtauth: no token found")
	ErrAlgoInvalid  = errors.New("jwtauth: algorithm mismatch")
)

Library errors

Functions

func Authenticator

func Authenticator(next phi.HandlerFunc) phi.HandlerFunc

Authenticator is a default authentication middleware to enforce access from the Verifier middleware request context values. The Authenticator sends a 401 Unauthorized response for any unverified tokens and passes the good ones through. It's just fine until you decide to write something similar and customize your client response.

func EpochNow

func EpochNow() int64

EpochNow is a helper function that returns the NumericDate time value used by the spec

func ExpireIn

func ExpireIn(tm time.Duration) int64

ExpireIn is a helper function to return calculated time in the future for "exp" claim

func FromContext

func FromContext(ctx *fasthttp.RequestCtx) (*jwt.Token, jwt.MapClaims, error)

func SetExpiry

func SetExpiry(claims jwt.MapClaims, tm time.Time)

Set expiry ("exp") in the claims

func SetExpiryIn

func SetExpiryIn(claims jwt.MapClaims, tm time.Duration)

Set expiry ("exp") in the claims to some duration from the present time

func SetIssuedAt

func SetIssuedAt(claims jwt.MapClaims, tm time.Time)

Set issued at ("iat") to specified time in the claims

func SetIssuedNow

func SetIssuedNow(claims jwt.MapClaims)

Set issued at ("iat") to present time in the claims

func TokenFromCookie

func TokenFromCookie(r *fasthttp.RequestCtx) string

TokenFromCookie tries to retreive the token string from a cookie named "jwt".

func TokenFromHeader

func TokenFromHeader(r *fasthttp.RequestCtx) string

TokenFromHeader tries to retreive the token string from the "Authorization" reqeust header: "Authorization: BEARER T".

func TokenFromQuery

func TokenFromQuery(r *fasthttp.RequestCtx) string

TokenFromQuery tries to retreive the token string from the "jwt" URI query parameter.

func UnixTime

func UnixTime(tm time.Time) int64

UnixTime returns the given time in UTC milliseconds

func Verifier

func Verifier(ja *JWTAuth) phi.Middleware

Verifier http middleware handler will verify a JWT string from a http request.

Verifier will search for a JWT token in a http request, in the order:

1. 'jwt' URI query parameter
2. 'Authorization: BEARER T' request header
3. Cookie 'jwt' value

The first JWT string that is found as a query parameter, authorization header or cookie header is then decoded by the `jwt-go` library and a *jwt.Token object is set on the request context. In the case of a signature decoding error the Verifier will also set the error on the request context.

The Verifier always calls the next http handler in sequence, which can either be the generic `jwtauth.Authenticator` middleware or your own custom handler which checks the request context jwt token and error to prepare a custom http response.

func Verify

func Verify(ja *JWTAuth, findTokenFns ...func(r *fasthttp.RequestCtx) string) func(phi.Handler) phi.HandlerFunc

func VerifyRequest

func VerifyRequest(ja *JWTAuth, r *fasthttp.RequestCtx, findTokenFns ...func(r *fasthttp.RequestCtx) string) (*jwt.Token, error)

Types

type JWTAuth

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

func New

func New(alg string, signKey interface{}, verifyKey interface{}) *JWTAuth

New creates a JWTAuth authenticator instance that provides middleware handlers and encoding/decoding functions for JWT signing.

func NewWithParser

func NewWithParser(alg string, parser *jwt.Parser, signKey interface{}, verifyKey interface{}) *JWTAuth

NewWithParser is the same as New, except it supports custom parser settings introduced in jwt-go/v2.4.0.

func (*JWTAuth) Decode

func (ja *JWTAuth) Decode(tokenString string) (t *jwt.Token, err error)

func (*JWTAuth) Encode

func (ja *JWTAuth) Encode(claims jwt.Claims) (t *jwt.Token, tokenString string, err error)