easy_traefik_rate_limit_jwt

README

Easy Traefik Rate Limit JWT Plugin

A flexible JWT validation middleware for Traefik v3+ that:

• Validates JWT tokens from multiple sources (bearer, header, query)
• Checks for required fields in the JWT payload
• Provides customizable error messages for expired tokens and other errors
• Injects JWT payload fields as HTTP headers for downstream services
• Integrates seamlessly with Traefik's rate limiting
• Supports public routes that bypass JWT validation
• Allows specified routes to bypass token expiration checks
• Logs errors with timestamps in UTC format

Features

• Multiple JWT Sources: Configure multiple places to look for the JWT token (Bearer token, header, query parameter)
• Required Fields: Specify required fields in the JWT payload
• Custom Error Messages: Configure separate messages for token expiration and all other validation errors
• Header Injection: Inject JWT payload fields or header values as HTTP headers for downstream services
• Rate Limit Integration: Seamless integration with Traefik's rate limiting middleware
• Public Routes: Define routes that can bypass JWT validation entirely
• Expiration Bypass: Define routes that ignore token expiration but still verify the signature
• Enhanced Error Logging: Detailed error logging with timestamps in UTC format

Installation

To use this plugin with Traefik v3+, add the following to your Traefik static configuration:

experimental:
    plugins:
        easy-traefik-rate-limit-jwt:
            moduleName: github.com/louiscavalcante/easy-traefik-rate-limit-jwt
            version: v0.0.1

Configuration

Create a middleware instance in your dynamic configuration:

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
    name: jwt-rate-limit
spec:
    plugin:
        easy-traefik-rate-limit-jwt:
            JwtPayloadFields:
                - exp
                - _id
            Alg: HS256
            Secret:
                - your-jwt-secret-key
            InjectNewHeaders:
                X-Rate-Limit-ID:
                    From:
                        - JwtPayloadFields
                        - Sources
                    Values:
                        - _id
                        - X-Mobile-ID
            Sources:
                - type: bearer
                  key: Authorization
                - type: header
                  key: X-Mobile-ID
            ExpirationMessage: 'Token has expired, please log in again'
            ErrorMessage: 'Something bad happened, please try again later'
            RoutesToBypassTokenExpiration:
                - match: Host(`api.example.com`) && Method(`PUT`) && PathPrefix(`/bypass`)
            RoutesToBypassJwtValidation:
                - match: Host(`api.example.com`) && Method(`GET`) && PathPrefix(`/public`)
                  InjectNewHeaders:
                      X-Rate-Limit-ID:
                          From:
                              - Sources
                          Key:
                              - X-Mobile-ID

See the plugin documentation for detailed configuration options and examples.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Documentation

Index

• func New(ctx context.Context, next http.Handler, config *Config, name string) (http.Handler, error)
• type Config
  • func CreateConfig() *Config
• type HeaderValue
• type JwtPlugin
  • func (p *JwtPlugin) ServeHTTP(rw http.ResponseWriter, req *http.Request)
• type PublicHeaderValue
• type PublicRouteMatch
• type RouteMatch
• type Source

Functions

func New

func New(ctx context.Context, next http.Handler, config *Config, name string) (http.Handler, error)

New creates a new JWT middleware

Types

type Config

type Config struct {
	JwtPayloadFields              []string               `json:"JwtPayloadFields,omitempty"`
	Alg                           string                 `json:"Alg,omitempty"`
	Secret                        []string               `json:"Secret,omitempty"`
	Sources                       []Source               `json:"Sources,omitempty"`
	InjectNewHeaders              map[string]HeaderValue `json:"InjectNewHeaders,omitempty"`
	ExpirationMessage             string                 `json:"ExpirationMessage,omitempty"`
	ErrorMessage                  string                 `json:"ErrorMessage,omitempty"`
	RoutesToBypassTokenExpiration []RouteMatch           `json:"RoutesToBypassTokenExpiration,omitempty"`
	RoutesToBypassJwtValidation   []PublicRouteMatch     `json:"RoutesToBypassJwtValidation,omitempty"`
}

Config holds the plugin configuration

func CreateConfig

func CreateConfig() *Config

CreateConfig creates a new config instance

type HeaderValue

type HeaderValue struct {
	From   []string `json:"From,omitempty"`
	Values []string `json:"Values,omitempty"`
}

HeaderValue defines header values to inject

type JwtPlugin

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

JwtPlugin implements the Traefik middleware interface

func (*JwtPlugin) ServeHTTP

func (p *JwtPlugin) ServeHTTP(rw http.ResponseWriter, req *http.Request)

ServeHTTP implements the http.Handler interface

type PublicHeaderValue

type PublicHeaderValue struct {
	From []string `json:"From,omitempty"`
	Key  []string `json:"Key,omitempty"`
}

PublicHeaderValue defines header values to inject for public routes

type PublicRouteMatch

type PublicRouteMatch struct {
	Match            string                       `json:"match,omitempty"`
	InjectNewHeaders map[string]PublicHeaderValue `json:"InjectNewHeaders,omitempty"`
}

PublicRouteMatch contains a Traefik route matcher expression and headers to inject

type RouteMatch

type RouteMatch struct {
	Match string `json:"match,omitempty"`
}

RouteMatch contains a Traefik route matcher expression

type Source

type Source struct {
	Type string `json:"type,omitempty"`
	Key  string `json:"key,omitempty"`
}

Source defines a source to look for the JWT token