jwt

README

JWT Middleware for Fiber Framework

preamble: this is port of appleyboy's JWT middleware adapted for Fiber framework

This is a middleware for Fiber framework, which built on top of fasthttp

It uses golang-jwt/jwt to provide a jwt authentication middleware. It provides additional handler functions to provide the doauth api that will generate the token and an additional refresh_token handler that can be used to refresh tokens.

Usage

Download and install using go module:

export GO111MODULE=on
go get github.com/LdDl/fiber-jwt

Import it in your code:

import (
    jwt "github.com/LdDl/fiber-jwt/v2"
)

Example

Please see the example file

go run example/main.go

Demo server will start on port 8080.

Login API

Correct username/password and user access

curl -X POST 'http://localhost:8080/api/doauth' -d '{"username": "user", "password": "pass"}'
curl -X GET 'http://localhost:8080/api/v0.0.1/secret_page?token=PUT_RECIEVED_TOKEN'

Correct username/password but user has no access (banned)

curl -X POST 'http://localhost:8080/api/doauth' -d '{"username": "user2", "password": "pass"}'

Wrong user or password

curl -X POST 'http://localhost:8080/api/doauth' -d '{"username": "user", "password": "pass333"}'

Refresh token API

curl -X GET 'http://localhost:8080/api/v0.0.1/refresh_token?token=PUT_RECIEVED_TOKEN'

Login Flow

1. Authenticator: handles the login logic. On success LoginResponse is called, on failure Unauthorized is called.
2. LoginResponse: optional, allows setting a custom response such as a redirect.

JWT Flow

1. PayloadFunc: maps the claims in the JWT.
2. IdentityHandler: extracts identity from claims.
3. Authorizator: receives identity and handles authorization logic.
4. Unauthorized: handles unauthorized logic.

Documentation

Index

• Variables
• func GetToken(c *fiber.Ctx) string
• type FiberJWTMiddleware
  • func New(m *FiberJWTMiddleware) (*FiberJWTMiddleware, error)
  • func (mw *FiberJWTMiddleware) CheckIfTokenExpire(c *fiber.Ctx) (jwt.MapClaims, error)
  • func (mw *FiberJWTMiddleware) GetClaimsFromJWT(c *fiber.Ctx) (MapClaims, error)
  • func (mw *FiberJWTMiddleware) LoginHandler(c *fiber.Ctx) error
  • func (mw *FiberJWTMiddleware) LogoutHandler(c *fiber.Ctx) error
  • func (mw *FiberJWTMiddleware) MiddlewareFunc() func(c *fiber.Ctx) error
  • func (mw *FiberJWTMiddleware) MiddlewareInit() error
  • func (mw *FiberJWTMiddleware) ParseToken(c *fiber.Ctx) (*jwt.Token, error)
  • func (mw *FiberJWTMiddleware) ParseTokenString(token string) (*jwt.Token, error)
  • func (mw *FiberJWTMiddleware) RefreshHandler(c *fiber.Ctx) error
  • func (mw *FiberJWTMiddleware) RefreshToken(c *fiber.Ctx) (string, time.Time, error)
  • func (mw *FiberJWTMiddleware) TokenGenerator(data interface{}) (string, time.Time, error)
• type MapClaims
  • func ExtractClaims(c *fiber.Ctx) MapClaims
  • func ExtractClaimsFromToken(token *jwt.Token) MapClaims

Variables

