# How to Set Up JWT Verification for API Security in Easegress

> Secure your APIs with Easegress by setting up JWT verification. Learn how to use the built-in jwt-validator filter to easily verify token signatures for robust API security.

- Repository: [MegaEase/easegress](https://github.com/megaease/easegress)
- Tags: how-to-guide
- Published: 2026-03-07

---

**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`](https://github.com/megaease/easegress/blob/main/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`](https://github.com/megaease/easegress/blob/main/pkg/filters/validator/jwt.go), the configuration accepts:

```go
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`):

```yaml
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:

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

```

The implementation in [`pkg/filters/validator/jwt.go`](https://github.com/megaease/easegress/blob/main/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:

```yaml
- 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`](https://github.com/megaease/easegress/blob/main/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`](https://github.com/megaease/easegress/blob/main/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.