How to Configure OAuth2 Validation for Protected Resources in Easegress

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.

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 defines the OAuth2TokenIntrospect struct, while pkg/filters/validator/validator.go handles instantiation via NewOAuth2Validator.

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 supports HMAC-SHA algorithms with hex-encoded secrets.

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, 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	Implements OAuth2TokenIntrospect and OAuth2JWT structs, validation logic, and HTTP client interactions for introspection
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	Step-by-step tutorial covering both introspection and JWT configuration patterns
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 orchestrates the creation of validation components, while OAuth2Validator.Validate in 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 and 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, 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.

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