var (
	// ErrMissingSecretKey indicates Secret key is required
	ErrMissingSecretKey = errors.New("secret key is required")

	// ErrForbidden when HTTP status 403 is given
	ErrForbidden = errors.New("you don't have permission to access this resource")

	// ErrMissingAuthenticatorFunc indicates Authenticator is required
	ErrMissingAuthenticatorFunc = errors.New("fiberJWTMiddleware.Authenticator func is undefined")

	// ErrMissingLoginValues indicates a user tried to authenticate without username or password
	ErrMissingLoginValues = errors.New("missing Username or Password")

	// ErrFailedAuthentication indicates authentication failed, could be faulty username or password
	ErrFailedAuthentication = errors.New("incorrect Username or Password")

	// ErrFailedTokenCreation indicates JWT Token failed to create, reason unknown
	ErrFailedTokenCreation = errors.New("failed to create JWT Token")

	// ErrExpiredToken indicates JWT token has expired. Can't refresh.
	ErrExpiredToken = errors.New("token is expired")

	// ErrEmptyAuthHeader can be thrown if authing with a HTTP header, the Auth header needs to be set
	ErrEmptyAuthHeader = errors.New("auth header is empty")

	// ErrMissingExpField missing exp field in token
	ErrMissingExpField = errors.New("missing exp field")

	// ErrWrongFormatOfExp field must be float64 format
	ErrWrongFormatOfExp = errors.New("exp must be float64 format")

	// ErrInvalidAuthHeader indicates auth header is invalid, could for example have the wrong Realm name
	ErrInvalidAuthHeader = errors.New("auth header is invalid")

	// ErrEmptyQueryToken can be thrown if authing with URL Query, the query token variable is empty
	ErrEmptyQueryToken = errors.New("query token is empty")

	// ErrEmptyCookieToken can be thrown if authing with a cookie, the token cookie is empty
	ErrEmptyCookieToken = errors.New("cookie token is empty")

	// ErrEmptyParamToken can be thrown if authing with parameter in path, the parameter in path is empty
	ErrEmptyParamToken = errors.New("parameter token is empty")

	// ErrInvalidSigningAlgorithm indicates signing algorithm is invalid, needs to be HS256, HS384, HS512, RS256, RS384 or RS512
	ErrInvalidSigningAlgorithm = errors.New("invalid signing algorithm")

	// ErrNoPrivKeyFile indicates that the given private key is unreadable
	ErrNoPrivKeyFile = errors.New("private key file unreadable")

	// ErrNoPubKeyFile indicates that the given public key is unreadable
	ErrNoPubKeyFile = errors.New("public key file unreadable")

	// ErrInvalidPrivKey indicates that the given private key is invalid
	ErrInvalidPrivKey = errors.New("private key invalid")

	// ErrInvalidPubKey indicates the the given public key is invalid
	ErrInvalidPubKey = errors.New("public key invalid")

	// IdentityKey default identity key
	IdentityKey = "identity"
)

Functions

func GetToken

func GetToken(c *fiber.Ctx) string

GetToken help to get the JWT token string

Types

type FiberJWTMiddleware

type FiberJWTMiddleware struct {
	// Realm name to display to the user. Required.
	Realm string

	// signing algorithm - possible values are HS256, HS384, HS512, RS256, RS384 or RS512
	// Optional, default is HS256.
	SigningAlgorithm string

	// Secret key used for signing. Required.
	Key []byte

	// Duration that a jwt token is valid. Optional, defaults to one hour.
	Timeout time.Duration

	// This field allows clients to refresh their token until MaxRefresh has passed.
	// Note that clients can refresh their token in the last moment of MaxRefresh.
	// This means that the maximum validity timespan for a token is TokenTime + MaxRefresh.
	// Optional, defaults to 0 meaning not refreshable.
	MaxRefresh time.Duration

	// Callback function that should perform the authentication of the user based on login info.
	// Must return user data as user identifier, it will be stored in Claim Array. Required.
	// Check error (e) to determine the appropriate error message.
	Authenticator func(c *fiber.Ctx) (interface{}, error)

	// Callback function that should perform the authorization of the authenticated user. Called
	// only after an authentication success. Must return true on success, false on failure.
	// Optional, default to success.
	Authorizator func(data interface{}, c *fiber.Ctx) bool

	// Callback function that will be called during login.
	// Using this function it is possible to add additional payload data to the webtoken.
	// The data is then made available during requests via c.Get("JWT_PAYLOAD").
	// Note that the payload is not encrypted.
	// The attributes mentioned on jwt.io can't be used as keys for the map.
	// Optional, by default no additional data will be set.
	PayloadFunc func(data interface{}) MapClaims

	// User can define own Unauthorized func.
	Unauthorized func(*fiber.Ctx, int, string) error

	// User can define own LoginResponse func.
	LoginResponse func(*fiber.Ctx, int, string, time.Time, map[string]interface{}) error

	// User can define own LogoutResponse func.
	LogoutResponse func(*fiber.Ctx, int) error

	// User can define own RefreshResponse func.
	RefreshResponse func(*fiber.Ctx, int, string, time.Time) error

	// Set the identity handler function
	IdentityHandler func(*fiber.Ctx) interface{}

	// Set the identity key
	IdentityKey string

	// 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>"
	// - "cookie:<name>"
	TokenLookup string

	// TokenHeadName is a string in the header. Default value is "Bearer"
	TokenHeadName string

	// TimeFunc provides the current time. You can override it to use another time value. This is useful for testing or if your server uses a different time zone than your tokens.
	TimeFunc func() time.Time

	// HTTP Status messages for when something in the JWT middleware fails.
	// Check error (e) to determine the appropriate error message.
	HTTPStatusMessageFunc func(e error, c *fiber.Ctx) string

	// Private key file for asymmetric algorithms
	PrivKeyFile string

	// Private Key bytes for asymmetric algorithms
	//
	// Note: PrivKeyFile takes precedence over PrivKeyBytes if both are set
	PrivKeyBytes []byte

	// Public key file for asymmetric algorithms
	PubKeyFile string

	// Public key bytes for asymmetric algorithms.
	//
	// Note: PubKeyFile takes precedence over PubKeyBytes if both are set
	PubKeyBytes []byte

	// Optionally return the token as a cookie
	SendCookie bool

	// Duration that a cookie is valid. Optional, by default equals to Timeout value.
	CookieMaxAge time.Duration

	// Allow insecure cookies for development over http
	SecureCookie bool

	// Allow cookies to be accessed client side for development
	CookieHTTPOnly bool

	// Allow cookie domain change for development
	CookieDomain string

	// SendAuthorization allow return authorization header for every request
	SendAuthorization bool

	// Disable abort() of context.
	DisabledAbort bool

	// CookieName allow cookie name change for development
	CookieName string
	// contains filtered or unexported fields
}

