# Easegress Authentication and Authorization Mechanisms: Complete Implementation Guide

> Explore Easegress authentication and authorization mechanisms including Basic Auth, JWT, OAuth 2.0, AWS signing, OIDC, and MQTT. Implement security seamlessly via YAML in this complete guide.

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

---

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

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

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

```yaml
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`](https://github.com/easegress-io/easegress/blob/main/pkg/util/signer/spec.go) and [`pkg/util/signer/signer.go`](https://github.com/easegress-io/easegress/blob/main/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`](https://github.com/easegress-io/easegress/blob/main/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.

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

```yaml
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`](https://github.com/easegress-io/easegress/blob/main/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`](https://github.com/easegress-io/easegress/blob/main/pkg/filters/validator/basicauth.go)) supports htpasswd files, etcd, and LDAP backends for credential validation.
- **JWT Validation** ([`pkg/filters/validator/jwt.go`](https://github.com/easegress-io/easegress/blob/main/pkg/filters/validator/jwt.go)) verifies HMAC or RSA/ECDSA signed tokens from headers or cookies.
- **OAuth 2.0** ([`pkg/filters/validator/oauth2.go`](https://github.com/easegress-io/easegress/blob/main/pkg/filters/validator/oauth2.go)) performs remote token introspection and injects user metadata headers.
- **Request Signing** ([`pkg/util/signer/signer.go`](https://github.com/easegress-io/easegress/blob/main/pkg/util/signer/signer.go)) validates AWS Signature V4 style request signatures.
- **OIDC Adaptor** ([`pkg/filters/oidcadaptor/oidcadaptor.go`](https://github.com/easegress-io/easegress/blob/main/pkg/filters/oidcadaptor/oidcadaptor.go)) implements the authorization-code flow for web authentication.
- **MQTT Auth** ([`pkg/filters/mqttclientauth/mqttauth.go`](https://github.com/easegress-io/easegress/blob/main/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`](https://github.com/easegress-io/easegress/blob/main/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`](https://github.com/easegress-io/easegress/blob/main/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`](https://github.com/easegress-io/easegress/blob/main/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`](https://github.com/easegress-io/easegress/blob/main/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`](https://github.com/easegress-io/easegress/blob/main/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.