JWT - 💧 Mizu

Overview

The jwt middleware provides JSON Web Token (JWT) authentication. It validates tokens from the Authorization header and makes claims available to handlers. Use it when you need:

Stateless API authentication
Token-based user sessions
Microservices authentication

Installation

import "github.com/go-mizu/mizu/middlewares/jwt"

Quick Start

app := mizu.New()

secret := []byte("your-secret-key-at-least-32-bytes")

// Protect routes with JWT
app.Use(jwt.New(secret))

app.Get("/protected", func(c *mizu.Ctx) error {
    // Access claims
    claims := jwt.GetClaims(c)
    userID := jwt.Subject(c)
    return c.JSON(200, map[string]string{"user": userID})
})

Configuration

Options

Option	Type	Default	Description
`Secret`	`[]byte`	Required	HMAC secret key
`TokenLookup`	`string`	`"header:Authorization"`	Where to find token
`AuthScheme`	`string`	`"Bearer"`	Authorization scheme
`Issuer`	`string`	`""`	Expected token issuer
`ErrorHandler`	`func(*mizu.Ctx, error) error`	-	Custom error handler
`SuccessHandler`	`func(*mizu.Ctx) error`	-	Called after validation

TokenLookup Formats

header:Authorization - From Authorization header
query:token - From query parameter
cookie:jwt - From cookie

Examples

Basic Usage

secret := []byte("your-secret-key-at-least-32-bytes")
app.Use(jwt.New(secret))

With Issuer Validation

app.Use(jwt.WithOptions(jwt.Options{
    Secret: secret,
    Issuer: "my-app",
}))

Token from Query Parameter

app.Use(jwt.WithOptions(jwt.Options{
    Secret:      secret,
    TokenLookup: "query:token",
    AuthScheme:  "", // No scheme for query params
}))

app.Use(jwt.WithOptions(jwt.Options{
    Secret:      secret,
    TokenLookup: "cookie:auth_token",
}))

Custom Error Handler

app.Use(jwt.WithOptions(jwt.Options{
    Secret: secret,
    ErrorHandler: func(c *mizu.Ctx, err error) error {
        return c.JSON(401, map[string]string{
            "error": "Invalid or expired token",
        })
    },
}))

Accessing Claims

app.Get("/profile", func(c *mizu.Ctx) error {
    // Get all claims
    claims := jwt.GetClaims(c)

    // Get specific claim
    email := claims["email"].(string)

    // Get subject (user ID)
    userID := jwt.Subject(c)

    return c.JSON(200, map[string]any{
        "user_id": userID,
        "email":   email,
    })
})

Protected Group

// Public routes
app.Get("/", publicHandler)

// Protected API routes
api := app.Group("/api")
api.Use(jwt.New(secret))

api.Get("/users", listUsers)
api.Post("/users", createUser)

API Reference

Functions

// New creates JWT middleware with secret
func New(secret []byte) mizu.Middleware

// WithOptions creates JWT middleware with full configuration
func WithOptions(opts Options) mizu.Middleware

// GetClaims returns claims from context
func GetClaims(c *mizu.Ctx) map[string]any

// Subject returns the "sub" claim
func Subject(c *mizu.Ctx) string

Standard Claims

Claim	Description
`sub`	Subject (user ID)
`iss`	Issuer
`exp`	Expiration time
`iat`	Issued at
`aud`	Audience

Technical Details

Token Validation Process

The JWT middleware implements a complete token validation workflow:

Token Extraction: The middleware supports three token sources:
- Header: Extracts from Authorization header with configurable scheme (default: “Bearer”)
- Query: Extracts from URL query parameters
- Cookie: Extracts from HTTP cookies
Token Structure Validation: Validates the token has exactly three parts (header.payload.signature) separated by dots.
Signature Verification: Uses HMAC-SHA256 to verify the token signature:
- Decodes the signature from base64url encoding
- Computes expected signature using the provided secret
- Performs constant-time comparison to prevent timing attacks
Payload Decoding: Decodes the base64url-encoded payload and unmarshals JSON claims.
Claims Validation: Validates standard JWT claims:
- exp (expiration): Rejects tokens past their expiration time
- nbf (not before): Rejects tokens used before their valid time
- iss (issuer): Validates against configured issuer if specified
- aud (audience): Validates against configured audience list if specified (supports both string and array formats)

