Docs
Elasticsearch Guide [8.1] » Secure the Elastic Stack » Start the Elastic Stack with security enabled
« Elasticsearch security principles Manually configure security »

Start the Elastic Stack with security enabled

When you start Elasticsearch for the first time, the following security configuration occurs automatically:

  • Certificates and keys for TLS are generated for the transport and HTTP layers.
  • The TLS configuration settings are written to elasticsearch.yml.
  • A password is generated for the elastic user.
  • An enrollment token is generated for Kibana.

You can then start Kibana and enter the enrollment token, which is valid for 30 minutes. This token automatically applies the security settings from your Elasticsearch cluster, authenticates to Elasticsearch with the built-in kibana service account, and writes the security configuration to kibana.yml.

Prerequisites

  • Download and unpack the elasticsearch package distribution for your environment.
  • Download and unpack the kibana package distribution for your environment.

Start Elasticsearch and enroll Kibana with security enabled

  1. From the installation directory, start Elasticsearch. A password is generated for the elastic user and output to the terminal, plus an enrollment token for enrolling Kibana.

    bin/elasticsearch

    You might need to scroll back a bit in the terminal to view the password and enrollment token.

  2. Copy the generated password and enrollment token and save them in a secure location. These values are shown only when you start Elasticsearch for the first time.

    If you need to reset the password for the elastic user or other built-in users, run the elasticsearch-reset-password tool. To generate new enrollment tokens for Kibana or Elasticsearch nodes, run the elasticsearch-create-enrollment-token tool. These tools are available in the Elasticsearch bin directory.

  3. (Optional) Open a new terminal and verify that you can connect to your Elasticsearch cluster by making an authenticated call. Enter the password for the elastic user when prompted:

    curl --cacert config/certs/http_ca.crt -u elastic https://localhost:9200

  4. From the directory where you installed Kibana, start Kibana.

    bin/kibana

    This command generates a unique link to enroll your Kibana instance with Elasticsearch.

    1. In your terminal, click the generated link to open Kibana in your browser.
    2. In your browser, paste the enrollment token that you copied and click the button to connect your Kibana instance with Elasticsearch.
    3. Log in to Kibana as the elastic user with the password that was generated when you started Elasticsearch.

Enroll additional nodes in your cluster

When Elasticsearch starts for the first time, the security auto-configuration process binds the HTTP layer to both _site_ and _local_, but only binds the transport layer to _local_. This intended behavior ensures that you can start a single-node cluster with security enabled by default without any additional configuration.

Before enrolling a new node, additional actions such as binding to an address other than localhost or satisfying bootstrap checks are typically necessary in production clusters. During that time, an auto-generated enrollment token could expire, which is why enrollment tokens aren’t generated automatically.

Additionally, only nodes on the same host can join the cluster without additional configuration. If you want nodes from another host to join your cluster, you need to set transport.host to a supported value other than _local_ (such as _site_), or an IP address that’s bound to an interface where other hosts can reach it. Refer to transport settings for more information.

To enroll new nodes in your cluster, create an enrollment token with the elasticsearch-create-enrollment-token tool on any existing node in your cluster. You can then start a new node with the --enrollment-token parameter so that it joins an existing cluster.

  1. In a separate terminal from where Elasticsearch is running, navigate to the directory where you installed Elasticsearch and run the elasticsearch-create-enrollment-token tool to generate an enrollment token for your new nodes.

    bin/elasticsearch-create-enrollment-token -s node

    Copy the enrollment token, which you’ll use to enroll new nodes with your Elasticsearch cluster.

  2. From the installation directory of your new node, start Elasticsearch and pass the enrollment token with the --enrollment-token parameter.

    bin/elasticsearch --enrollment-token <enrollment-token>

    Elasticsearch automatically generates certificates and keys in the following directory:

    config/certs
  3. Repeat the previous step for any new nodes that you want to enroll.

Connect clients to Elasticsearch

When you start Elasticsearch for the first time, TLS is configured automatically for the HTTP layer. A CA certificate is generated and stored on disk at $ES_HOME/config/certs/http_ca.crt. The hex-encoded SHA-256 fingerprint of this certificate is also output to the terminal. Any clients that connect to Elasticsearch, such as the Elasticsearch Clients, Beats, standalone Elastic Agents, and Logstash must validate that they trust the certificate that Elasticsearch uses for HTTPS. Fleet Server and Fleet-managed Elastic Agents are automatically configured to trust the CA certificate. Other clients can establish trust by using either the fingerprint of the CA certificate or the CA certificate itself.

If the auto-configuration process already completed, you can still obtain the fingerprint of the security certificate. You can also copy the CA certificate to your machine and configure your client to use it.

Use the CA fingerprint

Copy the fingerprint value that’s output to your terminal when Elasticsearch starts, and configure your client to use this fingerprint to establish trust when it connects to Elasticsearch.

If the auto-configuration process already completed, you can still obtain the fingerprint of the security certificate by running the following command. The path is to the auto-generated CA certificate for the HTTP layer.

openssl x509 -fingerprint -sha256 -in config/certs/http_ca.crt

The command returns the security certificate, including the fingerprint. The issuer should be Elasticsearch security auto-configuration HTTP CA.

issuer= /CN=Elasticsearch security auto-configuration HTTP CA
SHA256 Fingerprint=<fingerprint>

Use the CA certificate

If your library doesn’t support a method of validating the fingerprint, the auto-generated CA certificate is created in the $ES_HOME/config/certs/ directory on each Elasticsearch node. Copy the http_ca.crt file to your machine and configure your client to use this certificate to establish trust when it connects to Elasticsearch.

What’s next?

Congratulations! You’ve successfully started the Elastic Stack with security enabled. Elasticsearch and Kibana are secured with TLS on the HTTP layer, and internode communication is encrypted. If you want to enable HTTPS for web traffic, you can encrypt traffic between your browser and Kibana.

Security certificates and keys

When you install Elasticsearch, the following certificates and keys are generated in the Elasticsearch configuration directory, which are used to connect a Kibana instance to your secured Elasticsearch cluster and to encrypt internode communication. The files are listed here for reference.

http_ca.crt
The CA certificate that is used to sign the certificates for the HTTP layer of this Elasticsearch cluster.
http.p12
Keystore that contains the key and certificate for the HTTP layer for this node.
transport.p12
Keystore that contains the key and certificate for the transport layer for all the nodes in your cluster.

http.p12 and transport.p12 are password-protected PKCS#12 keystores. Elasticsearch stores the passwords for these keystores as secure settings. To retrieve the passwords so that you can inspect or change the keystore contents, use the bin/elasticsearch-keystore tool.

Use the following command to retrieve the password for http.p12:

bin/elasticsearch-keystore show xpack.security.http.ssl.keystore.secure_password

Use the following command to retrieve the password for transport.p12:

bin/elasticsearch-keystore show xpack.security.transport.ssl.keystore.secure_password

Additionally, when you use the enrollment token to connect Kibana to a secured Elasticsearch cluster, the HTTP layer CA certificate is retrieved from Elasticsearch and stored in the Kibana /data directory. This file establishes trust between Kibana and the Elasticsearch Certificate Authority (CA) for the HTTP layer.

« Elasticsearch security principles Manually configure security »