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.
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
|
Connecting to an “upstream” TLS
service is conversely done by adding an
UpstreamTLSContext
to the transport_socket of a
cluster.
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
|
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:
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
|
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.
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
|
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 mututal 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:
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:
|
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.
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:
|
Note
See here to view all of the possible configurations for certificate validation.
Use mututal TLS
(mTLS
) to connect with client certificates¶
When connecting to an upstream with client certificates you can set them as follows:
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
|
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:
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:
|
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.
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
|
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.