.. _start_quick_start_securing: 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 :ref:`JWT `, :ref:`RBAC ` and :ref:`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 :ref:`mTLS ` which provides both encryption and mutual authentication. When using ``TLS``, you are strongly encouraged to :ref:`validate ` all certificates wherever possible. It is your responsibility to ensure the integrity of your certificate chain, and outside the scope of this guide. .. _start_quick_start_securing_contexts: 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 :ref:`DownstreamTLSContext ` in the :ref:`transport_socket ` of a :ref:`listener `. You will also need to provide valid certificates. .. literalinclude:: _include/envoy-demo-tls.yaml :language: yaml :linenos: :lines: 1-37 :emphasize-lines: 28-37 :caption: :download:`envoy-demo-tls.yaml <_include/envoy-demo-tls.yaml>` Connecting to an "upstream" ``TLS`` service is conversely done by adding an :ref:`UpstreamTLSContext ` to the :ref:`transport_socket ` of a :ref:`cluster `. .. literalinclude:: _include/envoy-demo-tls.yaml :language: yaml :linenos: :lineno-start: 39 :lines: 39-56 :emphasize-lines: 15-18 :caption: :download:`envoy-demo-tls.yaml <_include/envoy-demo-tls.yaml>` .. _start_quick_start_securing_validation: 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 :ref:`validation_context ` to specify how Envoy should validate these certificates. Firstly, you can ensure that the certificates are from a mutually trusted certificate authority: .. literalinclude:: _include/envoy-demo-tls-validation.yaml :language: yaml :linenos: :lineno-start: 42 :lines: 42-52 :emphasize-lines: 6-9 :caption: :download:`envoy-demo-tls-validation.yaml <_include/envoy-demo-tls-validation.yaml>` 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. .. literalinclude:: _include/envoy-demo-tls-validation.yaml :language: yaml :linenos: :lineno-start: 42 :lines: 42-52 :emphasize-lines: 6-7, 10-11 :caption: :download:`envoy-demo-tls-validation.yaml <_include/envoy-demo-tls-validation.yaml>` .. 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 :ref:`here ` to view all of the possible configurations for certificate validation. .. _start_quick_start_securing_mtls: 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 :ref:`require_client_certificate ` and specify a mutually trusted certificate authority: .. literalinclude:: _include/envoy-demo-tls-client-auth.yaml :language: yaml :linenos: :lineno-start: 27 :lines: 27-39 :emphasize-lines: 6, 8-10 :caption: :download:`envoy-demo-tls-client-auth.yaml <_include/envoy-demo-tls-client-auth.yaml>` You can further restrict the authentication of connecting clients by specifying the allowed "Subject Alternative Names" in :ref:`match_subject_alt_names `, similar to validating upstream certificates :ref:`described above `. .. literalinclude:: _include/envoy-demo-tls-client-auth.yaml :language: yaml :linenos: :lineno-start: 27 :lines: 27-39 :emphasize-lines: 7, 11-12 :caption: :download:`envoy-demo-tls-client-auth.yaml <_include/envoy-demo-tls-client-auth.yaml>` .. note:: See :ref:`here ` to view all of the possible configurations for certificate validation. .. _start_quick_start_securing_mtls_client: Use mutual ``TLS`` (``mTLS``) to connect with client certificates ------------------------------------------------------------------ When connecting to an upstream with client certificates you can set them as follows: .. literalinclude:: _include/envoy-demo-tls-client-auth.yaml :language: yaml :linenos: :lineno-start: 44 :lines: 44-68 :emphasize-lines: 20-25 :caption: :download:`envoy-demo-tls-client-auth.yaml <_include/envoy-demo-tls-client-auth.yaml>` .. _start_quick_start_securing_sni: 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 :ref:`filter_chain_match ` of the :ref:`listener `: .. literalinclude:: _include/envoy-demo-tls-sni.yaml :language: yaml :linenos: :lineno-start: 27 :lines: 27-35 :emphasize-lines: 2-4 :caption: :download:`envoy-demo-tls-sni.yaml <_include/envoy-demo-tls-sni.yaml>` See here for :ref:`more info about creating multiple endpoints with SNI ` .. _start_quick_start_securing_sni_client: Connect to an endpoint with ``SNI`` ----------------------------------- When connecting to a ``TLS`` endpoint that uses ``SNI`` you should set :ref:`sni ` in the configuration of the :ref:`UpstreamTLSContext `. This will usually be the DNS name of the service you are connecting to. .. literalinclude:: _include/envoy-demo-tls-sni.yaml :language: yaml :linenos: :lineno-start: 55 :lines: 55-60 :emphasize-lines: 6 :caption: :download:`envoy-demo-tls-sni.yaml <_include/envoy-demo-tls-sni.yaml>` When connecting to an Envoy endpoint that is protected by ``SNI``, this must match one of the :ref:`server_names ` set in the endpoint's :ref:`filter_chain_match `, as :ref:`described above `.