JWT Middleware

The JWT Middleware validates JSON Web Tokens (JWT) in incoming requests to ensure only authenticated requests reach your upstream services. It provides flexible authentication methods and advanced claim validation capabilities.

Quick Start

middlewares:
  - name: jwt-auth
    type: jwtAuth
    paths: ["/.*"]
    rule:
      secret: "your-secret-key-here"
      algorithms: ["HS256"]

Authentication Methods

The middleware supports four authentication methods. You must configure exactly one:

Shared Secret (HMAC)

Use a shared secret key for HMAC algorithms like HS256, HS384, or HS512.

rule:
  secret: "MgsEUFgn9xiMym9Lo9rcRUa3wJbQBo..."
  algorithms: ["HS256"]

Public Key (RSA/ECDSA)

Use a PEM-formatted public key for RSA or ECDSA algorithms.

rule:
  publicKey: |
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
    -----END PUBLIC KEY-----
  algorithms: ["RS256"]

You can also provide:

File path: /path/to/public-key.pem
Base64 encoded key: LS0tLS1CRUdJTi...

JWKS URL

Dynamically fetch public keys from a JSON Web Key Set endpoint.

rule:
  jwksUrl: "https://your-auth-provider.com/.well-known/jwks.json"
  algorithms: ["RS256"]

JWKS File

Use a local JWKS file for key validation.

rule:
  jwksFile: "/path/to/jwks.json"
  # Or embed the content directly:
  # jwksFile: '{"keys":[{"kty":"RSA",...}]}'

Configuration Reference

Core Settings

Option	Type	Required	Description
`secret`	string	*	Shared secret for HMAC algorithms
`publicKey`	string	*	PEM public key (content, file path, or base64)
`jwksUrl`	string	*	URL to fetch JWKS dynamically
`jwksFile`	string	*	JWKS file path or content
`algorithms`	[]string	No	Accepted JWT signing algorithms, e.g. `["RS256", "ES256"]`
`algo`	string	No	Deprecated — use `algorithms`. Single accepted algorithm.

* One of these four options is required

Algorithm selection. When algorithms (and the deprecated algo) are omitted, the gateway accepts a safe set scoped to the configured key type: the HMAC family (HS256/384/512) for a shared secret, and asymmetric algorithms (RS*, ES*, PS*) for publicKey / jwksUrl / jwksFile. An HMAC token is never accepted against an asymmetric key, preventing algorithm-confusion attacks. Set algorithms to pin an explicit list.

Token Validation

Option	Type	Description	Example
`issuer`	string	Expected `iss` claim value	`"https://auth.example.com"`
`audience`	string	Expected `aud` claim value	`"api.example.com"`
`claimsExpression`	string	Boolean expression for custom claim validation	See Claims Validation

Claim Forwarding

Option	Type	Description
`forward`	map	Project claims onto the upstream request as headers, query parameters and cookies
`forwardHeaders`	map	Deprecated: use `forward.headers`
`forwardAuthorization`	boolean	Whether to forward the original `Authorization` header (default: `true`)

Claims Validation

Use claimsExpression to implement complex validation logic with boolean expressions:

Available Functions

Function	Purpose	Syntax	Example
`Equals`	Exact match comparison	`Equals(claim, value)`	`Equals('email_verified', true)`
`Prefix`	String starts with	`Prefix(claim, prefix)`	`Prefix('email', 'admin@')`
`Contains`	Claim names the value — an exact array element, or a token of a space/comma-separated string. Not a substring test: `Contains('roles', 'admin')` does not match `superadmin`.	`Contains(claim, value)`	`Contains('roles', 'admin')`
`OneOf`	Value matches any option	`OneOf(claim, val1, val2, ...)`	`OneOf('plan', 'pro', 'enterprise')`

Claim keys and string values may be quoted with single quotes, double quotes or backticks. A bare literal is accepted for a value, so Equals('active', true) and Equals(`active`, `true`) mean the same thing.

Logical Operators

! — NOT (highest precedence)
&& — AND (medium precedence)
|| — OR (lowest precedence)

Use parentheses () to control evaluation order.

Expression Examples

# Simple validation
claimsExpression: "Equals('active', true)"

# Multiple conditions
claimsExpression: "Equals('email_verified', true) && OneOf('role', 'admin', 'moderator')"

# Complex logic with grouping
claimsExpression: >
  (Contains('organizations', 'acme') || Contains('organizations', 'globex')) &&
  Equals('email_verified', true) &&
  !Equals('suspended', true)

Claim Forwarding

Project verified claims onto the request sent to your upstream services:

forward:
  headers:
    X-User-ID: sub                    # Standard claim
    X-User-Email: email               # Standard claim
    X-User-Role: user.role            # Nested claim (dot notation)
    X-Department: profile.department  # Deeply nested claim
    X-Is-Admin: permissions.admin     # Boolean claims become "true"/"false"
    X-User-Roles: roles               # Array claims are joined with ","
    X-User-Name: " "   # Template
  query:
    uid: sub
  cookies:
    app_user: email

Option	Type	Description
`headers`	map	Header name → claim path or template.
`query`	map	Query parameter → claim path or template.
`cookies`	map	Cookie name → claim path or template. Added to the upstream request only, never to the client response.
`stripInbound`	boolean	Remove client-supplied copies of every mapped key. Default `true`.
`arraySeparator`	string	Joins array claims. Default `,`.
`encoding`	string	`auto` (default) base64-encodes non-ASCII values and flags them with a `<Header>-Encoding` companion header; `raw` passes them through.
`maxValueBytes`	int	Bounds a single projected value. Default `4096`.

Every mapped key is removed from the incoming request before the verified value is set, on every path of the route — including the ones this middleware does not guard. Without that, a client could send X-User-Email: admin@example.com and your backend would believe it. Set stripInbound: false only when nothing but the gateway can reach the upstream.

Control characters are always removed from forwarded values, so a claim a user can set for themselves cannot inject a second header into the proxied request.

The deprecated flat forwardHeaders map still works and is merged into forward.headers, which takes precedence key by key. The same claim path syntax is used by the OpenID Connect middleware.

Complete Examples

Basic Authentication

middlewares:
  - name: simple-jwt
    type: jwtAuth
    paths: ["/api/.*"]
    rule:
      secret: "your-256-bit-secret"
      algorithms: ["HS256"]
      issuer: "https://your-auth-service.com"

Enterprise Setup with OIDC

middlewares:
  - name: enterprise-jwt
    type: jwtAuth
    paths: ["/.*"]
    rule:
      jwksUrl: "https://auth.company.com/.well-known/jwks.json"
      issuer: "https://auth.company.com"
      audience: "api.company.com"
      algorithms: ["RS256"]
      forwardAuthorization: false
      claimsExpression: >
        Equals('email_verified', true) &&
        OneOf('department', 'engineering', 'product', 'security') &&
        !Equals('account_disabled', true)
      forward:
        headers:
          X-User-ID: sub
          X-User-Email: email
          X-User-Name: name
          X-User-Department: department
          X-User-Roles: roles

Multi-Tenant SaaS

middlewares:
  - name: tenant-jwt
    type: jwtAuth
    paths: ["/tenant/.*/api/.*"]
    rule:
      publicKey: "/etc/ssl/jwt-public.pem"
      algorithms: ["RS256"]
      claimsExpression: >
        Equals('email_verified', true) &&
        Contains('scopes', 'api:read') &&
        OneOf('tenant_role', 'admin', 'user', 'viewer')
      forward:
        headers:
          X-Tenant-ID: tenant_id
          X-User-Role: tenant_role
          X-Permissions: scopes