badblocks/docker-easy-haproxy
1
0
Fork 0
Code Activity
docker-easy-haproxy/docs/reference/plugins/jwt-validator.md
Joao Gilberto Magalhaes 4b7f42473a Fix build error
2026-02-20 14:34:38 -05:00

8.3 KiB
Raw Permalink Blame History

sidebar_position sidebar_label
1 JWT Validator

JWT Validator Plugin

Type: Domain Plugin Runs: Once for each discovered domain/host

Overview

The JWT Validator plugin validates JWT (JSON Web Token) authentication tokens using HAProxy's built-in JWT functionality.

Why Use It

Protect APIs and services with JWT authentication without needing application-level code.

Generating JWT Keys

# Generate RSA key pair (idempotent - skips if exists)
[ -f jwt_private.pem ] || openssl genrsa -out jwt_private.pem 2048
[ -f jwt_pubkey.pem ] || openssl rsa -in jwt_private.pem -pubout -out jwt_pubkey.pem

Configuration Options

Option Description Default
enabled Enable/disable plugin true
algorithm JWT signing algorithm RS256
issuer Expected JWT issuer (optional, set to none/null to skip validation) (optional)
audience Expected JWT audience (optional, set to none/null to skip validation) (optional)
pubkey_path Path to public key file (priority 1: explicit file path) (optional)
pubkey Public key content as base64-encoded string (priority 2: inline content) (optional)
k8s_secret.pubkey Kubernetes secret containing public key (priority 3: Kubernetes only) (optional)
paths List of paths that require JWT validation (optional) (all paths)
only_paths If true, only specified paths are accessible; if false, only specified paths require JWT false
allow_anonymous If true, allows requests without Authorization header (validates JWT if present) false

Public Key Configuration Priority

When multiple public key options are configured, they are evaluated in this order:

  1. pubkey_path - Direct file path (explicit configuration)
  2. pubkey - Base64-encoded key content (inline configuration)
  3. k8s_secret.pubkey - Kubernetes secret (recommended for Kubernetes deployments)

Path Validation Logic

  • No paths configured: ALL requests to the domain require JWT validation (default behavior)
  • Paths configured + only_paths=false: Only specified paths require JWT validation, other paths pass through without validation
  • Paths configured + only_paths=true: Only specified paths are accessible (with JWT validation), all other paths are denied

Anonymous Access Logic

  • allow_anonymous=false (default): Requests without Authorization header are denied
  • allow_anonymous=true: Requests without Authorization header are allowed to pass through, but JWTs are validated if the header is present

Configuration Examples

Docker/Docker Compose (Protect All Paths)

services:
  api:
    labels:
      easyhaproxy.http.host: api.example.com
      easyhaproxy.http.plugins: jwt_validator
      easyhaproxy.http.plugin.jwt_validator.algorithm: RS256
      easyhaproxy.http.plugin.jwt_validator.issuer: https://auth.example.com/
      easyhaproxy.http.plugin.jwt_validator.audience: https://api.example.com
      easyhaproxy.http.plugin.jwt_validator.pubkey_path: /etc/easyhaproxy/jwt_keys/api_pubkey.pem
    volumes:
      - ./pubkey.pem:/etc/easyhaproxy/jwt_keys/api_pubkey.pem:ro

Protect Specific Paths Only

labels:
  easyhaproxy.http.plugins: jwt_validator
  easyhaproxy.http.plugin.jwt_validator.pubkey_path: /etc/easyhaproxy/jwt_keys/api_pubkey.pem
  easyhaproxy.http.plugin.jwt_validator.paths: /api/admin,/api/sensitive
  easyhaproxy.http.plugin.jwt_validator.only_paths: false
# /api/health, /api/docs, etc. remain publicly accessible

Only Allow Specific Paths

labels:
  easyhaproxy.http.plugins: jwt_validator
  easyhaproxy.http.plugin.jwt_validator.pubkey_path: /etc/easyhaproxy/jwt_keys/api_pubkey.pem
  easyhaproxy.http.plugin.jwt_validator.paths: /api/public,/api/v1
  easyhaproxy.http.plugin.jwt_validator.only_paths: true
# All paths except /api/public and /api/v1 are denied

Kubernetes with Secrets (Recommended)

---
apiVersion: v1
kind: Secret
metadata:
  name: jwt-pubkey-secret
  namespace: production
type: Opaque
stringData:
  pubkey: |
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
    -----END PUBLIC KEY-----

---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-ingress
  namespace: production
  annotations:
    easyhaproxy.plugins: "jwt_validator"
    easyhaproxy.plugin.jwt_validator.algorithm: "RS256"
    easyhaproxy.plugin.jwt_validator.issuer: "https://auth.example.com/"
    easyhaproxy.plugin.jwt_validator.audience: "https://api.example.com"
    easyhaproxy.plugin.jwt_validator.k8s_secret.pubkey: "jwt-pubkey-secret"
    easyhaproxy.plugin.jwt_validator.paths: "/api/admin,/api/users"
    easyhaproxy.plugin.jwt_validator.only_paths: "false"
spec:
  ingressClassName: easyhaproxy
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: api-service
                port:
                  number: 8080

Static YAML Configuration

# /etc/easyhaproxy/static/config.yaml
containers:
  "api.example.com:443":
    ip: ["api-service:8080"]
    ssl: true
    plugins: [jwt_validator]
    plugin:
      jwt_validator:
        algorithm: RS256
        issuer: https://auth.example.com/
        audience: https://api.example.com
        pubkey_path: /etc/easyhaproxy/jwt_keys/api_pubkey.pem

Environment Variables

Environment Variable Config Key Type Default Description
EASYHAPROXY_PLUGIN_JWT_VALIDATOR_ENABLED enabled boolean true Enable/disable plugin for all domains
EASYHAPROXY_PLUGIN_JWT_VALIDATOR_ALGORITHM algorithm string RS256 JWT signing algorithm
EASYHAPROXY_PLUGIN_JWT_VALIDATOR_ISSUER issuer string - Expected JWT issuer (optional)
EASYHAPROXY_PLUGIN_JWT_VALIDATOR_AUDIENCE audience string - Expected JWT audience (optional)
EASYHAPROXY_PLUGIN_JWT_VALIDATOR_PUBKEY_PATH pubkey_path string - Path to public key file
EASYHAPROXY_PLUGIN_JWT_VALIDATOR_PUBKEY pubkey string - Public key as base64-encoded string
EASYHAPROXY_PLUGIN_JWT_VALIDATOR_PATHS paths string - Comma-separated paths requiring JWT
EASYHAPROXY_PLUGIN_JWT_VALIDATOR_ONLY_PATHS only_paths boolean false If true, only specified paths accessible
EASYHAPROXY_PLUGIN_JWT_VALIDATOR_ALLOW_ANONYMOUS allow_anonymous boolean false Allow requests without Authorization header

What It Validates

  • ✅ Authorization header presence
  • ✅ JWT signing algorithm (RS256, RS512, etc.)
  • ✅ JWT issuer (if configured)
  • ✅ JWT audience (if configured)
  • ✅ JWT signature using public key
  • ✅ JWT expiration time

Important Notes

  • Required: HAProxy 2.5+ with JWT support
  • Mount public key file as read-only volume
  • The plugin runs once per domain during the discovery cycle
  • Test thoroughly with your JWT provider before deploying to production

Related Documentation