Context Storage

Claims are stored in the request context using a private context key. This prevents key collisions and ensures type safety. The GetClaims() and Subject() helper functions provide convenient access to the claims.

Error Handling

The middleware defines specific error types for different failure scenarios:

ErrTokenMissing: Returns 401 Unauthorized
ErrTokenMalformed, ErrTokenInvalid, ErrTokenExpired, ErrTokenNotYetValid, ErrInvalidScheme, ErrInvalidIssuer, ErrInvalidAudience: Return 403 Forbidden

Custom error handlers can be configured via the ErrorHandler option for application-specific error responses.

Security Considerations

Use strong secrets - At least 32 bytes for HS256
Always validate expiration - The middleware checks exp automatically
Use HTTPS - Never transmit tokens over HTTP
Short expiration times - Use refresh tokens for long sessions
Validate issuer - Prevent tokens from other applications

Best Practices

Store secrets in environment variables
Use short-lived access tokens with refresh tokens
Include only necessary data in claims
Validate additional claims in handlers when needed

Testing

The JWT middleware includes comprehensive test coverage for all scenarios:

Test Case	Description	Expected Behavior
Valid Token	Token with valid signature and expiration	Returns 200 OK, request proceeds
Missing Token	No Authorization header provided	Returns 401 Unauthorized
Invalid Token	Malformed token structure	Returns 403 Forbidden
Wrong Secret	Token signed with different secret	Returns 403 Forbidden, signature validation fails
Expired Token	Token with past expiration time	Returns 403 Forbidden
Valid Issuer	Token with matching issuer claim	Returns 200 OK
Invalid Issuer	Token with non-matching issuer	Returns 403 Forbidden
Missing Issuer	Token without issuer when required	Returns 403 Forbidden
GetClaims	Extract all claims from context	Returns map with all token claims
Subject	Extract subject claim	Returns “sub” claim value
Query Lookup	Token in query parameter	Returns 200 OK, extracts from query string
Cookie Lookup	Token in HTTP cookie	Returns 200 OK, extracts from cookie
Cookie Missing	No cookie when expected	Returns 401 Unauthorized
Not Before (Invalid)	Token with future “nbf” claim	Returns 403 Forbidden
Not Before (Valid)	Token with past “nbf” claim	Returns 200 OK
Valid Audience (String)	Token with matching audience string	Returns 200 OK
Valid Audience (Array)	Token with matching audience in array	Returns 200 OK
Invalid Audience	Token with non-matching audience	Returns 403 Forbidden
Missing Audience	Token without audience when required	Returns 403 Forbidden
GetClaims (No Claims)	Call GetClaims without JWT middleware	Returns nil
Subject (No Claims)	Call Subject without JWT middleware	Returns empty string
Subject (No Sub Claim)	Token without “sub” claim	Returns empty string
Invalid Scheme	Wrong authorization scheme (e.g., “Basic”)	Returns 403 Forbidden
Custom Error Handler	Custom error handling function	Calls custom handler with custom status
Custom Auth Scheme	Non-default scheme (e.g., “Token”)	Returns 200 OK with custom scheme
Malformed Parts	Token with wrong number of parts	Returns 403 Forbidden
Invalid Base64 Signature	Signature not properly base64 encoded	Returns 403 Forbidden
Invalid Base64 Payload	Payload not properly base64 encoded	Returns 403 Forbidden
Invalid JSON Payload	Payload is not valid JSON	Returns 403 Forbidden
Query Missing	No query parameter when expected	Returns 401 Unauthorized
Panic (No Secret)	Options without secret	Panics with error message
Panic (Invalid Lookup)	Invalid TokenLookup format	Panics with error message

bearerauth - Simple bearer token auth
keyauth - API key authentication
session - Session-based authentication

​Overview

​Installation

​Quick Start

​Configuration

​Options

​TokenLookup Formats

​Examples

​Basic Usage

​With Issuer Validation

​Token from Query Parameter

​Token from Cookie

​Custom Error Handler

​Accessing Claims

​Protected Group

​API Reference

​Functions

​Standard Claims

​Technical Details

​Token Validation Process

​Context Storage

​Error Handling

​Security Considerations

​Best Practices

​Testing

​Related Middlewares