Update security docs (#87215) (#87334)

jportner · web-flow · commit 497383da91cd · 2021-01-05T12:53:34.000-05:00
diff --git a/docs/management/managing-saved-objects.asciidoc b/docs/management/managing-saved-objects.asciidoc
@@ -60,8 +60,8 @@ You have two options for exporting saved objects.
 * Select the checkboxes of objects that you want to export, and then click *Export*.
 * Click *Export x objects*, and export objects by type.
 
-This action creates an NDJSON with all your saved objects.  By default,
-the NDJSON includes related objects. Exported dashboards include their associated index patterns.
+This action creates an NDJSON with all your saved objects. By default, the NDJSON includes child objects that are related to the saved
+objects. Exported dashboards include their associated index patterns.
 
 [float]
 [role="xpack"]
@@ -73,8 +73,8 @@ and select *Copy to space*. From here, you can select the spaces in which to cop
 You can also select whether to automatically overwrite any conflicts in the target spaces, or
 resolve them manually.
 
-WARNING: The copy operation automatically includes related objects. If you don't want this behavior,
-use the <<spaces-api-copy-saved-objects, copy saved objects to space API>> instead.
+WARNING: The copy operation automatically includes child objects that are related to the saved objects. If you don't want this behavior, use
+the <<spaces-api-copy-saved-objects, copy saved objects to space API>> instead.
 
 
 [float]
diff --git a/docs/user/security/securing-communications/index.asciidoc b/docs/user/security/securing-communications/index.asciidoc
@@ -26,65 +26,65 @@ NOTE: You do not need to enable the {es} {security-features} for this type of en
 When you obtain a server certificate, you must set its subject alternative name (SAN) correctly to ensure that modern web browsers with
 hostname verification will trust it. You can set one or more SANs to the {kib} server's fully-qualified domain name (FQDN), hostname, or IP
 address. When choosing the SAN, you should pick whichever attribute you will be using to connect to {kib} in your browser, which is likely
-the FQDN.
+the FQDN in a production environment.
 
-
-You may choose to generate a certificate signing request (CSR) and private key using the {ref}/certutil.html[`elasticsearch-certutil`] tool.
+You may choose to generate a signed certificate and private key using the {ref}/certutil.html[`elasticsearch-certutil`] tool.
 For example:
 
 [source,sh]
 --------------------------------------------------------------------------------
-bin/elasticsearch-certutil csr -name kibana-server -dns some-website.com,www.some-website.com
+bin/elasticsearch-certutil cert -name kibana-server -dns localhost,127.0.0.1
 --------------------------------------------------------------------------------
 
-This will produce a ZIP archive named `kibana-server.zip`. Extract that archive to obtain the PEM-formatted CSR (`kibana-server.csr`) and
-unencrypted private key (`kibana-server.key`). In this example, the CSR has a common name (CN) of `kibana-server`, a SAN of
-`some-website.com`, and another SAN of `www.some-website.com`.
+This will produce a PKCS#12 file named `kibana-server.p12`, which contains the server certificate and private key.
 
-NOTE: You will need to use a certificate authority (CA) to sign your CSR to obtain your server certificate. This certificate's signature
-will be verified by web browsers that are configured to trust the CA.
+NOTE: In this example, the server certificate is signed by a locally-generated certificate authority (CA). This is not suitable for a
+production environment, and it will result in warnings in your web browser until you configure your browser to trust the certificate. Steps
+to configure certificate trust vary depending upon your browser and operating system. If you want to obtain a server certificate for a
+production environment, you can instead generate a certificate signing request (CSR) with `elasticsearch-certutil` using
+{ref}/certutil.html#certutil-csr[CSR mode].
 --
 
 . Configure {kib} to access the server certificate and private key.
 
-.. If your server certificate and private key are in PEM format:
+.. If your server certificate and private key are contained in a PKCS#12 file:
 +
 --
-Specify your server certificate and private key in `kibana.yml`:
+Specify your PKCS#12 file in `kibana.yml`:
 
 [source,yaml]
 --------------------------------------------------------------------------------
-server.ssl.certificate: "/path/to/kibana-server.crt"
-server.ssl.key: "/path/to/kibana-server.key"
+server.ssl.keystore.path: "/path/to/kibana-server.p12"
 --------------------------------------------------------------------------------
 
-If your private key is encrypted, add the decryption password to your <<secure-settings,{kib} keystore>>:
+If your PKCS#12 file is encrypted, add the decryption password to your <<secure-settings,{kib} keystore>>:
 
 [source,yaml]
 --------------------------------------------------------------------------------
-bin/kibana-keystore add server.ssl.keyPassphrase
+bin/kibana-keystore add server.ssl.keystore.password
 --------------------------------------------------------------------------------
+
+NOTE: If you used `elasticsearch-certutil` to generate a PKCS#12 file and you did not specify a password, the file is encrypted, and you
+need to set `server.ssl.keystore.password` to an empty string.
 --
 
-.. Otherwise, if your server certificate and private key are contained in a PKCS#12 file:
+.. Otherwise, if your server certificate and private key are in PEM format:
 +
 --
-Specify your PKCS#12 file in `kibana.yml`:
+Specify your server certificate and private key in `kibana.yml`:
 
 [source,yaml]
 --------------------------------------------------------------------------------
-server.ssl.keystore.path: "/path/to/kibana-server.p12"
+server.ssl.certificate: "/path/to/kibana-server.crt"
+server.ssl.key: "/path/to/kibana-server.key"
 --------------------------------------------------------------------------------
 
-If your PKCS#12 file is encrypted, add the decryption password to your <<secure-settings,{kib} keystore>>:
+If your private key is encrypted, add the decryption password to your <<secure-settings,{kib} keystore>>:
 
 [source,yaml]
 --------------------------------------------------------------------------------
-bin/kibana-keystore add server.ssl.keystore.password
+bin/kibana-keystore add server.ssl.keyPassphrase
 --------------------------------------------------------------------------------
-
-TIP: If your PKCS#12 file isn't protected with a password, depending on how it was generated, you may need to set
-`server.ssl.keystore.password` to an empty string.
 --
 
 +
@@ -103,7 +103,7 @@ server.ssl.enabled: true
 
 . Restart {kib}.
 
-After making these changes, you must always access {kib} via HTTPS. For example, https://<your_kibana_host>.com.
+After making these changes, you must always access {kib} via HTTPS. For example, `https://localhost:5601`.
 
 [[configuring-tls-kib-es]]
 ==== Encrypt traffic between {kib} and {es}
@@ -166,8 +166,8 @@ If your PKCS#12 file is encrypted, add the decryption password to your <<secure-
 bin/kibana-keystore add elasticsearch.ssl.truststore.password
 --------------------------------------------------------------------------------
 
-TIP: If your PKCS#12 file isn't protected with a password, depending on how it was generated, you may need to set
-`elasticsearch.ssl.truststore.password` to an empty string.
+NOTE: If you used `elasticsearch-certutil` to generate a PKCS#12 file and you did not specify a password, the file is encrypted, and you
+need to set `server.ssl.truststore.password` to an empty string.
 --
 
 +
diff --git a/docs/user/security/securing-kibana.asciidoc b/docs/user/security/securing-kibana.asciidoc
@@ -38,9 +38,8 @@ elasticsearch.password: "kibanapassword"
 The {kib} server submits requests as this user to access the cluster monitoring
 APIs and the `.kibana` index. The server does _not_ need access to user indices.
 
-The password for the built-in `kibana_system` user is typically set as part of
-the security configuration process on {es}. For more information, see
-{ref}/built-in-users.html[Built-in users].
+NOTE: The password for the built-in `kibana_system` user is typically set as part of the security configuration process on {es}. For more
+information, see {ref}/built-in-users.html[Built-in users].
 --
 
 . Set the `xpack.security.encryptionKey` property in the `kibana.yml`
@@ -74,20 +73,21 @@ For more information, see <<xpack-security-session-management, Session managemen
 
 . Restart {kib}.
 
-. [[kibana-roles]]Choose an authentication mechanism and grant users the privileges they need to
-use {kib}.
+. Temporarily log in to {kib} using the built-in `elastic` superuser so you can create new users and assign roles. If you are running {kib}
+locally, go to `https://localhost:5601` to view the login page.
 +
---
-For more information on Basic Authentication and additional methods of
-authenticating {kib} users, see <<kibana-authentication>>.
+NOTE: The password for the built-in `elastic` user is typically set as part of the security configuration process on {es}. For more
+information, see {ref}/built-in-users.html[Built-in users].
 
-To manage privileges, open the main menu, then click *Stack Management > Roles*.
+. [[kibana-roles]]Create roles and users to grant access to {kib}.
++
+--
+To manage privileges in {kib}, open the main menu, then click *Stack Management > Roles*. The built-in `kibana_admin` role will grant
+access to {kib} with administrator privileges. Alternatively, you can create additional roles that grant limited access to {kib}.
 
-If you're using the native realm with Basic Authentication, open then main menu, 
-then click *Stack Management > Users* to assign roles, or use the
-{ref}/security-api.html#security-user-apis[user management APIs]. For example,
-the following creates a user named `jacknich` and assigns it the `kibana_admin`
-role:
+If you're using the default native realm with Basic Authentication, open the main menu, then click *Stack Management > Users* to create
+users and assign roles, or use the {es} {ref}/security-api.html#security-user-apis[user management APIs]. For example, the following creates
+a user named `jacknich` and assigns it the `kibana_admin` role:
 
 [source,js]
 --------------------------------------------------------------------------------
@@ -98,6 +98,8 @@ POST /_security/user/jacknich
 }
 --------------------------------------------------------------------------------
 // CONSOLE
+
+TIP: For more information on Basic Authentication and additional methods of authenticating {kib} users, see <<kibana-authentication>>.
 --
 
 . Grant users access to the indices that they will be working with in {kib}.
@@ -111,17 +113,11 @@ on specific index patterns. For more information, see
 
 --
 
-. Verify that you can log in as a user. If you are running
-{kib} locally, go to `https://localhost:5601` and enter the credentials for a
-user you've assigned a {kib} user role. For example, you could log in as the user
-`jacknich`.
+. Log out of {kib} and verify that you can log in as a normal user. If you are running {kib} locally, go to `https://localhost:5601` and
+enter the credentials for a user you've assigned a {kib} user role. For example, you could log in as the user `jacknich`.
 +
---
-
-NOTE: This must be a user who has been assigned <<kibana-privileges, Kibana privileges>>.
-{kib} server credentials should only be used internally by the {kib} server.
-
---
+NOTE: This must be a user who has been assigned <<kibana-privileges, Kibana privileges>>. {kib} server credentials (the built-in
+`kibana_system` user) should only be used internally by the {kib} server.
 
 include::authentication/index.asciidoc[]
 include::securing-communications/index.asciidoc[]
