Easegress Authentication and Authorization Mechanisms: Complete Implementation Guide

Easegress provides filter-level authentication and authorization mechanisms including HTTP Basic Auth, JWT validation, OAuth 2.0 token introspection, AWS-style request signing, OpenID Connect, and MQTT client authentication, all configurable through YAML pipeline specifications in the easegress-io/easegress repository.

Easegress is a cloud-native traffic orchestration system that implements security at the filter level. The authentication and authorization mechanisms are implemented as Go filters that intercept incoming requests before they reach backend services. This article examines the specific implementations found in the source code, including file paths, configuration options, and practical deployment examples.

Core HTTP Authentication Filters

Easegress implements multiple HTTP authentication strategies within the pkg/filters/validator/ directory. Each filter registers itself via filters.Register(kind) in its init() function, making it available for pipeline configuration.

HTTP Basic Authentication

The HTTP Basic Auth filter in pkg/filters/validator/basicauth.go validates credentials against three backend types: htpasswd files, etcd key-value stores, or LDAP servers.

The filter extracts the Authorization: Basic … header and validates the username-password pair. For LDAP configurations, it connects to the LDAP server, binds with a service account, and searches for the uid attribute to validate credentials.

pipeline:
  name: demo-pipeline
  filters:
    - type: Validator
      name: http-basic
      spec:
        basicAuth:
          mode: FILE          # FILE | ETCD | LDAP

          userFile: "/etc/apache2/.htpasswd"

JWT Validation

The JWT validator in pkg/filters/validator/jwt.go supports both HMAC and RSA/ECDSA signature algorithms. It extracts tokens from either a configurable cookie or the Authorization: Bearer … header.

The filter verifies the signature and optionally checks token expiry. If validation fails, it returns 401 Unauthorized and aborts the pipeline.

pipeline:
  name: jwt-demo
  filters:
    - type: Validator
      name: jwt-validate
      spec:
        jwt:
          algorithm: RS256
          publicKey: "30819f300d06092a864886f70d01010b... (hex‑encoded PEM)"
          cookieName: "jwt-token"   # optional – otherwise use Bearer header

OAuth 2.0 Token Introspection

The OAuth 2.0 validator in pkg/filters/validator/oauth2.go performs remote token introspection or validates self-contained JWTs. It sends a POST request to the configured introspection endpoint and checks the active flag in the response.

Upon successful validation, the filter injects X‑Authenticated‑Userid and X‑Authenticated‑Scope headers into the request for downstream services to consume.

pipeline:
  name: oauth-demo
  filters:
    - type: Validator
      name: oauth2-introspect
      spec:
        oauth2:
          tokenIntrospect:
            endPoint: "https://oauth2.example.com/introspect"
            clientId: "gateway-client"
            clientSecret: "s3cr3t"

Request Signature Verification

The signature validator leverages the signer utility in pkg/util/signer/spec.go and pkg/util/signer/signer.go to verify AWS Signature V4 style request signing. It validates that the Authorization header contains a correctly computed signature based on the configured access key and secret.

This mechanism protects against replay attacks and ensures request integrity without requiring TLS client certificates.

Advanced Authorization Mechanisms

Beyond the core validator filters, Easegress provides specialized adaptors for modern authentication protocols and IoT protocols.

OpenID Connect (OIDC) Adaptor

The OIDC adaptor in pkg/filters/oidcadaptor/oidcadaptor.go implements the complete authorization-code flow. It redirects unauthenticated users to the OIDC provider, handles the callback, validates the returned ID-token (JWT), and establishes session state.

Configuration options allow forwarding the access token, ID token, and user information via custom headers (e.g., X-User-Info) to backend services.

pipeline:
  name: oidc-demo
  filters:
    - type: OIDCAdaptor
      name: oidc-auth
      spec:
        clientId: "my-client"
        clientSecret: "my-secret"
        discovery: "https://accounts.google.com/.well-known/openid-configuration"
        redirectURI: "https://gateway.example.com/callback"

MQTT Client Authentication

