Cleartext support

While most modern web applications will choose to encrypt all traffic, there are reasons why you will want to support clients who access your website without encryption in cleartext.

Emissary supports both forcing automatic redirection to HTTPS and serving cleartext traffic on a Host.

Cleartext routing

Emissary has full support for routing cleartext traffic to upstream services for a Host.

Only cleartext

The default for the Open-Source Emissary is to serve cleartext on port 8080 in the container. See TLS documentation for information on how to configure TLS termination.

For Ambassador Edge Stack, TLS termination is enabled by default with a self-signed certificate or an ACME Host. To disable TLS termination in Ambassador Edge Stack, delete any existing Hosts and set the requestPolicy.insecure.action to Route in a Host:

apiVersion: getambassador.io/v2
kind: Host
metadata:
  name: example-host
spec:
  hostname: host.example.com
  acmeProvider:
    authority: none
  requestPolicy:
    insecure:
      action: Route

WARNING - Host Configuration: The requestPolicy property of the Host CRD is applied globally within an Emissary instance, even if it is applied to only one Host when multiple Hosts are configured. Different requestPolicy behaviors cannot be applied to different Hosts. It is recommended to apply an identical requestPolicy to all Hosts instead of assuming the behavior, to create a more human readable config.

If a requestPolicy is not defined for a Host, it’s assumed to be Redirect, so even if a Host does not specify it, the default requestPolicy of Redirect will be applied to all Hosts in that Emissary instance. If the behavior expected out of Emissary is anything other than Redirect, it must be explicitly enumerated in all Host resources.

Unexpected behavior can occur when multiple Host resources are not using the same value for requestPolicy.

For more information, please refer to the Host documentation.

The insecure-action can be one of:

• Redirect (the default): redirect to HTTPS
• Route: go ahead and route as normal; this will allow handling HTTP requests normally
• Reject: reject the request with a 400 response

HTTPS and cleartext

Emissary can also support serving both HTTPS and cleartext traffic from a single Emissary.

This configuration is the same whether you are running the Open-Source Emissary or the Ambassador Edge Stack. The configuration is very similar to the Host above but with the Host configured to terminate TLS.

apiVersion: getambassador.io/v2
kind: Host
metadata:
  name: example-host
spec:
  hostname: host.example.com
  acmeProvider:
    authority: none
  tlsSecret:
    name: example-cert
  requestPolicy:
    insecure:
      action: Route
      additionalPort: 8080

With the above configuration, we are tell Emissary to terminate TLS with the certificate in the example-cert Secret and route cleartext traffic that comes in over port 8080.

HTTP->HTTPS redirection

Most modern websites that force HTTPS will also automatically redirect any requests that come into it over HTTP. In Ambassador Edge Stack, this is enabled by default but can easily be enabled in any version of Emissary.

Client              Emissary
|                             |
| http://<hostname>/api       |
| --------------------------> |
| 301: https://<hostname>/api |
| <-------------------------- |
| https://<hostname>/api      |
| --------------------------> |
|                             |

In Emissary, this is configured by setting the insecure.action in a Host to Redirect.

requestPolicy:
  insecure:
    action: Redirect
    additionalPort: 8080

Emissary will then enable cleartext redrection in two ways.

First, Emissary will listen on the insecure.additionalPort and consider any traffic on this port as insecure and redirect it to HTTPS.

requestPolicy:
  insecure:
    action: Redirect
    additionalPort: 8080

Additionally, Emissary will also check the X-Forwarded-Proto header of the incoming request on the secure port (8443)and issue a 301 redirect if it is set to HTTP.

The value of X-Forwarded-Proto is dependent on whatever is forwarding traffic to Emissary. A couple of options are

• Layer 4 Load Balancer, Proxy, or direct from the client:

  X-Forwarded-Proto is not set or is untrusted. Envoy will set it based off the protocol of the incoming request.

  If Envoy determines the request is encrypted, it will be set to HTTPS. If not, it will be set to HTTP.

• Layer 7 Load Balancer or Proxy:

  X-Forwarded-Proto is set by the load balancer or proxy and trusted by Envoy. Envoy will trust the value of X-Forwarded-For even if the request comes in over cleartext.

  If you are using a layer 7 load balancer, it is critical that the system be configured correctly. The xff_num_trusted_hops element, although its name reflects X-Forwarded-For, is also used when determining trust for X-Forwarded-For, and it is therefore important to set it correctly. Its default of 0 should always be correct when Emissary is behind only layer 4 load balancers. Note that in rare cases the load balancer may remove or impact these headers so checking that the defaults are in place is recommended.

Summary

Ambassador Edge Stack will enable cleartext redirection by default.

To enable cleartext redirection in any version of Emissary, simply configure a Host to redirect cleartext to HTTPS like below:

apiVersion: getambassador.io/v2
kind: Host
metadata:
  name: example-host
spec:
  hostname: host.example.com
  requestPolicy:
    insecure:
      action: Redirect     # Configures Emissary to redirect cleartext
      additionalPort: 8080 # Optional: The redirect port. Defaults to 8080