# How to Configure OAuth2 Validation for Protected Resources in Easegress

> Configure OAuth2 validation for protected resources in Easegress using the Validator filter. Support token introspection and JWT validation for secure access.

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

---

**To configure OAuth2 validation in Easegress, use the Validator filter with either token introspection for opaque tokens or JWT validation for self-encoded tokens, configured in the `oauth2` section of your Pipeline YAML.**

When securing APIs with OAuth 2.0, Easegress provides built-in validation through the **Validator** filter. This article explains how to configure OAuth2 validation for protected resources in Easegress using two distinct modes: external token introspection for opaque tokens and local JWT verification for self-encoded tokens.

## Understanding OAuth2 Validation Modes

The Validator filter in Easegress supports two mutually exclusive approaches to OAuth2 validation, implemented in [`pkg/filters/validator/oauth2.go`](https://github.com/megaease/easegress/blob/main/pkg/filters/validator/oauth2.go).

### Token Introspection Mode

**Token introspection** delegates validation to an external authorization server. The filter extracts the bearer token from the `Authorization` header and POSTs it to a configured introspection endpoint (such as Keycloak or Auth0). This mode handles opaque tokens that cannot be parsed locally.

### Self-Encoded JWT Mode

**JWT validation** parses and verifies JSON Web Tokens locally using HMAC algorithms (HS256, HS384, or HS512). The filter validates the signature against a hex-encoded secret configured in the pipeline. This mode avoids external network calls but requires symmetric key management.

## Configuring Token Introspection for Opaque Tokens

To protect resources using an external OAuth2 provider, configure the `tokenIntrospect` section in your Validator filter. The implementation in [`pkg/filters/validator/oauth2.go`](https://github.com/megaease/easegress/blob/main/pkg/filters/validator/oauth2.go) defines the `OAuth2TokenIntrospect` struct, while [`pkg/filters/validator/validator.go`](https://github.com/megaease/easegress/blob/main/pkg/filters/validator/validator.go) handles instantiation via `NewOAuth2Validator`.

```yaml
name: oauth2-protected-pipeline
kind: Pipeline
flow:
  - filter: oauth-validator
  - filter: proxy
filters:
  - kind: Validator
    name: oauth-validator
    oauth2:
      tokenIntrospect:
        endPoint: https://auth.example.com/realms/demo/protocol/openid-connect/token/introspect
        clientId: easegress
        clientSecret: 01234567-89ab-cdef-0123-456789abcdef
        insecureTls: false

```

When the `Validate` method processes a request, it extracts the bearer token, constructs a POST request to the configured `endPoint`, and optionally includes `client_id` and `client_secret` parameters or a `Basic` authentication header. The response JSON is decoded into a `tokenInfo` structure; if the `active` field is `false`, the filter returns HTTP 401 and terminates the request. Set `insecureTls: true` only for testing with self-signed certificates.

## Configuring JWT Validation for Self-Encoded Tokens

For scenarios requiring local validation without external dependencies, configure the `jwt` section. The `OAuth2JWT` struct in [`pkg/filters/validator/oauth2.go`](https://github.com/megaease/easegress/blob/main/pkg/filters/validator/oauth2.go) supports HMAC-SHA algorithms with hex-encoded secrets.

```yaml
name: jwt-protected-pipeline
kind: Pipeline
flow:
  - filter: jwt-validator
  - filter: proxy
filters:
  - kind: Validator
    name: jwt-validator
    oauth2:
      jwt:
        algorithm: HS256
        secret: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

```

During initialization, `NewOAuth2Validator` decodes the hex string using `hex.DecodeString` and stores the byte slice as the HMAC key. When validating requests, the filter parses the JWT using `github.com/golang-jwt/jwt`, verifies the signature against the configured `algorithm`, and extracts the `sub` and `scope` claims.

## Accessing Authentication Data in Downstream Services

Upon successful validation, the Validator filter injects authentication context into request headers for downstream consumption. According to the implementation in [`pkg/filters/validator/oauth2.go`](https://github.com/megaease/easegress/blob/main/pkg/filters/validator/oauth2.go), the following headers are added:

- **`X-Authenticated-Userid`**: Contains the `sub` claim from JWTs or the `subject` field from introspection responses
- **`X-Authenticated-Scope`**: Contains the `scope` claim or field, representing granted permissions

Backend services can read these headers to implement fine-grained access control without parsing tokens themselves.

## Implementation Details and Source Code Reference

The OAuth2 validation logic is distributed across the Easegress codebase as follows:

| File | Role |
|------|------|
| [`pkg/filters/validator/oauth2.go`](https://github.com/megaease/easegress/blob/main/pkg/filters/validator/oauth2.go) | Implements `OAuth2TokenIntrospect` and `OAuth2JWT` structs, validation logic, and HTTP client interactions for introspection |
| [`pkg/filters/validator/validator.go`](https://github.com/megaease/easegress/blob/main/pkg/filters/validator/validator.go) | Defines the `Validator` filter, handles configuration reloading via `Validator.reload`, and instantiates `OAuth2Validator` through `NewOAuth2Validator` |
| [`docs/02.Tutorials/2.5.Traffic-Verification.md`](https://github.com/megaease/easegress/blob/main/docs/02.Tutorials/2.5.Traffic-Verification.md) | Step-by-step tutorial covering both introspection and JWT configuration patterns |
| [`docs/07.Reference/7.02.Filters.md`](https://github.com/megaease/easegress/blob/main/docs/07.Reference/7.02.Filters.md) | Complete reference for `Validator` filter specifications including `OAuth2ValidatorSpec` |

The `Validator.reload` method in [`pkg/filters/validator/validator.go`](https://github.com/megaease/easegress/blob/main/pkg/filters/validator/validator.go) orchestrates the creation of validation components, while `OAuth2Validator.Validate` in [`pkg/filters/validator/oauth2.go`](https://github.com/megaease/easegress/blob/main/pkg/filters/validator/oauth2.go) executes the per-request authentication checks.

## Summary

- **Use the Validator filter** to configure OAuth2 validation for protected resources in Easegress pipelines
- **Choose token introspection** when using opaque tokens from external providers like Keycloak; configure `endPoint`, `clientId`, and `clientSecret` in the `tokenIntrospect` section
- **Choose JWT validation** for self-encoded tokens using HMAC algorithms; configure `algorithm` and hex-encoded `secret` in the `jwt` section
- **Access authentication context** via `X-Authenticated-Userid` and `X-Authenticated-Scope` headers in downstream filters
- **Reference implementation** resides in [`pkg/filters/validator/oauth2.go`](https://github.com/megaease/easegress/blob/main/pkg/filters/validator/oauth2.go) and [`pkg/filters/validator/validator.go`](https://github.com/megaease/easegress/blob/main/pkg/filters/validator/validator.go)

## Frequently Asked Questions

### What is the difference between token introspection and JWT validation in Easegress?

Token introspection delegates validation to an external OAuth2 authorization server by sending the bearer token to a configured endpoint and checking the `active` status in the response. JWT validation parses and verifies JSON Web Tokens locally using symmetric HMAC algorithms (HS256/HS384/HS512) without external network calls. Use introspection for opaque tokens from providers like Keycloak, and JWT validation when you control the signing key and want to avoid latency from external requests.

### How do I pass the authenticated user information to my backend service?

When OAuth2 validation succeeds, the Validator filter automatically injects two headers into the request before forwarding it to downstream filters like `Proxy`. The `X-Authenticated-Userid` header contains the `sub` claim from JWTs or the `subject` field from introspection responses, while `X-Authenticated-Scope` contains the granted permissions. Your backend service can read these headers to identify the user and enforce authorization policies without processing the token itself.

### Can I use asymmetric algorithms like RS256 for JWT validation?

According to the source code in [`pkg/filters/validator/oauth2.go`](https://github.com/megaease/easegress/blob/main/pkg/filters/validator/oauth2.go), the current implementation only supports symmetric HMAC algorithms: HS256, HS384, and HS512. The `algorithm` field in the JWT configuration accepts only these three values, and the validation uses the hex-decoded secret as the HMAC key. Asymmetric algorithms like RS256 or ES256 using public/private key pairs are not implemented in the current version of the Validator filter.

### How do I troubleshoot OAuth2 validation failures in Easegress?

When validation fails, the Validator filter returns HTTP 401 and tags the request with a specific error message that appears in Easegress logs. For introspection failures, verify that the `endPoint` URL is reachable, the `clientId` and `clientSecret` are correct, and set `insecureTls: true` only temporarily if using self-signed certificates. For JWT failures, ensure the `secret` is a valid hex string and matches the algorithm used to sign the token (HS256/HS384/HS512). Check the logs for specific error tags from `OAuth2Validator.Validate` to identify whether the failure occurred during token extraction, endpoint communication, or signature verification.