For IoT deployments, the MQTT client authentication filter in pkg/filters/mqttclientauth/mqttauth.go validates credentials in the MQTT CONNECT packet. It compares the username/password pair against a map of salted-SHA256 passwords defined in the filter specification.

If authentication fails, the filter returns a DISCONNECT packet and sets a result string (resultAuthFail) that subsequent filters or routing logic can inspect.

pipeline:
  name: mqtt-demo
  filters:
    - type: MQTTClientAuth
      name: mqtt-auth
      spec:
        salt: "randomSalt"
        auth:
          - username: "deviceA"
            saltedSha256Pass: "6f1e2d3c..."   # SHA256(username+password+salt)

          - username: "deviceB"
            saltedSha256Pass: "9a8b7c6d..."

Pipeline Architecture and Filter Registration

All authentication filters register themselves via filters.Register(kind) in their init() functions, as defined in pkg/registry/registry.go. A pipeline specification references these kinds under the filters array.

When a request arrives, the filter's Handle(ctx *context.Context) method executes. For HTTP traffic, this method reads *httpprot.Request; for MQTT, it reads *mqttprot.Request. The filter either continues the pipeline or writes an error response (401/403) and aborts processing.

Filters can be chained sequentially. A request must pass all configured validators; the first failure terminates the chain. This design allows operators to implement defense-in-depth by combining multiple authentication factors.

Summary

• HTTP Basic Auth (pkg/filters/validator/basicauth.go) supports htpasswd files, etcd, and LDAP backends for credential validation.
• JWT Validation (pkg/filters/validator/jwt.go) verifies HMAC or RSA/ECDSA signed tokens from headers or cookies.
• OAuth 2.0 (pkg/filters/validator/oauth2.go) performs remote token introspection and injects user metadata headers.
• Request Signing (pkg/util/signer/signer.go) validates AWS Signature V4 style request signatures.
• OIDC Adaptor (pkg/filters/oidcadaptor/oidcadaptor.go) implements the authorization-code flow for web authentication.
• MQTT Auth (pkg/filters/mqttclientauth/mqttauth.go) validates IoT device credentials using salted SHA-256 hashes.

Frequently Asked Questions

How does Easegress verify JWT signatures?

The JWT validator in pkg/filters/validator/jwt.go extracts the token from either the Authorization: Bearer header or a configurable cookie. It supports RS256, ES256, and HS256 algorithms. For asymmetric algorithms, you provide a hex-encoded public key in the filter spec; for symmetric algorithms, provide the shared secret. The filter validates the signature, checks the exp claim if present, and rejects expired or malformed tokens with a 401 response.

Can Easegress authenticate MQTT connections for IoT devices?

Yes. The MQTTClientAuth filter in pkg/filters/mqttclientauth/mqttauth.go handles authentication for MQTT brokers. When a client sends a CONNECT packet, the filter extracts the username and password, concatenates them with a configured salt, computes the SHA-256 hash, and compares it against the saltedSha256Pass entries defined in the filter spec. If validation fails, the filter returns a DISCONNECT packet and sets the resultAuthFail result for downstream processing.

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

JWT validation (pkg/filters/validator/jwt.go) is a local operation: the gateway validates the token's cryptographic signature and claims without external dependencies. It works for self-contained JWTs.

OAuth 2.0 token introspection (pkg/filters/validator/oauth2.go) is a remote validation: the filter sends the token to an authorization server's introspection endpoint (e.g., https://oauth2.example.com/introspect). The endpoint returns an active boolean and scope information. This approach supports opaque tokens and centralized revocation checking. Upon success, the filter injects X-Authenticated-Userid and X-Authenticated-Scope headers into the request.

How do I configure LDAP-backed Basic Authentication?

In pkg/filters/validator/basicauth.go, the Basic Auth filter supports an LDAP configuration block. Set mode: LDAP in the spec and provide the ldapSpec fields: url (e.g., ldap://localhost:389), baseDN (e.g., dc=example,dc=com), and uid attribute (typically uid or cn). The filter binds with a service account, searches for the user entry, and attempts a bind with the provided password to validate credentials. This allows integration with existing corporate directory services without maintaining separate password files.

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