diff --git a/docs/en/ingest-management/images/tls-overview-mutual-all.jpg b/docs/en/ingest-management/images/tls-overview-mutual-all.jpg new file mode 100644 index 000000000..88ef37a68 Binary files /dev/null and b/docs/en/ingest-management/images/tls-overview-mutual-all.jpg differ diff --git a/docs/en/ingest-management/images/tls-overview-mutual-fs-agent.png b/docs/en/ingest-management/images/tls-overview-mutual-fs-agent.png new file mode 100644 index 000000000..4d05d5c1f Binary files /dev/null and b/docs/en/ingest-management/images/tls-overview-mutual-fs-agent.png differ diff --git a/docs/en/ingest-management/images/tls-overview-mutual-fs-es.png b/docs/en/ingest-management/images/tls-overview-mutual-fs-es.png new file mode 100644 index 000000000..0cd7746bf Binary files /dev/null and b/docs/en/ingest-management/images/tls-overview-mutual-fs-es.png differ diff --git a/docs/en/ingest-management/images/tls-overview-oneway-all.jpg b/docs/en/ingest-management/images/tls-overview-oneway-all.jpg new file mode 100644 index 000000000..e65f24add Binary files /dev/null and b/docs/en/ingest-management/images/tls-overview-oneway-all.jpg differ diff --git a/docs/en/ingest-management/images/tls-overview-oneway-fs-agent.png b/docs/en/ingest-management/images/tls-overview-oneway-fs-agent.png new file mode 100644 index 000000000..7d5326c27 Binary files /dev/null and b/docs/en/ingest-management/images/tls-overview-oneway-fs-agent.png differ diff --git a/docs/en/ingest-management/images/tls-overview-oneway-fs-es.png b/docs/en/ingest-management/images/tls-overview-oneway-fs-es.png new file mode 100644 index 000000000..6b2477384 Binary files /dev/null and b/docs/en/ingest-management/images/tls-overview-oneway-fs-es.png differ diff --git a/docs/en/ingest-management/index.asciidoc b/docs/en/ingest-management/index.asciidoc index 7328e2a55..f85081f37 100644 --- a/docs/en/ingest-management/index.asciidoc +++ b/docs/en/ingest-management/index.asciidoc @@ -99,6 +99,8 @@ include::security/certificates-rotation.asciidoc[leveloffset=+2] include::security/mutual-tls.asciidoc[leveloffset=+2] +include::security/tls-overview.asciidoc[leveloffset=+2] + include::security/logstash-certificates.asciidoc[leveloffset=+2] include::fleet/fleet.asciidoc[leveloffset=+1] diff --git a/docs/en/ingest-management/security/certificates.asciidoc b/docs/en/ingest-management/security/certificates.asciidoc index e2d5bb2d6..30e091875 100644 --- a/docs/en/ingest-management/security/certificates.asciidoc +++ b/docs/en/ingest-management/security/certificates.asciidoc @@ -7,6 +7,9 @@ in the {stack}. For the install settings specific to mutual TLS, as opposed to one-way TLS, refer to <>. +For a summary of flow by which TLS is established between components using +either one-way or mutual TLS, refer to <>. + TIP: Our {ess-product}[hosted {ess}] on {ecloud} provides secure, encrypted connections out of the box! diff --git a/docs/en/ingest-management/security/mutual-tls.asciidoc b/docs/en/ingest-management/security/mutual-tls.asciidoc index f0c26036f..95e7b66a6 100644 --- a/docs/en/ingest-management/security/mutual-tls.asciidoc +++ b/docs/en/ingest-management/security/mutual-tls.asciidoc @@ -3,6 +3,8 @@ Mutual Transport Layer Security (mTLS) provides a higher level of security and trust compared to one-way TLS, where only the server presents a certificate. It ensures that not only the server is who it claims to be, but the client is also authenticated. This is particularly valuable in scenarios where both parties need to establish trust and validate each other's identities, such as in secure API communication, web services, or remote authentication. +For a summary of flow by which TLS is established between components using either one-way or mutual TLS, refer to <>. + * <> * <> * <> diff --git a/docs/en/ingest-management/security/tls-overview.asciidoc b/docs/en/ingest-management/security/tls-overview.asciidoc new file mode 100644 index 000000000..c79d1ff67 --- /dev/null +++ b/docs/en/ingest-management/security/tls-overview.asciidoc @@ -0,0 +1,82 @@ +[[tls-overview]] += One-way and mutual TLS certifications flow + +This page provides an overview of the relationship between the various certificates and certificate authorities (CAs) that you configure for {fleet-server} and {agent}, using the `elastic-agent install` TLS command options. + +* <> +* <> + +[discrete] +[[one-way-tls-connection]] +== Simple one-way TLS connection + +The following `elastic-agent install` command configures a {fleet-server} with the required certificates and certificate authorities to enable one-way TLS connections between the components involved: + +[source,shell] +---- +elastic-agent install --url=https://your-fleet-server.elastic.co:443 \ +--certificate-authorities=/path/to/fleet-ca \ +--fleet-server-es=https://es.elastic.com:443 \ +--fleet-server-es-ca=/path/to/es-ca \ +--fleet-server-cert=/path/to/fleet-cert \ +--fleet-server-cert-key=/path/to/fleet-cert-key \ +--fleet-server-service-token=FLEET-SERVER-SERVICE-TOKEN \ +--fleet-server-policy=FLEET-SERVER-POLICY-ID \ +--fleet-server-port=8220 +---- + +{agent} is configured with `fleet-ca` as the certificate authority that it needs to validate certificates from {fleet-server}. + +During the TLS connection setup, {fleet-server} presents its certificate `fleet-cert` to the agent and the agent (as a client) uses `fleet-ca` to validate the presented certificate. + +image::images/tls-overview-oneway-fs-agent.png[Diagram of one-way TLS connection between Fleet Server and Elastic Agent] + +{fleet-server} also establishes a secure connection to an {es} cluster. In this case, {fleet-server} is configured with the certificate authority from the {es} `es-ca`. {es} presents its certificate, `es-cert`, and {fleet-server} validates the presented certificate using the certificate authority `es-ca`. + +image::images/tls-overview-oneway-fs-es.png[Diagram of one-way TLS connection between Fleet Server and Elasticsearch] + +[discrete] +=== Relationship between components in a one-way TLS connection + +image::images/tls-overview-oneway-all.jpg[Diagram of one-way TLS connection between components] + +[discrete] +[[mutual-tls-connection]] +== Mutual TLS connection + +The following `elastic-agent install` command configures a {fleet-server} with the required certificates and certificate authorities to enable mutual TLS connections between the components involved: + +[source,shell] +---- +elastic-agent install --url=https://your-fleet-server.elastic.co:443 \ +--certificate-authorities=/path/to/fleet-ca,/path/to/agent-ca \ +--elastic-agent-cert=/path/to/agent-cert \ +--elastic-agent-cert-key=/path/to/agent-cert-key \ +--fleet-server-es=https://es.elastic.com:443 \ +--fleet-server-es-ca=/path/to/es-ca \ +--fleet-server-es-cert=/path/to/fleet-es-cert \ +--fleet-server-es-cert-key=/path/to/fleet-es-cert-key \ +--fleet-server-cert=/path/to/fleet-cert \ +--fleet-server-cert-key=/path/to/fleet-cert-key \ +--fleet-server-client-auth=required \ +--fleet-server-service-token=FLEET-SERVER-SERVICE-TOKEN \ +--fleet-server-policy=FLEET-SERVER-POLICY-ID \ +--fleet-server-port=8220 +---- + +As with the <>, {agent} is configured with `fleet-ca` as the certificate authority that it needs to validate certificates from the {fleet-server}. {fleet-server} presents its certificate `fleet-cert` to the agent and the agent (as a client) uses `fleet-ca` to validate the presented certificate. + +To establish a mutual TLS connection, the agent presents its certificate, `agent-cert`, and {fleet-server} validates this certificate using the `agent-ca` that it has stored in memory. + +image::images/tls-overview-mutual-fs-agent.png[Diagram of mutual TLS connection between Fleet Server and Elastic Agent] + +{fleet-server} can also establish a mutual TLS connection to the {es} cluster. In this case, {fleet-server} is configured with the certificate authority from the {es} `es-ca` and uses this to validate the certificate `es-cert` presented to it by {es}. + +image::images/tls-overview-mutual-fs-es.png[Diagram of mutual TLS connection between Fleet Server and Elasticsearch] + +Note that you can also configure mutual TLS for {fleet-server} and {agent} <>. + +[discrete] +=== Relationship between components in a mutual TLS connection + +image::images/tls-overview-mutual-all.jpg[Diagram of mutual TLS connection between components] \ No newline at end of file