How to Set Up JWT Verification for API Security in Easegress

Easegress validates JWT tokens using the built-in jwt-validator filter, which extracts tokens from either the Authorization: Bearer header or a configured cookie, then verifies signatures using HMAC secrets or RSA/ECDSA public keys provided in hex-encoded format.

Easegress, the open-source traffic orchestration system from MegaEase, provides native JWT verification to secure API endpoints without requiring external authentication services. This guide explains how to configure the jwt-validator filter using the actual implementation details found in the megaease/easegress repository source code.

JWT Validator Architecture and Source Code

The JWT validation logic resides in pkg/filters/validator/jwt.go and processes tokens through a strict validation pipeline before allowing requests to reach upstream services.

Configuration Structure

The JWTValidatorSpec struct defines the supported algorithms and key formats. According to lines 32-44 of pkg/filters/validator/jwt.go, the configuration accepts:

type JWTValidatorSpec struct {
    Algorithm  string `json:"algorithm" jsonschema:"enum=HS256,enum=HS384,enum=HS512,enum=RS256,enum=RS384,enum=RS512,enum=ES256,enum=ES384,enum=ES512,enum=EdDSA"`
    PublicKey  string `json:"publicKey" jsonschema:"pattern=^$|^[A-Fa-f0-9]+$"` // hex-encoded PEM
    Secret     string `json:"secret"    jsonschema:"pattern=^$|^[A-Fa-f0-9]+$"` // hex-encoded HMAC secret
    CookieName string `json:"cookieName,omitempty"`
}

Key implementation details:

• HMAC algorithms (HS256, HS384, HS512) require a hex-encoded secret string.
• Asymmetric algorithms (RS256, RS384, RS512, ES256, ES384, ES512, EdDSA) require a hex-encoded PEM public key in the publicKey field.
• The CookieName field optionally enables token extraction from cookies instead of headers.

Token Extraction and Verification Flow

The Validate method (lines 67-99) implements the following logic:

1. Token extraction (lines 67-84): Checks the configured cookie first if CookieName is set; otherwise falls back to parsing the Authorization: Bearer <token> header.
2. Signature verification (lines 85-98): Uses the golang-jwt library to parse the token. The validation callback asserts that the token's signing method matches the configured Algorithm and returns the prepared key (decoded from hex). If t.Valid is true, the request proceeds; otherwise, the filter returns an error that aborts the pipeline.

The NewJWTValidator function (lines 45-58) handles the initial hex-decoding and PEM parsing during filter initialization to avoid runtime overhead.

Configuring JWT Verification in Your Pipeline

To protect API endpoints, place the jwt-validator filter before the proxy filter in your pipeline definition. The filter accepts Kubernetes-style CRD YAML or native Easegress pipeline configurations.

HMAC-Based Validation (HS256/HS384/HS512)

For symmetric key verification, provide the hex-encoded secret. This example uses HS256 with the secret "mysecret" (hex: 6d79736563726574):

name: secure-api-pipeline
kind: Pipeline
flow:
  - filter: jwt-validator
  - filter: proxy
filters:
  - kind: Validator
    name: jwt-validator
    jwt:
      algorithm: HS256
      secret: 6d79736563726574
  - name: proxy
    kind: Proxy
    pools:
      - servers:
          - url: http://backend:8080

RSA and ECDSA Validation (RS256/ES256)

For asymmetric verification, convert your PEM public key to hex format and specify the appropriate algorithm:

- kind: Validator
  name: jwt-validator
  jwt:
    algorithm: RS256
    publicKey: 3082010a0282010100...  # hex-encoded PEM contents

The implementation in pkg/filters/validator/jwt.go parses this hex string into an RSA or ECDSA public key during initialization, then uses it to verify the JWT signature on each request.

Cookie-Based Token Extraction

To read the JWT from a cookie instead of the Authorization header, add the cookieName field:

- kind: Validator
  name: jwt-validator
  jwt:
    cookieName: access_token
    algorithm: HS256
    secret: a1b2c3d4e5f60708a9b0c1d2e3f4a5b6

When configured, the validator checks for Cookie: access_token=<token> before falling back to the header. If neither contains a valid token, the request is rejected with a 401 response.

Summary

• Use kind: Validator with an embedded jwt block to enable JWT verification in Easegress pipelines.
• Provide hex-encoded keys: Use the secret field for HMAC algorithms or publicKey (hex-encoded PEM) for RSA/ECDSA.
• Token extraction order: When cookieName is configured, cookies take precedence over the Authorization header.
• Pipeline placement: Always position jwt-validator before the proxy filter to ensure unauthenticated requests never reach upstream services.

Frequently Asked Questions

What JWT algorithms does Easegress support?

Easegress supports HS256, HS384, HS512 for HMAC; RS256, RS384, RS512 for RSA; ES256, ES384, ES512 for ECDSA; and EdDSA for Edwards-curve signatures. These are defined in the JWTValidatorSpec struct in pkg/filters/validator/jwt.go.

How do I convert my PEM key to the hex format required by Easegress?

Convert your PEM file to a hex string by removing headers/footers and newlines, then encoding the remaining base64 content as hexadecimal. For example, use xxd -p -c 256 public.pem on Linux, or programmatically convert the PEM bytes to hex representation before embedding in the YAML configuration.

Can I validate JWT tokens from cookies instead of headers?

Yes. Set the cookieName field in the JWT validator configuration. When present, the validator extracts the token from that cookie name; if absent, it falls back to the standard Authorization: Bearer header. This is implemented in the Validate method at lines 67-84 of pkg/filters/validator/jwt.go.

Where should the jwt-validator filter be placed in the pipeline?

Place it as the first or early filter in the flow array, before the proxy filter. The pipeline processes filters sequentially, and the validator must intercept requests before they reach upstream services. If validation fails, the pipeline aborts immediately with a 401 or 403 response.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}