//////////////////////////////////////////////////////////////////////////
//// This content is shared by all Elastic Beats. Make sure you keep the
//// descriptions here generic enough to work for all Beats that include
//// this file. When using cross references, make sure that the cross
//// references resolve correctly for any files that include this one.
//// Use the appropriate variables defined in the index.asciidoc file to
//// resolve Beat names: beatname_uc and beatname_lc.
//// Use the following include to pull this content into a doc file:
//// include::../../libbeat/docs/https.asciidoc[]
//// This content is structured to be included as a whole file.
//////////////////////////////////////////////////////////////////////////

[role="xpack"]
[[securing-communication-elasticsearch]]
== Secure communication with Elasticsearch

When sending data to a secured cluster through the `elasticsearch`
output, {beatname_uc} can use any of the following authentication methods:

* Basic authentication credentials (username and password).
* Token-based API authentication.
* A client certificate.

Authentication is specified in the {beatname_uc} configuration file:

* To use *basic authentication*, specify the `username` and `password` settings under `output.elasticsearch`.
For example:
+
--
["source","yaml",subs="attributes,callouts"]
----------------------------------------------------------------------
output.elasticsearch:
  hosts: ["https://myEShost:9200"]
  username: "{beat_default_index_prefix}_writer" <1>
  password: "{pwd}" <2>
----------------------------------------------------------------------
<1> This user needs the privileges required to publish events to {es}.
To create a user like this, see <<privileges-to-publish-events>>.
<2> This example shows a hard-coded password, but you should store sensitive
values
ifndef::serverless[]
in the <<keystore,secrets keystore>>.
endif::[]
ifdef::serverless[]
in environment variables.
endif::[]
--

* To use token-based *API key authentication*, specify the `api_key` under `output.elasticsearch`.
For example:
+
--
["source","yaml",subs="attributes,callouts"]
----------------------------------------------------------------------
output.elasticsearch:
  hosts: ["https://myEShost:9200"]
  api_key: "ZCV7VnwBgnX0T19fN8Qe:KnR6yE41RrSowb0kQ0HWoA" <1>
----------------------------------------------------------------------
<1> This API key must have the privileges required to publish events to {es}.
To create an API key like this, see <<beats-api-keys>>.
--

[[beats-tls]]
* To use *Public Key Infrastructure (PKI) certificates* to authenticate users,
specify the `certificate` and `key` settings under `output.elasticsearch`.
For example:
+
--
["source","yaml",subs="attributes,callouts"]
----------------------------------------------------------------------
output.elasticsearch:
  hosts: ["https://myEShost:9200"]
  ssl.certificate: "/etc/pki/client/cert.pem" <1>
  ssl.key: "/etc/pki/client/cert.key" <2>
----------------------------------------------------------------------
<1> The path to the certificate for SSL client authentication
<2> The client certificate key
--
+
These settings assume that the
distinguished name (DN) in the certificate is mapped to the appropriate roles in
the `role_mapping.yml` file on each node in the {es} cluster. For more
information, see {ref}/mapping-roles.html#mapping-roles-file[Using role
mapping files].
+
By default, {beatname_uc} uses the list of trusted certificate authorities (CA) from the
operating system where {beatname_uc} is running. If the certificate authority that signed your node certificates
is not in the host system's trusted certificate authorities list, you need
to add the path to the `.pem` file that contains your CA's certificate to the
{beatname_uc} configuration. This will configure {beatname_uc} to use a specific list of
CA certificates instead of the default list from the OS.
+
Here is an example configuration:
+
--
["source","yaml",subs="attributes,callouts"]
----------------------------------------------------------------------
output.elasticsearch:
  hosts: ["https://myEShost:9200"]
  ssl.certificate_authorities: <1>
    - /etc/pki/my_root_ca.pem
    - /etc/pki/my_other_ca.pem
  ssl.certificate: "/etc/pki/client.pem" <2>
  ssl.key: "/etc/pki/key.pem" <3>
----------------------------------------------------------------------
<1> Specify the path to the local `.pem` file that contains your Certificate
Authority's certificate. This is needed if you use your own CA to sign your node certificates.
<2> The path to the certificate for SSL client authentication
<3> The client certificate key
--
+
NOTE: For any given connection, the SSL/TLS certificates must have a subject
that matches the value specified for `hosts`, or the SSL handshake fails.
For example, if you specify `hosts: ["foobar:9200"]`, the certificate MUST
include `foobar` in the subject (`CN=foobar`) or as a subject alternative name
(SAN). Make sure the hostname resolves to the correct IP address. If no DNS is available, then
you can associate the IP address with your hostname in `/etc/hosts`
(on Unix) or `C:\Windows\System32\drivers\etc\hosts` (on Windows).

ifndef::no_dashboards[]
[role="xpack"]
[float]
[[securing-communication-kibana]]
=== Secure communication with the Kibana endpoint

If you've configured the <<setup-kibana-endpoint,{kib} endpoint>>,
you can also specify credentials for authenticating with {kib} under `kibana.setup`.
If no credentials are specified, Kibana will use the configured authentication method
in the Elasticsearch output.

For example, specify a unique username and password to connect to Kibana like this:

--
["source","yaml",subs="attributes,callouts"]
----
setup.kibana:
  host: "mykibanahost:5601"
  username: "{beat_default_index_prefix}_kib_setup" <1>
  password: "{pwd}" <2>
----
<1> This user needs privileges required to set up dashboards. To create a user like this,
see <<privileges-to-setup-beats>>.
<2> This example shows a hard-coded password, but you should store sensitive
values
ifndef::serverless[]
in the <<keystore,secrets keystore>>.
endif::[]
ifdef::serverless[]
in environment variables.
endif::[]
endif::no_dashboards[]
--

[role="xpack"]
[float]
[[securing-communication-learn-more]]
=== Learn more about secure communication

More information on sending data to a secured cluster is available in the configuration reference:

* <<elasticsearch-output>>
* <<configuration-ssl>>
ifndef::no_dashboards[]
* <<setup-kibana-endpoint>>
endif::no_dashboards[]
