# How to Secure Communication with Easegress Using TLS: A Complete Guide > Secure Easegress communication with TLS. Learn to configure TLS for the Management API, enable HTTPS via certificates or Let's Encrypt, and secure MQTTProxy with this complete guide. - Repository: [easegress-io/easegress](https://github.com/easegress-io/easegress) - Tags: how-to-guide - Published: 2026-03-01 --- **To secure communication with Easegress using TLS, configure TLS certificates for the Management API via command-line flags, enable HTTPS with certificate base64 strings or automatic Let's Encrypt for HTTPServer objects, and set `useTLS` for MQTTProxy objects.** Easegress is a cloud-native traffic orchestration system that handles both administrative and data-plane traffic. Securing communication with Easegress using TLS involves configuring encryption at multiple layers: the management API, HTTP server objects, and MQTT proxy objects. This guide covers each layer with specific configuration examples and source code references from the Easegress repository. ## TLS for the Easegress Management API The management API handles administrative traffic and can be secured using TLS to encrypt HTTP traffic and optionally enforce mutual TLS (mTLS) for client authentication. ### Command-Line TLS Configuration In [`pkg/option/option.go`](https://github.com/easegress-io/easegress/blob/main/pkg/option/option.go), the server defines flags for TLS configuration: ```go opt.flags.BoolVar(&opt.TLS, "tls", false, "Flag to use secure transport protocol(https).") opt.flags.StringVar(&opt.CertFile, "cert-file", "", "Flag to set the certificate file for https.") opt.flags.StringVar(&opt.KeyFile, "key-file", "", "Flag to set the private key file for https.") opt.flags.BoolVar(&opt.ClientCAFile, "client-ca-file", "", "File containing client CA certificates for mTLS.") ``` When `--tls` is enabled, the server creates a `tls.Config` using the supplied certificate and key files. If `--client-ca-file` is provided, the server enables mutual TLS by setting `ClientAuth` to `RequireAndVerifyClientCert`. **Example startup command:** ```bash ./easegress-server \ --tls \ --cert-file=/etc/easegress/server.crt \ --key-file=/etc/easegress/server.key \ --client-ca-file=/etc/easegress/ca.crt ``` ## TLS for HTTPServer Data Plane Traffic HTTPServer objects handle inbound traffic and support multiple TLS modes: static certificates, automatic Let's Encrypt certificates, and mutual TLS. ### Static Certificate Configuration The HTTPServer specification in [`pkg/object/httpserver/spec.go`](https://github.com/easegress-io/easegress/blob/main/pkg/object/httpserver/spec.go) defines fields for TLS configuration: ```go type Spec struct { HTTPS bool `json:"https" jsonschema:"required"` CertBase64 string `json:"certBase64,omitempty"` KeyBase64 string `json:"keyBase64,omitempty"` Certs map[string]string `json:"certs,omitempty"` Keys map[string]string `json:"keys,omitempty"` // ... } ``` The `tlsConfig()` method (lines 97-164) builds the TLS configuration by loading certificates from base64-encoded strings or domain-specific maps. **Configuration example with static certificates:** ```yaml kind: HTTPServer name: my-https-server spec: https: true address: 0.0.0.0 port: 443 certBase64: keyBase64: ``` ### Automatic Let's Encrypt Certificates Easegress supports automatic certificate issuance via ACME TLS-ALPN-01. Enable this by setting `autoCert: true`: ```yaml kind: HTTPServer name: auto-https spec: https: true autoCert: true address: 0.0.0.0 port: 443 ``` When enabled, the `GetCertificate` callback in [`pkg/object/autocertmanager/autocertmanager.go`](https://github.com/easegress-io/easegress/blob/main/pkg/object/autocertmanager/autocertmanager.go) handles the ACME flow, either returning cached certificates or initiating the TLS-ALPN-01 challenge. ### Mutual TLS for Client Authentication To enforce client certificate authentication, add `caCertBase64` to the HTTPServer spec: ```yaml spec: https: true certBase64: keyBase64: caCertBase64: # Requires clients to present valid certs ``` The `tlsConfig()` method sets `ClientAuth: tls.RequireAndVerifyClientCert` and populates `ClientCAs` when this field is present. ## TLS for MQTT Proxy Objects The MQTT proxy supports TLS encryption for MQTT connections. Configuration is defined in [`pkg/object/mqttproxy/spec.go`](https://github.com/easegress-io/easegress/blob/main/pkg/object/mqttproxy/spec.go): ```go type Spec struct { UseTLS bool `json:"useTLS,omitempty"` Certificate []Certificate `json:"certificate,omitempty"` } type Certificate struct { Name string `json:"name"` Cert string `json:"cert"` // PEM encoded Key string `json:"key"` // PEM encoded } ``` The `tlsConfig()` method (lines 8-22) builds the TLS configuration from the provided certificate list. **Example configuration:** ```yaml kind: MQTTProxy name: mqtt-secure spec: port: 8883 useTLS: true certificate: - name: default cert: | -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- key: | -----BEGIN PRIVATE KEY----- ... -----END PRIVATE KEY----- ``` ## Auto-Certificate Management Architecture The global auto-cert manager ([`pkg/object/autocertmanager/autocertmanager.go`](https://github.com/easegress-io/easegress/blob/main/pkg/object/autocertmanager/autocertmanager.go)) handles ACME certificate lifecycle: 1. **Initialization**: Creates an ACME client and registers with the Let's Encrypt directory 2. **Certificate Cache**: Stores valid certificates in memory and persistent storage 3. **TLS-ALPN-01 Challenge**: Handles the ACME protocol handshake during TLS connections 4. **Renewal**: Automatically renews certificates before expiration When an HTTPServer specifies `autoCert: true`, the `GetCertificate` callback retrieves certificates from this manager rather than static configuration. ## Complete Deployment Example The following configuration demonstrates securing all three layers simultaneously: ```yaml # Management API (HTTPS with client-auth) # Start server with: # ./easegress-server --tls --cert-file=/etc/easegress/api.crt \ # --key-file=/etc/easegress/api.key --client-ca-file=/etc/easegress/api-ca.crt # Public HTTPS with automatic certificates objects: - kind: HTTPServer name: public-site spec: https: true autoCert: true address: 0.0.0.0 port: 443 routerKind: Ordered rules: - path: / backend: my-backend # Internal API with mutual TLS - kind: HTTPServer name: internal-api spec: https: true certBase64: "" keyBase64: "" caCertBase64: "" address: 10.0.0.0/24 port: 8443 rules: - path: /admin backend: admin-service # Secure MQTT broker - kind: MQTTProxy name: mqtt-secure spec: port: 8883 useTLS: true certificate: - name: mqtt-cert cert: | -----BEGIN CERTIFICATE----- MIIDXTCCAkWgAwIBAgIJAKoK/heBjcOuMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV ... -----END CERTIFICATE----- key: | -----BEGIN PRIVATE KEY----- MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC... -----END PRIVATE KEY----- ``` Deploy this configuration using the Easegress CLI: ```bash easegress create -f config.yaml ``` ## Key Source Files Reference | Feature | File | Key Implementation | |---------|------|-------------------| | Management API TLS flags | [`pkg/option/option.go`](https://github.com/easegress-io/easegress/blob/main/pkg/option/option.go) | `TLS`, `CertFile`, `KeyFile`, `ClientCAFile` flags | | HTTPServer TLS config | [`pkg/object/httpserver/spec.go`](https://github.com/easegress-io/easegress/blob/main/pkg/object/httpserver/spec.go) | `tlsConfig()` method (lines 97-164) | | HTTPServer runtime | [`pkg/object/httpserver/runtime.go`](https://github.com/easegress-io/easegress/blob/main/pkg/object/httpserver/runtime.go) | TLS listener creation using `r.spec.tlsConfig()` | | Auto-cert manager | [`pkg/object/autocertmanager/autocertmanager.go`](https://github.com/easegress-io/easegress/blob/main/pkg/object/autocertmanager/autocertmanager.go) | `GetCertificate()` ACME implementation | | MQTTProxy TLS | [`pkg/object/mqttproxy/spec.go`](https://github.com/easegress-io/easegress/blob/main/pkg/object/mqttproxy/spec.go) | `tlsConfig()` method (lines 8-22) | | MQTTProxy listener | [`pkg/object/mqttproxy/broker.go`](https://github.com/easegress-io/easegress/blob/main/pkg/object/mqttproxy/broker.go) | `tls.Listen("tcp", addr, cfg)` | ## Summary - **Management API**: Enable TLS using `--tls`, `--cert-file`, and `--key-file` flags when starting `easegress-server`. Add `--client-ca-file` to enforce mutual TLS for administrative access. - **HTTPServer**: Set `https: true` in the spec. Provide certificates via `certBase64`/`keyBase64` for static configuration, or enable `autoCert: true` for automatic Let's Encrypt issuance. Add `caCertBase64` to require client certificate authentication. - **MQTTProxy**: Set `useTLS: true` and provide PEM-encoded certificates in the `certificate` list to encrypt MQTT broker connections. - **Auto-Cert**: The global auto-cert manager handles ACME TLS-ALPN-01 challenges, certificate caching, and automatic renewal when `autoCert` is enabled. ## Frequently Asked Questions ### How do I enable TLS for the Easegress admin API? Start the Easegress server with the `--tls` flag and provide the certificate and key files using `--cert-file` and `--key-file`. For mutual TLS, add `--client-ca-file` pointing to your CA certificate. This encrypts all administrative traffic on the API port and optionally requires client certificates for authentication. ### Can Easegress automatically obtain TLS certificates? Yes. Set `autoCert: true` in your HTTPServer specification. Easegress will use the auto-cert manager ([`pkg/object/autocertmanager/autocertmanager.go`](https://github.com/easegress-io/easegress/blob/main/pkg/object/autocertmanager/autocertmanager.go)) to automatically obtain and renew certificates from Let's Encrypt using the ACME TLS-ALPN-01 challenge protocol. No manual certificate management is required. ### How do I configure mutual TLS (mTLS) in Easegress? For the Management API, use the `--client-ca-file` flag when starting the server. For HTTPServer objects, add the `caCertBase64` field containing a base64-encoded CA certificate to the spec. This sets `ClientAuth: tls.RequireAndVerifyClientCert` in the TLS configuration, requiring clients to present valid certificates signed by the specified CA. ### What TLS versions and cipher suites does Easegress support? Easegress uses the Go standard library's `crypto/tls` package. By default, it supports TLS 1.2 and TLS 1.3 with secure cipher suites. The specific cipher suites and minimum TLS version can be configured through the Go runtime environment or by modifying the source code in the TLS configuration builders found in [`pkg/object/httpserver/spec.go`](https://github.com/easegress-io/easegress/blob/main/pkg/object/httpserver/spec.go) and related files.