Browse Source

[DOCS] Add minimal security steps back to docs (#88393)

* [DOCS] Add minimal security steps back to docs

* Update instructions to use reset password tool

* Update setting built-in user passwords with the es reset passwords tool

* Revert "Update setting built-in user passwords with the es reset passwords tool"

This reverts commit 51b72fdfdf4923e5d276485724bdcebea16143ad.

* Address review feedback and make clearer distinctions between security configurations
Adam Locke 3 years ago
parent
commit
1441367d0b

+ 0 - 10
docs/reference/redirects.asciidoc

@@ -192,22 +192,12 @@ See <<grok,Grokking grok>>.
 
 // [START] Security redirects
 
-[role="exclude",id="security-minimal-setup"]
-=== Set up minimal security for {es}
-
-Refer to <<manually-configure-security,Manually configure security for the {stack}>>.
-
 [role="exclude",id="get-started-users"]
 ==== Create users
 
 Refer to the <<reset-password,`elasticsearch-reset-password`>> tool for resetting
 passwords of built-in users.
 
-[role="exclude",id="add-built-in-users"]
-==== Configure {kib} to connect to {es} with a password
-
-Refer to <<configuring-stack-security,Start the {stack} with security enabled>>.
-
 [role="exclude",id="encrypting-communications-certificates"]
 === Generate certificates
 

+ 3 - 3
x-pack/docs/en/security/configuring-stack-security.asciidoc

@@ -1,5 +1,5 @@
 [[configuring-stack-security]]
-== Start the Elastic Stack with security enabled
+== Start the {stack} with security enabled automatically
 
 When you start {es} for the first time, the following security configuration
 occurs automatically:
@@ -12,8 +12,8 @@ generated for the transport and HTTP layers.
 
 You can then start {kib} and enter the enrollment token, which is valid for 30
 minutes. This token automatically applies the security settings from your {es}
-cluster, authenticates to {es} with the built-in `kibana` service account, and writes the
-security configuration to `kibana.yml`.
+cluster, authenticates to {es} with the built-in `kibana` service account, and
+writes the security configuration to `kibana.yml`.
 
 NOTE: There are <<stack-skip-auto-configuration,some cases>> where security
 can't be configured automatically because the node startup process detects that

BIN
x-pack/docs/en/security/images/elastic-security-overview.png


+ 9 - 10
x-pack/docs/en/security/index.asciidoc

@@ -11,16 +11,15 @@ safe, adhere to the <<es-security-principles,{es} security principles>>.
 
 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. Just start {es} to enable and configure 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
-<<manually-configure-security,manually configure security>> to secure {es}
-clusters and any clients that communicate with your clusters. You can also
+<<configuring-stack-security,start the {stack} with security enabled and configured>>.
+For any new clusters, just start {es} to automatically enable password protection, 
+secure internode communication with Transport Layer Security (TLS), and encrypt
+connections between {es} and {kib}.
+
+If you have an existing, unsecured cluster (or prefer to manage security on your
+own), you can
+<<manually-configure-security,manually enable and 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.
 

+ 167 - 0
x-pack/docs/en/security/securing-communications/security-minimal-setup.asciidoc

@@ -0,0 +1,167 @@
+[[security-minimal-setup]]
+=== Set up minimal security for {es}
+++++
+<titleabbrev>Set up minimal security</titleabbrev>
+++++
+
+IMPORTANT: You only need to complete the following steps if you're running an 
+existing, unsecured cluster and want to enable the {es} {security-features}.
+
+In {es} 8.0 and later, security is
+<<configuring-stack-security,enabled automatically>> when you start {es} for the 
+first time. 
+
+If you're running an existing {es} cluster where security is disabled, you can 
+manually enable the {es} {security-features} and then create passwords for 
+built-in users. You can add more users later, but using the built-in users 
+simplifies the process of enabling security for your cluster.
+
+include::../security-manual-configuration.asciidoc[tag=minimal-security-note]
+
+==== Enable {es} security features
+
+Enabling the {es} security features provides basic authentication so
+that you can run a local cluster with username and password authentication.
+
+. On *every* node in your cluster, stop both {kib} and {es} if they are running.
+
+. On *every* node in your cluster, add the `xpack.security.enabled` setting to
+the `$ES_PATH_CONF/elasticsearch.yml` file and set the value to `true`:
++
+[source,yaml]
+----
+xpack.security.enabled: true
+----
++
+NOTE: The `$ES_PATH_CONF` variable is the path for the {es}
+configuration files. If you installed {es} using archive distributions
+(`zip` or `tar.gz`), the variable defaults to `$ES_HOME/config`. If you used
+package distributions (Debian or RPM), the variable defaults to `/etc/elasticsearch`.
+
+. If your cluster has a single node, add the `discovery.type` setting in the
+`$ES_PATH_CONF/elasticsearch.yml` file and set the value to `single-node`. This
+setting ensures that your node does not inadvertently connect to other clusters
+that might be running on your network.
++
+[source,yaml]
+----
+discovery.type: single-node
+----
+
+[[security-create-builtin-users]]
+==== Set passwords for built-in users
+
+To communicate with the cluster, you must configure a username for the built-in
+users. Unless you enable anonymous access, all requests that don’t include a
+username and password are rejected.
+
+NOTE: You only need to set passwords for the `elastic` and `kibana_system` users
+when enabling minimal or basic security.
+
+. On *every* node in your cluster, start {es}. For example, if you installed 
+{es} with a `.tar.gz` package, run the following command from the `ES_HOME`
+directory:
++
+[source,shell]
+----
+./bin/elasticsearch
+----
+
+. In another terminal window, set the passwords for the built-in users by
+running the <<reset-password,`elasticsearch-reset-password`>> utility.
++
+IMPORTANT: You can run the `elasticsearch-reset-password` utility
+against any node in your cluster. However, you should only run this utility *one
+time* for the entire cluster.
++
+Using the `auto` parameter
+outputs randomly-generated passwords to the console that you can change later
+if necessary:
++
+[source,shell]
+----
+./bin/elasticsearch-reset-password auto
+----
++
+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-reset-password interactive
+----
+
+. Save the generated passwords. You'll need them to add the built-in user to
+{kib}.
+
+*Next*: <<add-built-in-users,Configure {kib} to connect to {es} with a password>>
+
+[[add-built-in-users]]
+==== Configure {kib} to connect to {es} with a password
+
+When the {es} security features are 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 `KIB_PATH_CONF/kibana.yml`
+file and set the value to the `kibana_system` user:
++
+[source,yaml]
+----
+elasticsearch.username: "kibana_system"
+----
++
+NOTE: The `KIB_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 `KIB_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:
++
+[source,shell]
+----
+./bin/kibana-keystore create
+----
+
+   b. Add the password for the `kibana_system` user to the {kib} keystore:
++
+[source,shell]
+----
+./bin/kibana-keystore add elasticsearch.password
+----
++
+When prompted, enter the password for the `kibana_system` user.
+
+. 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
+----
+
+. 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.
+
+[[minimal-security-whatsnext]]
+==== What's next?
+
+Congratulations! You enabled password protection for your local cluster to
+prevent unauthorized access. You can log in to {kib} securely as the `elastic`
+user and create additional users and roles. If you're running a <<single-node-discovery,single-node cluster>>, then you can stop here.
+
+If your cluster has multiple nodes, then you must configure Transport Layer
+Security (TLS) between nodes. <<dev-vs-prod-mode,Production mode>> clusters
+will not start if you do not enable TLS.
+
+<<security-basic-setup,Set up basic security for the {stack}>> to
+secure all internal communication between nodes in your cluster.

+ 26 - 6
x-pack/docs/en/security/security-manual-configuration.asciidoc

@@ -1,8 +1,5 @@
 [[manually-configure-security]]
 == Manually configure security
-++++
-<titleabbrev>Configure security</titleabbrev>
-++++
 
 Security needs vary depending on whether you're developing locally on your
 laptop or securing all communications in a production environment. Regardless
@@ -11,9 +8,10 @@ incredibly important to protect your data. That's why security is
 <<configuring-stack-security,enabled and configured by default>> in {es} 8.0
 and later.
 
-If you want to use your own Certificate Authority (CA) or would rather manually
-configure security, the following scenarios provide steps for configuring TLS
-on the transport layer, plus securing HTTPS traffic if you want it.
+If you want to enable security on an existing, unsecured cluster, use your own 
+Certificate Authority (CA), or would rather manually configure security, the 
+following scenarios provide steps for configuring TLS on the transport layer,
+plus securing HTTPS traffic if you want it.
 
 If you configure security manually _before_ starting your {es} nodes, the
 auto-configuration process will respect your security configuration. You can
@@ -22,6 +20,26 @@ adjust your TLS configuration at any time, such as
 
 image::images/elastic-security-overview.png[Elastic Security layers]
 
+[discrete]
+[[security-minimal-overview]]
+=== Minimal security ({es} Development)
+
+If you've been working with {es} and want to enable security on your existing,
+unsecured cluster, start here. You'll set passwords for the built-in users to prevent 
+unauthorized access to your local cluster, and also configure password 
+authentication for {kib}.
+
+// tag::minimal-security-note[]
+IMPORTANT: The minimal security scenario is not sufficient for
+<<dev-vs-prod-mode,production mode>> clusters. If your cluster has multiple
+nodes, you must enable minimal security and then
+<<security-basic-setup,configure Transport Layer Security (TLS)>> between
+nodes.
+
+// end::minimal-security-note[]
+
+<<security-minimal-setup,Set up minimal security>>
+
 [discrete]
 [[security-basic-overview]]
 === Basic security ({es} + {kib})
@@ -54,6 +72,8 @@ cluster are secure.
 
 <<security-basic-setup-https,Set up basic security plus HTTPS traffic>>
 
+include::securing-communications/security-minimal-setup.asciidoc[]
+
 include::securing-communications/security-basic-setup.asciidoc[]
 
 include::securing-communications/security-basic-setup-https.asciidoc[]