From 53f12c02bed84ad69003331aeebcf52e6a5e921f Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Wed, 22 Sep 2021 19:53:45 -0400 Subject: [PATCH 1/3] [DOCS] Document default security in alpha2 --- .../configuring-stack-security.asciidoc | 55 +++++++++++++++++-- 1 file changed, 50 insertions(+), 5 deletions(-) diff --git a/x-pack/docs/en/security/configuring-stack-security.asciidoc b/x-pack/docs/en/security/configuring-stack-security.asciidoc index 4abddb79d70fc..b43eb23de1ef6 100644 --- a/x-pack/docs/en/security/configuring-stack-security.asciidoc +++ b/x-pack/docs/en/security/configuring-stack-security.asciidoc @@ -3,18 +3,62 @@ beta::[This functionality is in alpha and is subject to change. The design and code is less mature than official GA features and is being provided as-is with no warranties. Alpha features are not subject to the support SLA of official GA features.] -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`. +When you start {es} for the first time, passwords are automatically generated +for the `elastic` and `kibana_system` users. Use these passwords to securely +connect {es} and {kib}. [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] the `elasticsearch 8.0.0-alpha2` package distribution for your +environment. +* https://www.elastic.co/downloads/kibana#preview-release[Download] the +`kibana 8.0.0-alpha2` package distribution for your environment. [discrete] -=== Start {es} with security enabled +=== Start {es} and {kib} with security enabled +. Start {es}. ++ +[source,bash] +---- +/bin/elasticsearch +---- ++ +Passwords for the for the `elastic` and `kibana_system` users +are output to the terminal. You might need to scroll back a bit to view the +generated passwords. + +. From the directory where you downloaded {kib}, edit `kibana.yml` to uncomment +the `elasticsearch` username and password. Add the generated password for the +`kibana_system` user. ++ +[source,yml] +---- +elasticsearch.username: "kibana_system" +elasticsearch.password: "" +---- + +. Start {kib}. ++ +[source,bash] +---- +bin/kibana +---- + +. Open a browser and navigate to http://localhost:5601/[http://localhost:5601/]. + +. Log in to {kib} as the `elastic` user with the generated password. + +If you need to reset the password for the `elastic` user, run the +<> 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. + + +//// +Close to GA behavior to add later . Before starting {es} for the first time, run the `elasticsearch-security-config` tool from the directory where you downloaded @@ -189,3 +233,4 @@ NOTE: You must create a separate `elasticsearch-ca.pem` security file for the monitoring cluster. Refer to <>. **** +//// \ No newline at end of file From fc146071549707861736e345a0611b7841da0468 Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Tue, 5 Oct 2021 18:54:15 -0400 Subject: [PATCH 2/3] Updating steps for current environment --- .../configuring-stack-security.asciidoc | 246 ++++++------------ 1 file changed, 85 insertions(+), 161 deletions(-) diff --git a/x-pack/docs/en/security/configuring-stack-security.asciidoc b/x-pack/docs/en/security/configuring-stack-security.asciidoc index b43eb23de1ef6..3f4ecdc8045eb 100644 --- a/x-pack/docs/en/security/configuring-stack-security.asciidoc +++ b/x-pack/docs/en/security/configuring-stack-security.asciidoc @@ -3,74 +3,52 @@ beta::[This functionality is in alpha and is subject to change. The design and code is less mature than official GA features and is being provided as-is with no warranties. Alpha features are not subject to the support SLA of official GA features.] +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 Transport Layer Security (TLS) configuration +settings to `elasticsearch.yml`. These certificates allows you to connect a +{kib} to your secured {es} cluster and encrypt internode communication. + When you start {es} for the first time, passwords are automatically generated -for the `elastic` and `kibana_system` users. Use these passwords to securely -connect {es} and {kib}. +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 +<> 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, {kib} 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-alpha2` package distribution for your -environment. -* https://www.elastic.co/downloads/kibana#preview-release[Download] the -`kibana 8.0.0-alpha2` 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} and {kib} with security enabled -. Start {es}. -+ -[source,bash] ----- -/bin/elasticsearch ----- -+ -Passwords for the for the `elastic` and `kibana_system` users -are output to the terminal. You might need to scroll back a bit to view the -generated passwords. - -. From the directory where you downloaded {kib}, edit `kibana.yml` to uncomment -the `elasticsearch` username and password. Add the generated password for the -`kibana_system` user. -+ -[source,yml] ----- -elasticsearch.username: "kibana_system" -elasticsearch.password: "" ----- - -. Start {kib}. -+ -[source,bash] ----- -bin/kibana ----- - -. Open a browser and navigate to http://localhost:5601/[http://localhost:5601/]. - -. Log in to {kib} as the `elastic` user with the generated password. - -If you need to reset the password for the `elastic` user, run the -<> 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. - - -//// -Close to GA behavior to add later - +[[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_`: +certificates and keys in `config/tls_auto_config_initial_node_`: + -- `http_ca.crt`:: @@ -84,45 +62,33 @@ 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 -<> 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. You might need +to scroll back a bit to view the passwords. + [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. +Copy the generated passwords and save them in a secure location. The passwords +are shown only when you start {es} for the first time. + -[source,shell] ----- -./bin/elasticsearch-setup-passwords interactive ----- - -. Save the generated passwords. You'll need them to add the built-in user to -{kib}. -+ -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 -<> tool. +NOTE: If you need to reset the password for the `elastic` user, run the +<> 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: +. 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_/http_ca.crt \ +curl --cacert config/tls_auto_config_initial_node_/http_ca.crt \ -u elastic https://localhost:9200 ---- // NOTCONSOLE @@ -130,107 +96,65 @@ curl --cacert config/auto_config_on_/http_ca.crt \ `--cacert`:: Path to the generated `http_ca.crt` certificate for the HTTP layer. -*Next*: <> - -[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: -+ -[source,yaml] ----- -elasticsearch.username: "kibana_system" ----- -+ -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: - - a. Create the {kib} keystore: +. Open another terminal, navigate to the directory where you installed {es}, and +run the <> tool +to generate an enrollment token for {kib}. + [source,shell] ---- -./bin/kibana-keystore create +bin/elasticsearch-create-enrollment-token -s kibana ---- ++ +Copy the enrollment token, which you'll use to enroll {kib} with your {es} +cluster. - b. Add the password for the `kibana_system` user to the {kib} keystore: +. From the directory where you installed {kib}, start {kib} in interactive mode. + [source,shell] ---- -./bin/kibana-keystore add elasticsearch.password +bin/kibana --interactiveSetup.enabled=true ---- + -When prompted, enter the password for the `kibana_system` user. +This command generates a unique link to enroll your {kib} instance with {es}. -. Restart {kib}. For example, if you installed {kib} with a `.tar.gz` package, run the following command from the {kib} directory: -+ -[source,shell] ----- -./bin/kibana ----- +. In your terminal, click the link to open {kib} in your browser. -. 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. +. In your browser, paste the enrollment token that you copied previously and +click the button to connect your {kib} instance with {es}. -*Next*: <> +. 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]. [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_`. -Use this file to configure {kib} to trust the {es} CA for the HTTP layer. - -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. +[[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 +<> tool +to generate an enrollment token for your additional nodes. + -[source,yaml] +[source,shell] ---- -elasticsearch.ssl.certificateAuthorities: $KBN_PATH_CONF/http_ca.crt +bin/elasticsearch-create-enrollment-token -s node ---- ++ +Copy the enrollment token, which you'll use to enroll additional nodes with +your {es} cluster. -3. Add the following line to specify the HTTPS URL for your {es} -cluster. +. 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,yaml] +[source,shell] ---- -elasticsearch.hosts: https://.com:9200 +bin/elasticsearch-enroll-node --enrollment token ---- -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 -<>. -**** -//// \ No newline at end of file +. Start your new node, which {es} automatically enrolls into the existing +cluster. + +=== What's next? +Congrats! 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, you +can <>. From c0692e2a64cfe15ffb05e0c81717a878479e3a17 Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Wed, 6 Oct 2021 14:47:24 -0400 Subject: [PATCH 3/3] Edits, updates, and rewrites --- .../configuring-stack-security.asciidoc | 56 +++++++++++-------- x-pack/docs/en/security/index.asciidoc | 22 +++++--- 2 files changed, 47 insertions(+), 31 deletions(-) diff --git a/x-pack/docs/en/security/configuring-stack-security.asciidoc b/x-pack/docs/en/security/configuring-stack-security.asciidoc index 3f4ecdc8045eb..02c2aa99cf8c2 100644 --- a/x-pack/docs/en/security/configuring-stack-security.asciidoc +++ b/x-pack/docs/en/security/configuring-stack-security.asciidoc @@ -6,23 +6,22 @@ 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 Transport Layer Security (TLS) configuration -settings to `elasticsearch.yml`. These certificates allows you to connect a -{kib} to your secured {es} cluster and encrypt internode communication. +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 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 -<> tool to +<> 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, {kib} 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 +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. @@ -66,15 +65,16 @@ Keystore that contains the key and certificate for the transport layer for all t [[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. You might need -to scroll back a bit to view the passwords. +`kibana_system` users are generated and output to the terminal. + [source,shell] ---- bin/elasticsearch ---- + -Copy the generated passwords and save them in a secure location. The passwords +TIP: You might need to scroll back a bit in the terminal to view the passwords. + +. 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: If you need to reset the password for the `elastic` user, run the @@ -83,20 +83,22 @@ 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. -. Verify that you can connect to your {es} cluster by making an authenticated -call. 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/tls_auto_config_initial_node_/http_ca.crt \ --u elastic https://localhost:9200 +-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. -. Open another terminal, navigate to the directory where you installed {es}, and +. In your new terminal, navigate to the directory where you installed {es}, and run the <> tool to generate an enrollment token for {kib}. + @@ -117,13 +119,13 @@ bin/kibana --interactiveSetup.enabled=true + This command generates a unique link to enroll your {kib} instance with {es}. -. In your terminal, click the link to open {kib} in your browser. + .. In your terminal, click the generated link to open {kib} in your browser. -. In your browser, paste the enrollment token that you copied previously and -click the button to connect your {kib} instance with {es}. + .. 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. Use this superuser account to -{kibana-ref}/tutorial-secure-access-to-kibana.html[manage spaces, create new users, and assign roles]. + .. Log in to {kib} as the `elastic` user with the password that was generated +when you started {es}. [discrete] [[stack-enroll-nodes]] @@ -150,11 +152,19 @@ your {es} cluster. bin/elasticsearch-enroll-node --enrollment token ---- -. Start your new node, which {es} automatically enrolls into the existing +. Repeat the previous step for any additional nodes that you want to enroll. + +. Start your new nodes, which {es} automatically enrolls into the existing cluster. ++ +[source,shell] +---- +bin/elasticsearch +---- +[discrete] === What's next? -Congrats! You've successfully started the {stack} with security enabled. {es} +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, you +is encrypted. If you want to enable HTTPS for web traffic, you can <>. diff --git a/x-pack/docs/en/security/index.asciidoc b/x-pack/docs/en/security/index.asciidoc index d857eee896738..56e48abaad2cc 100644 --- a/x-pack/docs/en/security/index.asciidoc +++ b/x-pack/docs/en/security/index.asciidoc @@ -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 <>. -<> or -<> 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 +<> 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}. + +If you prefer to manage security on your own, you can +<> 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: