[7.5] Update security docs (#87215) (#87346)

# Conflicts:
#	docs/management/managing-saved-objects.asciidoc
#	docs/user/security/securing-communications/index.asciidoc
#	docs/user/security/securing-kibana.asciidoc

docs/management/managing-saved-objects.asciidoc

@@ -56,8 +56,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"]
@@ -69,8 +69,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]

docs/user/security/securing-communications/index.asciidoc

@@ -25,54 +25,62 @@ 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.
-
-You may choose to generate a certificate signing request (CSR) and private key using the {ref}/certutil.html[`elasticsearch-certutil`] tool.
+the FQDN in a production environment.
 
+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`.
 
-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.
+This will produce a PKCS#12 file named `kibana-server.p12`, which contains the server certificate and private key.
+
+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 contained in a PKCS#12 file:
++
+--
+You will need to extract the server certificate and private key in PEM format.
+[source,shell]
+----------------------------------------------------------
+openssl pkcs12 -in kibana-server.p12 -clcerts -nokeys -out kibana-server.crt
+openssl pkcs12 -in kibana-server.p12 -nocerts -nodes -out kibana-server.key
+----------------------------------------------------------
+This will produce a PEM-formatted server certificate (`kibana-server.crt`) and unencrypted private key (`kibana-server.key`). Then, specify
+these files in `kibana.yml` as described below.
+--
+
 .. If your server certificate and private key are in PEM format:
 +
 --
 Specify your server certificate and private key in `kibana.yml`:
+
 [source,yaml]
 --------------------------------------------------------------------------------
 server.ssl.certificate: "/path/to/kibana-server.crt"
 server.ssl.key: "/path/to/kibana-server.key"
 --------------------------------------------------------------------------------
+
 If your private key is encrypted, add the decryption password to your <<secure-settings,{kib} keystore>>:
+
 [source,yaml]
 --------------------------------------------------------------------------------
 bin/kibana-keystore add server.ssl.keyPassphrase
 --------------------------------------------------------------------------------
 --
-.. Otherwise, if your server certificate and private key are contained in a PKCS#12 file:
-+
---
-You will need to extract the server certificate and private key in PEM format.
-[source,shell]
-----------------------------------------------------------
-openssl pkcs12 -in kibana-server.p12 -clcerts -nokeys -out kibana-server.crt
-openssl pkcs12 -in kibana-server.p12 -nocerts -nodes -out kibana-server.key
-----------------------------------------------------------
-This will produce a PEM-formatted server certificate (`kibana-server.crt`) and unencrypted private key (`kibana-server.key`). Then, specify
-these files in `kibana.yml` as described above.
---
+
 +
 For more information about settings for certificates and keys, see <<settings,{kib} configuration settings>>.
+
 . Configure {kib} to enable TLS for inbound connections.
 +
 --
@@ -83,7 +91,8 @@ 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]]
 ==== Encrypting traffic between {kib} and {es}

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` 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` 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`
@@ -73,20 +72,21 @@ xpack.security.sessionTimeout: 600000
 
 . 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].
 
-You can manage privileges on the *Management / Security / Roles* page in {kib}.
+. [[kibana-roles]]Create roles and users to grant access to {kib}.
++
+--
+To manage privileges in {kib}, open the main menu, then click *Management / Security / Roles*. The built-in `kibana_user` 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, you can assign roles
-using the *Management / Security / Users* page in {kib} or 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_user` 
-role:
+If you're using the default native realm with Basic Authentication, open the main menu, then click *Management / Security / 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_user` role:
 
 [source,js]
 --------------------------------------------------------------------------------
@@ -97,6 +97,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}.
@@ -110,17 +112,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
-`jacknich` user created above.
+. 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` user) should only be used internally by the {kib} server.
 
 include::authentication/index.asciidoc[]
 include::securing-communications/index.asciidoc[]