Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[DOCS] Document default security in alpha2 #78227

Merged
merged 4 commits into from
Oct 7, 2021
Merged

[DOCS] Document default security in alpha2 #78227

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
53f12c0
[DOCS] Document default security in alpha2
Sep 22, 2021
fc14607
Updating steps for current environment
Oct 5, 2021
a45e47c
Merge branch 'master' into docs__alpha2-security-on
elasticmachine Oct 6, 2021
c0692e2
Edits, updates, and rewrites
Oct 6, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
201 changes: 90 additions & 111 deletions x-pack/docs/en/security/configuring-stack-security.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,28 +5,49 @@ beta::[This functionality is in alpha and is subject to change. The design and c

Before you start {es} for the first time, run the `elasticsearch-security-config`
tool. This tool generates certificates and keys for the transport and HTTP
layers of {es}, and writes the TLS configuration settings to `elasticsearch.yml`.
layers of {es}, and writes the Transport Layer Security (TLS) configuration
settings to `elasticsearch.yml`. These certificates allow you to connect a
{kib} instance to your secured {es} cluster and encrypt internode communication.

When you start {es} for the first time, passwords are automatically generated
lockewritesdocs marked this conversation as resolved.
Show resolved Hide resolved
for the `elastic` and `kibana_system` users. Tools are available to reset these
passwords if you misplace them or need to rotate passwords.

You can then use the
<<create-enrollment-token,`elasticsearch-create-enrollment-token`>> tool to
generate separate enrollment tokens for connecting a {kib} instance to your
secured {es} cluster and enrolling additional nodes.

When you complete the enrollment process for {kib}, it applies the security
settings from your {es} cluster, authenticates to {es} with the `kibana_system`
user, and writes the security configuration to `kibana.yml`. A security
certificate is generated in the {kib} configuration directory. This
file establishes trust between {kib} and the {es} Certificate Authority (CA) for
the HTTP layer.

[discrete]
=== Prerequisites

https://www.elastic.co/downloads/elasticsearch#preview-release[Download] the `elasticsearch 8.0.0-alpha1` package distribution for your
* https://www.elastic.co/downloads/elasticsearch#preview-release[Download] and
unpack the `elasticsearch 8.0.0-alpha2` package distribution for your
environment.
* https://www.elastic.co/downloads/kibana#preview-release[Download] and unpack
the `kibana 8.0.0-alpha2` package distribution for your environment.

[discrete]
=== Start {es} with security enabled

[[stack-generate-certificates]]
=== Generate security certificates
. Before starting {es} for the first time, run the
`elasticsearch-security-config` tool from the directory where you downloaded
the {es} package distribution:
+
[source,shell]
----
./bin/elasticsearch-security-config
bin/elasticsearch-security-config
----
+
The `elasticsearch-security-config` tool generates the following security
certificates and keys in `config/auto_config_on_<timestamp>`:
certificates and keys in `config/tls_auto_config_initial_node_<timestamp>`:
+
--
`http_ca.crt`::
Expand All @@ -40,152 +61,110 @@ Keystore that contains the key and certificate for the HTTP layer for this node.
Keystore that contains the key and certificate for the transport layer for all the nodes in your cluster.
--

. Start {es}.
+
[source,shell]
----
./bin/elasticsearch
----

. In another terminal window, run the
<<setup-passwords,`elasticsearch-setup-passwords`>> utility from the directory
where you downloaded the {es} package distribution:
[discrete]
[[stack-start-with-security]]
=== Start {es} and enroll {kib} with security enabled
. From the installation directory, start {es}. Passwords for the `elastic` and
`kibana_system` users are generated and output to the terminal.
+
[source,shell]
----
./bin/elasticsearch-setup-passwords auto
bin/elasticsearch
----
+
If you want to use your own passwords, run the command with the
`interactive` parameter instead of the `auto` parameter. Using this mode
steps you through password configuration for all of the built-in users.
+
[source,shell]
----
./bin/elasticsearch-setup-passwords interactive
----
TIP: You might need to scroll back a bit in the terminal to view the passwords.

. Save the generated passwords. You'll need them to add the built-in user to
{kib}.
. Copy the generated passwords and save them in a secure location. The passwords
are shown only when you start {es} for the first time.
+
NOTE: After you set a password for the `elastic` user, you cannot run the
`elasticsearch-setup-passwords` command a second time. If you forgot the
password for the `elastic` user or want to change it, use the
<<reset-elastic-password,`elasticsearch-reset-elastic-password`>> tool.
NOTE: If you need to reset the password for the `elastic` user, run the
<<reset-elastic-password,`elasticsearch-reset-elastic-password`>> tool. To
reset the password for the `kibana_system` user, run the
`elasticsearch-reset-kibana-system-password` tool. Both of these tools are
available in the {es} `/bin` directory.

. Make an authenticated call to your {es} cluster and enter the password for
the `elastic` user when prompted:
. Open a new terminal and verify that you can connect to your {es} cluster by
making an authenticated call. Enter the password for the `elastic` user when
prompted:
+
[source,shell]
----
curl --cacert config/auto_config_on_<timestamp>/http_ca.crt \
-u elastic https://localhost:9200
curl --cacert config/tls_auto_config_initial_node_<timestamp>/http_ca.crt \
-u elastic https://localhost:9200 <1>
----
// NOTCONSOLE
<1> Ensure that you use `https` in your call, or the request will fail.
+
`--cacert`::
Path to the generated `http_ca.crt` certificate for the HTTP layer.

*Next*: <<add-kib-user,Configure {kib} to connect to {es} with a password>>

[discrete]
[[add-kib-user]]
=== Configure {kib} to connect to {es} with a password

With security enabled, users must log in to {kib} with a valid username and
password.

You'll configure {kib} to use the built-in `kibana_system` user and the password
that you created earlier. {kib} performs some background tasks that require use
of the `kibana_system` user.

This account is not meant for individual users and does not have permission to
log in to {kib} from a browser. Instead, you'll log in to {kib} as the `elastic`
superuser.

. Add the `elasticsearch.username` setting to the `$KBN_PATH_CONF/kibana.yml`
file and set the value to the `kibana_system` user:
. In your new terminal, navigate to the directory where you installed {es}, and
run the <<create-enrollment-token,`elasticsearch-create-enrollment-token`>> tool
to generate an enrollment token for {kib}.
+
[source,yaml]
[source,shell]
----
elasticsearch.username: "kibana_system"
bin/elasticsearch-create-enrollment-token -s kibana
----
+
NOTE: The `$KBN_PATH_CONF` variable is the path for the {kib}
configuration files. If you installed {kib} using archive distributions
(`zip` or `tar.gz`), the variable defaults to `$KBN_HOME/config`. If you used
package distributions (Debian or RPM), the variable defaults to `/etc/kibana`.

. From the directory where you installed {kib}, run the following commands
to create the {kib} keystore and add the secure settings:
Copy the enrollment token, which you'll use to enroll {kib} with your {es}
cluster.

a. Create the {kib} keystore:
. From the directory where you installed {kib}, start {kib} in interactive mode.
+
[source,shell]
----
./bin/kibana-keystore create
bin/kibana --interactiveSetup.enabled=true
----
+
This command generates a unique link to enroll your {kib} instance with {es}.

.. In your terminal, click the generated link to open {kib} in your browser.

.. In your browser, paste the enrollment token that you copied and click the
button to connect your {kib} instance with {es}.

.. Log in to {kib} as the `elastic` user with the password that was generated
when you started {es}.

b. Add the password for the `kibana_system` user to the {kib} keystore:
[discrete]
[[stack-enroll-nodes]]
=== Enroll additional nodes in your cluster
. In a separate terminal from where {es} is running, navigate to the directory
where you installed {es} and run the
<<create-enrollment-token,`elasticsearch-create-enrollment-token`>> tool
to generate an enrollment token for your additional nodes.
+
[source,shell]
----
./bin/kibana-keystore add elasticsearch.password
bin/elasticsearch-create-enrollment-token -s node
----
+
When prompted, enter the password for the `kibana_system` user.
Copy the enrollment token, which you'll use to enroll additional nodes with
your {es} cluster.

. Restart {kib}. For example, if you installed {kib} with a `.tar.gz` package, run the following command from the {kib} directory:
. From the installation directory of your other node, run the
`elasticsearch-enroll-node` tool and pass your enrollment token with the
`--enrollment token` parameter.
+
[source,shell]
----
./bin/kibana
bin/elasticsearch-enroll-node --enrollment token <enrollment-token>
----

. Log in to {kib} as the `elastic` user. Use this superuser account to
{kibana-ref}/tutorial-secure-access-to-kibana.html[manage spaces, create new users, and assign roles]. If you're running {kib} locally, go to `http://localhost:5601` to view the login page.

*Next*: <<encrypt-kibana-with-elasticsearch,Encrypt traffic between {kib} and {es}>>

[discrete]
[[encrypt-kibana-with-elasticsearch]]
=== Encrypt traffic between {kib} and {es}

When you ran the `elasticsearch-security-config` tool, it
created an `http_ca.crt` file in `config/auto_config_on_<timestamp>`.
Use this file to configure {kib} to trust the {es} CA for the HTTP layer.
. Repeat the previous step for any additional nodes that you want to enroll.

1. Copy the `http_ca.crt` file to the {kib} configuration directory, as defined
by the `$KBN_PATH_CONF` path.

2. Open `kibana.yml` and add the following line to specify the location of the
security certificate for the HTTP layer.
+
[source,yaml]
----
elasticsearch.ssl.certificateAuthorities: $KBN_PATH_CONF/http_ca.crt
----

3. Add the following line to specify the HTTPS URL for your {es}
. Start your new nodes, which {es} automatically enrolls into the existing
cluster.
+
[source,yaml]
[source,shell]
----
elasticsearch.hosts: https://<your_elasticsearch_host>.com:9200
bin/elasticsearch
----

4. Restart {kib}. You can now connect to {kib} securely over HTTPS, such as
`https://localhost:5601`.

.Connect to a secure monitoring cluster
****
If the Elastic monitoring features are enabled and you configured a separate
{es} monitoring cluster, you can also configure {kib} to connect to
the monitoring cluster via HTTPS. The steps are the same, but each setting is
prefixed by `monitoring`. For example, `monitoring.ui.elasticsearch.hosts` and
`monitoring.ui.elasticsearch.ssl.truststore.path`.

NOTE: You must create a separate `elasticsearch-ca.pem` security file for the
monitoring cluster. Refer to
<<encrypt-http-communication,Encrypt HTTP client communications for {es}>>.
****
[discrete]
=== What's next?
Congratulations! You've successfully started the {stack} with security enabled. {es}
and {kib} 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-kibana-browser,encrypt traffic between your browser and {kib}>>.
22 changes: 14 additions & 8 deletions x-pack/docs/en/security/index.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,14 +9,20 @@ nodes that form the cluster, plus {ls} instances, {kib} instances, {beats}
agents, and clients all communicating with the cluster. To keep your cluster
safe, adhere to the <<es-security-principles,{es} security principles>>.

<<configuring-stack-security,Start the {stack} with security enabled>> or
<<manually-configure-security,manually configure security>> to
secure {es} clusters and any clients that communicate with your clusters. You
can password protect access to your data as well as enable more advanced
security by configuring Transport Layer Security (TLS). This additional layer
provides confidentiality and integrity protection to your communications with
the {stack}. You can also implement additional security measures, such as
role-based access control, IP filtering, and auditing.
The first principle is to run {es} with security enabled. Configuring security
can be complicated, so we made it easy to
<<configuring-stack-security,start the {stack} with security enabled>> by
default. Run a single configuration command and then start {es} to enable the
{stack} security features. You can then connect a {kib} instance to your
secured {es} cluster and enroll additional nodes. You'll have password
protection, internode communication secured with Transport Layer Security (TLS),
and encrypted connections between {es} and {kib}.
Comment on lines +12 to +19
Copy link
Contributor Author

@lockewritesdocs lockewritesdocs Oct 6, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@bytebilly, I'd like to get your input here. I want to distinguish between running with security on by default versus manually configuring security, including the benefits and what's included. I think that we can merge this for now and iterate on it for Beta and GA.


If you prefer to manage security on your own, you can
<<manually-configure-security,manually configure security>> to secure {es}
clusters and any clients that communicate with your clusters. You can also
implement additional security measures, such as role-based access control, IP
filtering, and auditing.

Enabling security protects {es} clusters by:

Expand Down