FiberJWTMiddleware provides a Json-Web-Token authentication implementation. On failure, a 401 HTTP response is returned. On success, the wrapped middleware is called, and the userID is made available as c.Get("userID").(string). Users can get a token by posting a json request to LoginHandler. The token then needs to be passed in the Authentication header. Example: Authorization:Bearer XXX_TOKEN_XXX

func New

func New(m *FiberJWTMiddleware) (*FiberJWTMiddleware, error)

New for check error with FiberJWTMiddleware

func (*FiberJWTMiddleware) CheckIfTokenExpire

func (mw *FiberJWTMiddleware) CheckIfTokenExpire(c *fiber.Ctx) (jwt.MapClaims, error)

CheckIfTokenExpire check if token expire

func (*FiberJWTMiddleware) GetClaimsFromJWT

func (mw *FiberJWTMiddleware) GetClaimsFromJWT(c *fiber.Ctx) (MapClaims, error)

GetClaimsFromJWT get claims from JWT token

func (*FiberJWTMiddleware) LoginHandler

func (mw *FiberJWTMiddleware) LoginHandler(c *fiber.Ctx) error

LoginHandler can be used by clients to get a jwt token. Payload needs to be json in the form of {"username": "USERNAME", "password": "PASSWORD"}. Reply will be of the form {"token": "TOKEN"}.

func (*FiberJWTMiddleware) LogoutHandler

func (mw *FiberJWTMiddleware) LogoutHandler(c *fiber.Ctx) error

LogoutHandler can be used by clients to remove the jwt cookie (if set)

func (*FiberJWTMiddleware) MiddlewareFunc

func (mw *FiberJWTMiddleware) MiddlewareFunc() func(c *fiber.Ctx) error

MiddlewareFunc makes FiberJWTMiddleware implement the Middleware interface.

func (*FiberJWTMiddleware) MiddlewareInit

func (mw *FiberJWTMiddleware) MiddlewareInit() error

MiddlewareInit initialize jwt configs.

func (*FiberJWTMiddleware) ParseToken

func (mw *FiberJWTMiddleware) ParseToken(c *fiber.Ctx) (*jwt.Token, error)

ParseToken parse jwt token from gin context

func (*FiberJWTMiddleware) ParseTokenString

func (mw *FiberJWTMiddleware) ParseTokenString(token string) (*jwt.Token, error)

ParseTokenString parse jwt token string

func (*FiberJWTMiddleware) RefreshHandler

func (mw *FiberJWTMiddleware) RefreshHandler(c *fiber.Ctx) error

RefreshHandler can be used to refresh a token. The token still needs to be valid on refresh. Shall be put under an endpoint that is using the FiberJWTMiddleware. Reply will be of the form {"token": "TOKEN"}.

func (*FiberJWTMiddleware) RefreshToken

func (mw *FiberJWTMiddleware) RefreshToken(c *fiber.Ctx) (string, time.Time, error)

RefreshToken refresh token and check if token is expired

func (*FiberJWTMiddleware) TokenGenerator

func (mw *FiberJWTMiddleware) TokenGenerator(data interface{}) (string, time.Time, error)

TokenGenerator method that clients can use to get a jwt token.

type MapClaims

type MapClaims map[string]interface{}

MapClaims type that uses the map[string]interface{} for JSON decoding This is the default claims type if you don't supply one

func ExtractClaims

func ExtractClaims(c *fiber.Ctx) MapClaims

ExtractClaims help to extract the JWT claims

func ExtractClaimsFromToken

func ExtractClaimsFromToken(token *jwt.Token) MapClaims

ExtractClaimsFromToken help to extract the JWT claims from token