jwtauth

README

jwtauth - JWT authentication middleware for Go HTTP services

Documentation

Index

• Variables
• type AppClaims
  • func (c *AppClaims) ParseClaims(claims jwt.MapClaims) error
• type Config
• type JWTAuth
  • func NewJWTAuth(config Config) JWTAuth
• type RefreshClaims
  • func (c *RefreshClaims) ParseClaims(claims jwt.MapClaims) error
• type Role

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

var (
	TokenCtxKey        = &contextKey{"Token"}
	AccessClaimsCtxKey = &contextKey{"AccessClaims"}
	ErrorCtxKey        = &contextKey{"Error"}
)

Context keys

Types

type AppClaims

type AppClaims struct {
	// ID for the account
	UserID string `json:"uid,omitempty"`
	// Name of the account e.g. an email or username
	Name string `json:"name,omitempty"`
	// Roles the account has access too
	Roles []Role `json:"roles,omitempty"`
	// Type of the account, e.g. user
	Type string `json:"type,omitempty"`
	// Metadata associated with the account
	Metadata map[string]interface{} `json:"metadata,omitempty"`
	// https://tools.ietf.org/html/rfc7519#section-4.1
	jwt.StandardClaims
}

AppClaims represent the claims parsed from JWT access token.

func (*AppClaims) ParseClaims

func (c *AppClaims) ParseClaims(claims jwt.MapClaims) error

ParseClaims parses JWT claims into AppClaims.

type Config

type Config struct {
	// Algorithm to be used for for signing and validating JWT token
	JwtAuthAlgo string `json:"jwtAuthAlgo"`
	// JWT token expiry duration
	JwtExpiry time.Duration `json:"jwtExpiry"`
	// Refresh token expiry duration
	JwtRefreshExpiry time.Duration `json:"jwtRefreshExpiry"`
	// Private key used for generating JWT token
	SignKey interface{} `json:"signKey"`
	// Public key used to validate the JWT token
	VerifyKey interface{} `json:"verifyKey"`
	// Custom JWT Parser *jwt.Parser is custom parser settings introduced in jwt-go/v2.4.0.
	JwtParser *jwt.Parser `json:"jwtParser"`
}

Config holds the configuration for the jwtauth

type JWTAuth

type JWTAuth interface {
	// Functions to create JWTs
	GenTokenPair(accessClaims *AppClaims, refreshClaims *RefreshClaims) (string, string, error)
	CreateJWT(c *AppClaims) (string, error)
	CreateRefreshJWT(c *RefreshClaims) (string, error)

	// Middlewares for validating JWT tokens
	Authenticate(next http.Handler) http.Handler
	Verify() func(http.Handler) http.Handler
	RequiresRole(role Role) func(next http.Handler) http.Handler

	// Functions to extract tokens from http request
	TokenFromCookie(r *http.Request) string
	TokenFromHeader(r *http.Request) string
	TokenFromQuery(r *http.Request) string

	// Functions to encode and decode tokens
	Encode(claims jwt.Claims) (t *jwt.Token, tokenString string, err error)
	Decode(tokenString string) (t *jwt.Token, err error)

	// Functions to work with context
	TokenFromContext(ctx context.Context) (*jwt.Token, jwt.MapClaims, error)
	NewContext(ctx context.Context, t *jwt.Token, err error) context.Context
	AppClaimsFromCtx(ctx context.Context) AppClaims

	// Utility functions for setting token expiry
	ExpireIn(tm time.Duration) int64
	SetIssuedAt(claims jwt.MapClaims, tm time.Time)
	SetIssuedNow(claims jwt.MapClaims)
	SetExpiry(claims jwt.MapClaims, tm time.Time)
	SetExpiryIn(claims jwt.MapClaims, tm time.Duration)
}

JWTAuth implements the JWTAuth methods

func NewJWTAuth

func NewJWTAuth(config Config) JWTAuth

NewJWTAuth creates a JWTAuth authenticator instance that provides middleware handlers and encoding/decoding functions for JWT signing. *jwt.Parser is custom parser settings introduced in jwt-go/v2.4.0.

type RefreshClaims

type RefreshClaims struct {
	// ID for the account
	UserID string `json:"uid,omitempty"`
	// Roles the account has access too
	Roles []Role `json:"roles,omitempty"`
	// Metadata associated with the account
	Metadata map[string]interface{} `json:"metadata,omitempty"`
	// https://tools.ietf.org/html/rfc7519#section-4.1
	jwt.StandardClaims
}

RefreshClaims represents the claims parsed from JWT refresh token.

func (*RefreshClaims) ParseClaims

func (c *RefreshClaims) ParseClaims(claims jwt.MapClaims) error

ParseClaims parses the JWT claims into RefreshClaims.

type Role

type Role string

Role defines a perticular user role