Securing Envoy

Envoy provides a number of features to secure traffic in and out of your network, and between proxies and services within your network.

Transport Layer Security (TLS) can be used to secure all types of HTTP traffic, including WebSockets.

Envoy also has support for transmitting and receiving generic TCP traffic with TLS.

Envoy also offers a number of other HTTP-based protocols for authentication and authorization such as JWT, RBAC and OAuth.

Warning

The following guide takes you through individual aspects of securing traffic.

To secure traffic over a network that is untrusted, you are strongly advised to make use of encryption and mutual authentication wherever you control both sides of the connection or where relevant protocols are available.

Here we provide a guide to using mTLS which provides both encryption and mutual authentication.

When using TLS, you are strongly encouraged to validate all certificates wherever possible.

It is your responsibility to ensure the integrity of your certificate chain, and outside the scope of this guide.

Upstream and downstream TLS contexts

Machines connecting to Envoy to proxy traffic are “downstream” in relation to Envoy.

Specifying a TLS context that clients can connect to is achieved by setting the DownstreamTLSContext in the transport_socket of a listener.

You will also need to provide valid certificates.

envoy-demo-tls.yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
static_resources:

  listeners:
  - name: listener_0
    address:
      socket_address:
        address: 0.0.0.0
        port_value: 10000
    filter_chains:
    - filters:
      - name: envoy.filters.network.http_connection_manager
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
          stat_prefix: ingress_http
          http_filters:
          - name: envoy.filters.http.router
          route_config:
            name: local_route
            virtual_hosts:
            - name: local_service
              domains: ["*"]
              routes:
              - match:
                  prefix: "/"
                route:
                  host_rewrite_literal: www.envoyproxy.io
                  cluster: service_envoyproxy_io
      transport_socket:
        name: envoy.transport_sockets.tls
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext
          common_tls_context:
            tls_certificates:
            - certificate_chain:
                filename: certs/servercert.pem
              private_key:
                filename: certs/serverkey.pem
Copy to clipboard

Connecting to an “upstream” TLS service is conversely done by adding an UpstreamTLSContext to the transport_socket of a cluster.

envoy-demo-tls.yaml
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
  clusters:
  - name: service_envoyproxy_io
    connect_timeout: 30s
    type: LOGICAL_DNS
    # Comment out the following line to test on v6 networks
    dns_lookup_family: V4_ONLY
    load_assignment:
      cluster_name: service_envoyproxy_io
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: www.envoyproxy.io
                port_value: 443
    transport_socket:
      name: envoy.transport_sockets.tls
      typed_config:
        "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext
Copy to clipboard

Validate an endpoint’s certificates when connecting

When Envoy connects to an upstream TLS service, it does not, by default, validate the certificates that it is presented with.

You can use the validation_context to specify how Envoy should validate these certificates.

Firstly, you can ensure that the certificates are from a mutually trusted certificate authority:

envoy-demo-tls-validation.yaml
43
44
45
46
47
48
49
50
51
52
53
                port_value: 443
    transport_socket:
      name: envoy.transport_sockets.tls
      typed_config:
        "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext
        common_tls_context:
          validation_context:
            trusted_ca:
              filename: certs/cacert.pem
            match_subject_alt_names:
            - exact: proxy-postgres-backend.example.com
Copy to clipboard

You can also ensure that the “Subject Alternative Names” for the cerficate match.

This is commonly used by web certificates (X.509) to identify the domain or domains that a certificate is valid for.

envoy-demo-tls-validation.yaml
43
44
45
46
47
48
49
50
51
52
53
                port_value: 443
    transport_socket:
      name: envoy.transport_sockets.tls
      typed_config:
        "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext
        common_tls_context:
          validation_context:
            trusted_ca:
              filename: certs/cacert.pem
            match_subject_alt_names:
            - exact: proxy-postgres-backend.example.com
Copy to clipboard

Note

If the “Subject Alternative Names” for a certificate are for a wildcard domain, eg *.example.com, this is what you should use when matching with match_subject_alt_names.

Note

See here to view all of the possible configurations for certificate validation.

Use mutual TLS (mTLS) to enforce client certificate authentication

With mutual TLS (mTLS), Envoy also provides a way to authenticate connecting clients.

At a minimum you will need to set require_client_certificate and specify a mutually trusted certificate authority:

envoy-demo-tls-client-auth.yaml
27
28
29
30
31
32
33
34
35
36
37
38
39
                  cluster: service_envoyproxy_io
      transport_socket:
        name: envoy.transport_sockets.tls
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext
          require_client_certificate: true
          common_tls_context:
            validation_context:
              trusted_ca:
                filename: certs/cacert.pem
              match_subject_alt_names:
              - exact: proxy-postgres-frontend.example.com
            tls_certificates:
Copy to clipboard

You can further restrict the authentication of connecting clients by specifying the allowed “Subject Alternative Names” in match_subject_alt_names, similar to validating upstream certificates described above.

envoy-demo-tls-client-auth.yaml
27
28
29
30
31
32
33
34
35
36
37
38
39
                  cluster: service_envoyproxy_io
      transport_socket:
        name: envoy.transport_sockets.tls
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext
          require_client_certificate: true
          common_tls_context:
            validation_context:
              trusted_ca:
                filename: certs/cacert.pem
              match_subject_alt_names:
              - exact: proxy-postgres-frontend.example.com
            tls_certificates:
Copy to clipboard

Note

See here to view all of the possible configurations for certificate validation.

Use mutual TLS (mTLS) to connect with client certificates

When connecting to an upstream with client certificates you can set them as follows:

envoy-demo-tls-client-auth.yaml
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
  clusters:
  - name: service_envoyproxy_io
    connect_timeout: 30s
    type: LOGICAL_DNS
    # Comment out the following line to test on v6 networks
    dns_lookup_family: V4_ONLY
    load_assignment:
      cluster_name: service_envoyproxy_io
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: www.envoyproxy.io
                port_value: 443
    transport_socket:
      name: envoy.transport_sockets.tls
      typed_config:
        "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext
        common_tls_context:
          tls_certificates:
          - certificate_chain:
              filename: certs/clientcert.pem
            private_key:
              filename: certs/clientkey.pem
Copy to clipboard

Provide multiple TLS domains at the same IP address with SNI

SNI is an extension to the TLS protocol which allows multiple domains served from the same IP address to be secured with TLS.

To secure specific domains on a listening connection with SNI, you should set the filter_chain_match of the listener:

envoy-demo-tls-sni.yaml
27
28
29
30
31
32
33
34
35
                  cluster: service_envoyproxy_io
      filter_chain_match:
        server_names:
        - my-service-name.example.com
      transport_socket:
        name: envoy.transport_sockets.tls
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext
          common_tls_context:
Copy to clipboard

See here for more info about creating multiple endpoints with SNI

Connect to an endpoint with SNI

When connecting to a TLS endpoint that uses SNI you should set sni in the configuration of the UpstreamTLSContext.

This will usually be the DNS name of the service you are connecting to.

envoy-demo-tls-sni.yaml
56
57
58
59
60
61
                port_value: 443
    transport_socket:
      name: envoy.transport_sockets.tls
      typed_config:
        "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext
        sni: www.envoyproxy.io
Copy to clipboard

When connecting to an Envoy endpoint that is protected by SNI, this must match one of the server_names set in the endpoint’s filter_chain_match, as described above.