[DOCS] Overhaul TLS security docs (#68946)

* Removing security overview and condensing.

* Adding new security file.

* Minor changes.

* Removing link to pass build.

* Adding minimal security page.

* Adding minimal security page.

* Changes to intro.

* Add basic and basic + http configurations.

* Lots of changes, removed files, and redirects.

* Moving some AD and LDAP sections, plus more redirects.

* Redirects for SAML.

* Updating snippet languages and redirects.

* Adding another SAML redirect.

* Hopefully fixing the ci/2 error.

* Fixing another broken link for SAML.

* Adding what's next sections and some cleanup.

* Removes both security tutorials from the TOC.

* Adding redirect for removed tutorial.

* Add graphic for Elastic Security layers.

* Incorporating reviewer feedback.

* Update x-pack/docs/en/security/securing-communications/security-basic-setup.asciidoc

Co-authored-by: Ioannis Kakavas <ikakavas@protonmail.com>

* Update x-pack/docs/en/security/securing-communications/security-minimal-setup.asciidoc

Co-authored-by: Yang Wang <ywangd@gmail.com>

* Update x-pack/docs/en/security/securing-communications/security-basic-setup.asciidoc

Co-authored-by: Yang Wang <ywangd@gmail.com>

* Update x-pack/docs/en/security/index.asciidoc

Co-authored-by: Ioannis Kakavas <ikakavas@protonmail.com>

* Update x-pack/docs/en/security/securing-communications/security-basic-setup-https.asciidoc

Co-authored-by: Ioannis Kakavas <ikakavas@protonmail.com>

* Apply suggestions from code review

Co-authored-by: Ioannis Kakavas <ikakavas@protonmail.com>
Co-authored-by: Yang Wang <ywangd@gmail.com>

* Additional changes from review feedback.

* Incorporating reviewer feedback.

* Incorporating more reviewer feedback.

* Clarify that TLS is for authenticating nodes

Co-authored-by: Tim Vernum <tim@adjective.org>

* Clarify security between nodes

Co-authored-by: Tim Vernum <tim@adjective.org>

* Clarify that TLS is between nodes

Co-authored-by: Tim Vernum <tim@adjective.org>

* Update title for configuring Kibana with a password

Co-authored-by: Tim Vernum <tim@adjective.org>

* Move section for enabling passwords between Kibana and ES to minimal security.

* Add section for transport description, plus incorporate more reviewer feedback.

* Moving operator privileges lower in the navigation.

Co-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com>
Co-authored-by: Ioannis Kakavas <ikakavas@protonmail.com>
Co-authored-by: Yang Wang <ywangd@gmail.com>
Co-authored-by: Tim Vernum <tim@adjective.org>

docs/reference/commands/certutil.asciidoc

@@ -214,7 +214,7 @@ parameter cannot be used with the `csr` parameter.
 applicable to the `cert` parameter.
 +
 --
-NOTE: This option is not recommended for <<ssl-tls,setting up TLS on a cluster>>.
+NOTE: This option is not recommended for <<encrypt-internode-communication,setting up TLS on a cluster>>.
 In fact, a self-signed certificate should be used only when you can be sure
 that a CA is definitely not needed and trust is directly given to the
 certificate itself.
@@ -253,7 +253,7 @@ Alternatively, you can specify the `--ca-pass`, `--out`, and `--pass` parameters
 By default, this command generates a file called `elastic-certificates.p12`,
 which you can copy to the relevant configuration directory for each Elastic
 product that you want to configure. For more information, see
-<<ssl-tls>>.
+<<encrypt-internode-communication>>.
 
 [discrete]
 [[certutil-silent]]

docs/reference/licensing/update-license.asciidoc

@@ -23,7 +23,7 @@ Updates the license for your {es} cluster.
 
 * If {es} {security-features} are enabled and you are installing a gold or higher
 license, you must enable TLS on the transport networking layer before you
-install the license. See <<configuring-tls>>.
+install the license. See <<encrypt-internode-communication>>.
 
 * If the <<operator-privileges,{operator-feature}>> is enabled, only operator
 users can use this API.

docs/reference/modules/remote-clusters.asciidoc

@@ -332,6 +332,6 @@ separately.
 
   An optional hostname string which is sent in the `server_name` field of
   the TLS Server Name Indication extension if
-  <<configuring-tls,TLS is enabled>>. The TLS transport will fail to open
+  <<encrypt-internode-communication,TLS is enabled>>. The TLS transport will fail to open
   remote connections if this field is not a valid hostname as defined by the
   TLS SNI specification.

docs/reference/monitoring/collecting-monitoring-data.asciidoc

@@ -155,7 +155,7 @@ xpack.monitoring.exporters:
 --
 
 .. If you configured the monitoring cluster to use
-<<configuring-tls,encrypted communications>>, you must use the HTTPS protocol in
+<<encrypt-internode-communication,encrypted communications>>, you must use the HTTPS protocol in
 the `host` setting. You must also specify the trusted CA certificates that will
 be used to verify the identity of the nodes in the monitoring cluster.
 

docs/reference/redirects.asciidoc

@@ -3,6 +3,102 @@
 
 The following pages have moved or been deleted.
 
+// [START] Security redirects
+
+[role="exclude",id="get-started-users"]
+=== Create users
+
+See <<security-create-builtin-users,Create passwords for built-in users>>.
+
+[role="exclude",id="encrypting-communications-certificates"]
+=== Generate certificates
+
+See <<security-basic-setup,Set up basic security for the Elastic Stack>>.
+
+[role="exclude",id="encrypting-internode-communications"]
+=== Tutorial: Encrypting communications
+
+See <<security-basic-setup,Set up basic security for the Elastic Stack>>.
+
+[role="exclude",id="encrypting-internode"]
+=== Encrypting internode communication
+
+See <<security-basic-setup,Set up basic security for the Elastic Stack>>.
+
+[role="exclude",id="security-getting-started"]
+=== Tutorial: Getting started with security
+
+See <<secure-cluster,Secure the Elastic Stack>>.
+
+[role="exclude",id="saml-guide"]
+=== Configure SAML single-sign on
+
+See <<saml-guide-stack,Configuring SAML single-sign-on on the {stack}>>.
+
+[role="exclude",id="saml-guide-authentication"]
+=== Configure {es} for SAML authentication
+
+See <<saml-elasticsearch-authentication,Configure {es} for SAML authentication>>.
+
+[role="exclude",id="saml-attribute-mapping"]
+==== Attribute mapping
+
+See <<saml-attributes-mapping,SAML attribute mapping>>.
+
+[role="exclude",id="active-directory-ssl"]
+=== Setting up SSL between {es} and Active Directory
+
+See <<tls-active-directory,Encrypting communications between {es} and Active Directory>>.
+
+[role="exclude",id="elasticsearch-security"]
+=== Security overview
+
+See <<secure-cluster,Secure the Elastic Stack>>.
+
+[role="exclude",id="get-started-enable-security"]
+=== Enable {es} {security-features}
+
+See <<security-minimal-setup,Set up minimal security for {es}>>.
+
+[role="exclude",id="ssl-tls"]
+=== Set up TLS on a cluster
+
+See <<encrypt-internode-communication,Encrypt internode communication>>.
+
+// [START] Configuring TLS
+[role="exclude",id="configuring-tls"]
+=== Configure TLS
+
+See <<encrypt-internode-communication,Encrypt internode communication>>.
+
+[role="exclude",id="tls-http"]
+==== Encrypt HTTP client communications
+
+See <<encrypt-http-communication,Encrypt HTTP client communications>>.
+
+[role="exclude",id="tls-transport"]
+==== Encrypt internode communication
+
+See <<encrypt-internode-communication,Encrypt internode communications>>.
+
+[role="exclude",id="node-certificates"]
+==== Generating node certificates
+
+See <<generate-certificates,Generate the certificate authority>>.
+
+[role="exclude",id="configuring-security"]
+=== Configure security in {es}
+
+See <<configuring-stack-security,Configuring security for the Elastic Stack>>.
+
+// [END] Configuring TLS
+
+[role="exclude",id="encrypting-communications"]
+=== Encrypting communications
+
+See <<configuring-stack-security,Configuring security for the Elastic Stack>>.
+// [END] Security redirects
+
 [roles="exclude",id="modules-scripting-stored-scripts"]
 === Stored scripts
 
@@ -406,7 +502,7 @@ See <<ref-native-settings>>.
 [role="exclude",id="configuring-saml-realm"]
 === Configuring a SAML realm
 
-See <<saml-guide>>.
+See <<saml-guide-stack>>.
 
 [role="exclude",id="saml-settings"]
 ==== SAML realm settings
@@ -498,7 +594,7 @@ See <<ad-realm-configuration>>.
 [role="exclude",id="how-security-works"]
 === How security works
 
-See <<elasticsearch-security>>.
+See <<configuring-stack-security>>.
 
 [role="exclude",id="rollup-job-config"]
 === Rollup job configuration

docs/reference/setup/bootstrap-checks-xes.asciidoc

@@ -14,7 +14,8 @@ If you use {watcher} and have chosen to encrypt sensitive data (by setting
 the secure settings store.
 
 To pass this bootstrap check, you must set the `xpack.watcher.encryption_key`
-on each node in the cluster. For more information, see <<encrypting-data>>.
+on each node in the cluster. For more information, see
+<<encrypting-data,Encrypting sensitive data in Watcher>>.
 
 [discrete]
 === PKI realm check
@@ -23,7 +24,8 @@ on each node in the cluster. For more information, see <<encrypting-data>>.
 If you use {es} {security-features} and a Public Key Infrastructure (PKI) realm,
 you must configure Transport Layer Security (TLS) on your cluster and enable
 client authentication on the network layers (either transport or http). For more
-information, see <<pki-realm>> and <<ssl-tls>>.
+information, see <<pki-realm,PKI user authentication>> and
+<<security-basic-setup-https,Set up basic security plus HTTPS>>.
 
 To pass this bootstrap check, if a PKI realm is enabled, you must configure TLS
 and enable client authentication on at least one network communication layer.
@@ -51,15 +53,15 @@ must also be valid.
 === SSL/TLS check
 //See TLSLicenseBootstrapCheck.java
 
-If you enable {es} {security-features}, unless you have a trial license, you 
+If you enable {es} {security-features}, unless you have a trial license, you
 must configure SSL/TLS for internode-communication.
 
 NOTE: Single-node clusters that use a loopback interface do not have this
 requirement.  For more information, see
-<<encrypting-communications>>.
+<<configuring-stack-security>>.
 
 To pass this bootstrap check, you must
-<<ssl-tls,set up SSL/TLS in your cluster>>.
+<<encrypt-internode-communication,set up SSL/TLS in your cluster>>.
 
 
 [discrete]

docs/reference/sql/functions/system.asciidoc

@@ -40,7 +40,7 @@ USER()
 *Output*: string
 
 *Description*: Returns the username of the authenticated user executing the query. This function can
-return `null` in case <<elasticsearch-security,security>> is disabled.
+return `null` in case <<configuring-stack-security,security>> is disabled.
 
 [source, sql]
 --------------------------------------------------

x-pack/docs/en/rest-api/security/create-api-keys.asciidoc

@@ -27,17 +27,17 @@ See the note under `role_descriptors`.
 ==== {api-description-title}
 
 The API keys are created by the {es} API key service, which is automatically enabled
-when you configure TLS on the HTTP interface. See <<tls-http>>. Alternatively,
-you can explicitly enable the `xpack.security.authc.api_key.enabled` setting. When 
-you are running in production mode, a bootstrap check prevents you from enabling 
-the API key service unless you also enable TLS on the HTTP interface. 
+when you configure TLS on the HTTP interface. See <<encrypt-http-communication>>. Alternatively,
+you can explicitly enable the `xpack.security.authc.api_key.enabled` setting. When
+you are running in production mode, a bootstrap check prevents you from enabling
+the API key service unless you also enable TLS on the HTTP interface.
 
 A successful create API key API call returns a JSON structure that contains the
 API key, its unique id, and its name. If applicable, it also returns expiration
-information for the API key in milliseconds. 
+information for the API key in milliseconds.
 
 NOTE: By default, API keys never expire. You can specify expiration information
-when you create the API keys. 
+when you create the API keys.
 
 See <<api-key-service-settings>> for configuration settings related to API key
 service.
@@ -54,7 +54,7 @@ The following parameters can be specified in the body of a POST or PUT request:
 `role_descriptors`::
 (Optional, array-of-role-descriptor) An array of role descriptors for this API
 key. This parameter is optional. When it is not specified or is an empty array,
-then the API key will have a _point in time snapshot of permissions of the 
+then the API key will have a _point in time snapshot of permissions of the
 authenticated user_. If you supply role descriptors then the resultant permissions
 would be an intersection of API keys permissions and authenticated user's permissions
 thereby limiting the access scope for API keys.

x-pack/docs/en/rest-api/security/get-tokens.asciidoc

@@ -21,7 +21,7 @@ Creates a bearer token for access without requiring basic authentication.
 ==== {api-description-title}
 
 The tokens are created by the {es} Token Service, which is automatically enabled
-when you configure TLS on the HTTP interface. See <<tls-http>>. Alternatively,
+when you configure TLS on the HTTP interface. See <<encrypt-http-communication>>. Alternatively,
 you can explicitly enable the `xpack.security.authc.token.enabled` setting. When
 you are running in production mode, a bootstrap check prevents you from enabling
 the token service unless you also enable TLS on the HTTP interface.

x-pack/docs/en/rest-api/security/grant-api-keys.asciidoc

@@ -25,20 +25,20 @@ API key for a user that is different than the user that runs the API.
 
 The caller must have authentication credentials (either an access token, or a username and password) for the user on whose behalf the API key will be created. It is not possible to use this API to create an API key without that user's credentials.
 
-This API is intended be used by applications that need to create and manage API keys for end users, but cannot guarantee that those users have permission to create API keys on their own behalf (see <<security-api-create-api-key-prereqs>>). 
+This API is intended be used by applications that need to create and manage API keys for end users, but cannot guarantee that those users have permission to create API keys on their own behalf (see <<security-api-create-api-key-prereqs>>).
 The API keys are created by the {es} API key service, which is automatically
-enabled when you configure TLS on the HTTP interface. See <<tls-http>>.
+enabled when you configure TLS on the HTTP interface. See <<encrypt-http-communication>>.
 Alternatively, you can explicitly enable the
 `xpack.security.authc.api_key.enabled` setting. When you are running in
 production mode, a bootstrap check prevents you from enabling the API key
-service unless you also enable TLS on the HTTP interface. 
+service unless you also enable TLS on the HTTP interface.
 
 A successful grant API key API call returns a JSON structure that contains the
 API key, its unique id, and its name. If applicable, it also returns expiration
-information for the API key in milliseconds. 
+information for the API key in milliseconds.
 
 NOTE: By default, API keys never expire. You can specify expiration information
-when you create the API keys. 
+when you create the API keys.
 
 See <<api-key-service-settings>> for configuration settings related to API key
 service.
@@ -68,7 +68,7 @@ expire.
 (Optional, array-of-role-descriptor) An array of role descriptors for this API
 key. This parameter is optional. When it is not specified or is an empty array,
 the API key has a point in time snapshot of permissions of the specified user or
-access token. If you supply role descriptors, the resultant permissions are an 
+access token. If you supply role descriptors, the resultant permissions are an
 intersection of API keys permissions and the permissions of the user or access
 token. The structure of role descriptor is the same as the request for create
 role API. For more details, see <<security-api-put-role>>.
@@ -81,7 +81,7 @@ The type of grant. Supported grant types are: `access_token`,`password`.
 (Required*, string)
 In this type of grant, you must supply an access token that was created by the
 {es} token service. For more information, see
-<<security-api-get-token>> and <<tls-http>>.
+<<security-api-get-token>> and <<encrypt-http-communication>>.
 
 `password`:::
 In this type of grant, you must supply the user ID and password for which you
@@ -109,8 +109,8 @@ POST /_security/api_key/grant
   "password" : "x-pack-test-password",
   "api_key" : {
     "name": "my-api-key",
-    "expiration": "1d", 
-    "role_descriptors": { 
+    "expiration": "1d",
+    "role_descriptors": {
       "role-a": {
         "cluster": ["all"],
         "index": [

x-pack/docs/en/rest-api/security/ssl.asciidoc

@@ -26,7 +26,7 @@ privileges to use this API. For more information, see
 
 For more information about how certificates are configured in conjunction with
 Transport Layer Security (TLS), see
-<<ssl-tls>>.
+<<encrypt-internode-communication>>.
 
 The API returns a list that includes certificates from all TLS contexts
 including:

x-pack/docs/en/security/auditing/enable-audit-logging.asciidoc

@@ -1,6 +1,6 @@
 [role="xpack"]
 [[enable-audit-logging]]
-== Enabling audit logging
+== Enable audit logging
 
 You can log security-related events such as authentication failures and refused connections
 to monitor your cluster for suspicious activity (including data access authorization and user
@@ -22,10 +22,10 @@ To enable audit logging:
 . Set `xpack.security.audit.enabled` to `true` in `elasticsearch.yml`.
 . Restart {es}.
 
-When audit logging is enabled, <<audit-event-types, security events>> are persisted to 
+When audit logging is enabled, <<audit-event-types, security events>> are persisted to
 a dedicated `<clustername>_audit.json` file on the host's file system, on every cluster node.
 For more information, see <<audit-log-output>>.
 
-You can configure additional options to control what events are logged and 
-what information is included in the audit log. 
+You can configure additional options to control what events are logged and
+what information is included in the audit log.
 For more information, see <<auditing-settings>>.

x-pack/docs/en/security/authentication/active-directory-realm.asciidoc

@@ -47,7 +47,7 @@ properties are populated in the user's _metadata_:
                         groups were mapped to a role).
 |=======================
 
-This metadata is returned in the 
+This metadata is returned in the
 <<security-api-authenticate,authenticate API>> and can be used with
 <<templating-role-query, templated queries>> in roles.
 
@@ -63,8 +63,4 @@ Two modes of operation are supported: failover and load balancing.
 See
 <<load-balancing>>.
 
-[[active-directory-ssl]]
-==== Setting up SSL between Elasticsearch and Active Directory
-
-See 
-<<tls-active-directory>>.
+include::../securing-communications/tls-ad.asciidoc[]

x-pack/docs/en/security/authentication/configuring-kerberos-realm.asciidoc

@@ -1,35 +1,35 @@
 Kerberos is used to protect services and uses a ticket-based authentication
 protocol to authenticate users.
-You can configure {es} to use the Kerberos V5 authentication protocol, which is 
+You can configure {es} to use the Kerberos V5 authentication protocol, which is
 an industry standard protocol, to authenticate users.
 In this scenario, clients must present Kerberos tickets for authentication.
 
 In Kerberos, users authenticate with an authentication service and later
 with a ticket granting service to generate a TGT (ticket-granting ticket).
 This ticket is then presented to the service for authentication.
-Refer to your Kerberos installation documentation for more information about 
-obtaining TGT. {es} clients must first obtain a TGT then initiate the process of 
+Refer to your Kerberos installation documentation for more information about
+obtaining TGT. {es} clients must first obtain a TGT then initiate the process of
 authenticating with {es}.
 
 [[kerberos-realm-prereq]]
 ===== Before you begin
 
-. Deploy Kerberos. 
+. Deploy Kerberos.
 +
 --
 You must have the Kerberos infrastructure set up in your environment.
 
-NOTE: Kerberos requires a lot of external services to function properly, such as 
-time synchronization between all machines and working forward and reverse DNS 
+NOTE: Kerberos requires a lot of external services to function properly, such as
+time synchronization between all machines and working forward and reverse DNS
 mappings in your domain. Refer to your Kerberos documentation for more details.
 
-These instructions do not cover setting up and configuring your Kerberos 
-deployment. Where examples are provided, they pertain to an MIT Kerberos V5 
-deployment. For more information, see 
+These instructions do not cover setting up and configuring your Kerberos
+deployment. Where examples are provided, they pertain to an MIT Kerberos V5
+deployment. For more information, see
 http://web.mit.edu/kerberos/www/index.html[MIT Kerberos documentation]
 --
 
-. Configure Java GSS. 
+. Configure Java GSS.
 +
 --
 
@@ -39,10 +39,10 @@ To support Kerberos authentication, {es} needs the following files:
 * `krb5.conf`, a Kerberos configuration file
 *  A `keytab` file that contains credentials for the {es} service principal
 
-The configuration requirements depend on your Kerberos setup. Refer to your 
+The configuration requirements depend on your Kerberos setup. Refer to your
 Kerberos documentation to configure the `krb5.conf` file.
 
-For more information on Java GSS, see 
+For more information on Java GSS, see
 https://docs.oracle.com/javase/10/security/kerberos-requirements1.htm[Java GSS Kerberos requirements]
 --
 
@@ -51,7 +51,7 @@ https://docs.oracle.com/javase/10/security/kerberos-requirements1.htm[Java GSS K
 --
 If your {es} cluster is operating in production mode, you must configure the
 HTTP interface to use SSL/TLS before you can enable Kerberos authentication. For
-more information, see <<tls-http>>.
+more information, see <<encrypt-http-communication>>.
 
 This step is necessary to support Kerberos authentication via {kib}.
 It is not required for Kerberos authentication directly against the {es} Rest API.
@@ -79,22 +79,22 @@ It is not required for Kerberos authentication directly against the {es} Rest AP
 
 To configure a Kerberos realm in {es}:
 
-. Configure the JVM to find the Kerberos configuration file. 
+. Configure the JVM to find the Kerberos configuration file.
 +
 --
-{es} uses Java GSS and JAAS Krb5LoginModule to support Kerberos authentication 
-using a Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO) mechanism. 
-The Kerberos configuration file (`krb5.conf`) provides information such as the 
-default realm, the Key Distribution Center (KDC), and other configuration details 
-required for Kerberos authentication. When the JVM needs some configuration 
-properties, it tries to find those values by locating and loading this file. The 
-JVM system property to configure the file path is `java.security.krb5.conf`. To 
-configure JVM system properties see <<jvm-options>>. 
-If this system property is not specified, Java tries to locate the file based on 
+{es} uses Java GSS and JAAS Krb5LoginModule to support Kerberos authentication
+using a Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO) mechanism.
+The Kerberos configuration file (`krb5.conf`) provides information such as the
+default realm, the Key Distribution Center (KDC), and other configuration details
+required for Kerberos authentication. When the JVM needs some configuration
+properties, it tries to find those values by locating and loading this file. The
+JVM system property to configure the file path is `java.security.krb5.conf`. To
+configure JVM system properties see <<jvm-options>>.
+If this system property is not specified, Java tries to locate the file based on
 the conventions.
 
 TIP: It is recommended that this system property be configured for {es}.
-The method for setting this property depends on your Kerberos infrastructure. 
+The method for setting this property depends on your Kerberos infrastructure.
 Refer to your Kerberos documentation for more details.
 
 For more information, see http://web.mit.edu/kerberos/krb5-latest/doc/admin/conf_files/krb5_conf.html[krb5.conf]
@@ -104,11 +104,11 @@ For more information, see http://web.mit.edu/kerberos/krb5-latest/doc/admin/conf
 . Create a keytab for the {es} node.
 +
 --
-A keytab is a file that stores pairs of principals and encryption keys. {es} 
-uses the keys from the keytab to decrypt the tickets presented by the user. You 
-must create a keytab for {es} by using the tools provided by your Kerberos 
-implementation. For example, some tools that create keytabs are `ktpass.exe` on 
-Windows and `kadmin` for MIT Kerberos. 
+A keytab is a file that stores pairs of principals and encryption keys. {es}
+uses the keys from the keytab to decrypt the tickets presented by the user. You
+must create a keytab for {es} by using the tools provided by your Kerberos
+implementation. For example, some tools that create keytabs are `ktpass.exe` on
+Windows and `kadmin` for MIT Kerberos.
 --
 
 . Put the keytab file in the {es} configuration directory.
@@ -117,8 +117,8 @@ Windows and `kadmin` for MIT Kerberos.
 Make sure that this keytab file has read permissions. This file contains
 credentials, therefore you must take appropriate measures to protect it.
 
-IMPORTANT: {es} uses Kerberos on the HTTP network layer, therefore there must be 
-a keytab file for the HTTP service principal on every {es} node. The service 
+IMPORTANT: {es} uses Kerberos on the HTTP network layer, therefore there must be
+a keytab file for the HTTP service principal on every {es} node. The service
 principal name must have the format `HTTP/es.domain.local@ES.DOMAIN.LOCAL`.
 The keytab files are unique for each node since they include the hostname.
 An {es} node can act as any principal a client requests as long as that
@@ -126,18 +126,18 @@ principal and its credentials are found in the configured keytab.
 
 --
 
-. Create a Kerberos realm. 
+. Create a Kerberos realm.
 +
 --
 
-To enable Kerberos authentication in {es}, you must add a Kerberos realm in the 
+To enable Kerberos authentication in {es}, you must add a Kerberos realm in the
 realm chain.
 
 NOTE: You can configure only one Kerberos realm on {es} nodes.
 
 To configure a Kerberos realm, there are a few mandatory realm settings and
 other optional settings that you need to configure in the `elasticsearch.yml`
-configuration file. Add a realm configuration under the 
+configuration file. Add a realm configuration under the
 `xpack.security.authc.realms.kerberos` namespace.
 
 The most common configuration for a Kerberos realm is as follows:
@@ -150,10 +150,10 @@ xpack.security.authc.realms.kerberos.kerb1:
   remove_realm_name: false
 ------------------------------------------------------------
 
-The `username` is extracted from the ticket presented by user and usually has 
-the format `username@REALM`. This `username` is used for mapping 
-roles to the user. If realm setting `remove_realm_name` is 
-set to `true`, the realm part (`@REALM`) is removed. The resulting `username` 
+The `username` is extracted from the ticket presented by user and usually has
+the format `username@REALM`. This `username` is used for mapping
+roles to the user. If realm setting `remove_realm_name` is
+set to `true`, the realm part (`@REALM`) is removed. The resulting `username`
 is used for role mapping.
 
 For detailed information of available realm settings,
@@ -172,7 +172,7 @@ configure these role mappings by using the
 <<security-api-put-role-mapping,create or update role mappings API>>. You
 identify users by their `username` field.
 
-The following example uses the role mapping API to map `user@REALM` to the roles 
+The following example uses the role mapping API to map `user@REALM` to the roles
 `monitoring` and `user`:
 
 [source,console]
@@ -187,8 +187,8 @@ POST /_security/role_mapping/kerbrolemapping
 }
 --------------------------------------------------
 
-In case you want to support Kerberos cross realm authentication you may 
-need to map roles based on the Kerberos realm name. For such scenarios 
+In case you want to support Kerberos cross realm authentication you may
+need to map roles based on the Kerberos realm name. For such scenarios
 following are the additional user metadata available for role mapping:
 - `kerberos_realm` will be set to Kerberos realm name.
 - `kerberos_user_principal_name` will be set to user principal name from the Kerberos ticket.

x-pack/docs/en/security/authentication/configuring-pki-realm.asciidoc

@@ -75,7 +75,7 @@ to allow delegation. See <<pki-realm-for-proxied-clients>>.
 you're following through with the next steps, you might wish to hold the
 restart for last.
 
-. <<configuring-tls,Enable SSL/TLS>>.
+. <<encrypt-internode-communication,Enable SSL/TLS>>.
 
 . Enable client authentication on the desired network layers (transport or http).
 +
@@ -103,14 +103,14 @@ In particular this means:
   or by setting `verification_mode` to `none`.
 * The _protocols_ supported by the interface must be compatible with those
   used by the client.
-  
+
 For an explanation of these settings, see <<ssl-tls-settings>>.
 
 The relevant network interface (transport or http) must be configured to trust
 any certificate that is to be used within the PKI realm. However, it is possible
 to configure the PKI realm to trust only a _subset_ of the certificates accepted
-by the network interface. This is useful when the SSL/TLS layer trusts clients 
-with certificates that are signed by a different CA than the one that signs your 
+by the network interface. This is useful when the SSL/TLS layer trusts clients
+with certificates that are signed by a different CA than the one that signs your
 users' certificates.
 
 To configure the PKI realm with its own truststore, specify the
@@ -224,7 +224,7 @@ the PKI realms that have been configured for delegation.
 To permit authentication delegation for a specific {es} PKI realm, start by
 configuring the realm for the usual case, as detailed in the
 <<pki-realm-for-direct-clients>> section. In this scenario, when you enable TLS,
-it is mandatory that you <<tls-http,encrypt HTTP client communications>>.
+it is mandatory that you <<encrypt-http-communication,encrypt HTTP client communications>>.
 
 You must also explicitly configure a `truststore` (or, equivalently
 `certificate_authorities`) even though it is the same trust configuration that
@@ -248,7 +248,7 @@ xpack:
 ------------------------------------------------------------
 
 After you restart {es}, this realm can validate delegated PKI authentication.
-You must then 
+You must then
 {kibana-ref}/kibana-authentication.html#pki-authentication[configure {kib} to allow PKI certificate authentication].
 
 A PKI realm with `delegation.enabled` still works unchanged for clients

x-pack/docs/en/security/authentication/index.asciidoc

@@ -1,20 +0,0 @@
-
-include::overview.asciidoc[]
-include::built-in-users.asciidoc[]
-include::internal-users.asciidoc[]
-include::token-authentication-services.asciidoc[]
-include::realms.asciidoc[]
-include::realm-chains.asciidoc[]
-include::active-directory-realm.asciidoc[]
-include::file-realm.asciidoc[]
-include::ldap-realm.asciidoc[]
-include::native-realm.asciidoc[]
-include::oidc-realm.asciidoc[]
-include::pki-realm.asciidoc[]
-include::saml-realm.asciidoc[]
-include::kerberos-realm.asciidoc[]
-include::custom-realm.asciidoc[]
-include::anonymous-access.asciidoc[]
-include::user-cache.asciidoc[]
-include::saml-guide.asciidoc[]
-include::oidc-guide.asciidoc[]

x-pack/docs/en/security/authentication/ldap-realm.asciidoc

@@ -17,7 +17,7 @@ _common name_ (`cn`) or _unique ID_ (`uid`). A DN is specified as a string,
 for example  `"cn=admin,dc=example,dc=com"` (white spaces are ignored).
 
 The `ldap` realm supports two modes of operation, a user search mode
-and a mode with specific templates for user DNs. 
+and a mode with specific templates for user DNs.
 
 [[mapping-roles-ldap]]
 ==== Mapping LDAP groups to roles
@@ -72,3 +72,5 @@ the {security-features} should interact with multiple LDAP servers. The
 {security-features} support both failover and load balancing modes of operation.
 
 See <<load-balancing>>.
+
+include::../securing-communications/tls-ldap.asciidoc[]

x-pack/docs/en/security/authentication/oidc-guide.asciidoc

@@ -63,7 +63,7 @@ configure the HTTP interface to use SSL/TLS before you can enable OpenID Connect
 authentication.
 
 For more information, see
-<<tls-http>>.
+<<encrypt-http-communication>>.
 
 [[oidc-enable-token]]
 ==== Enable the token service

x-pack/docs/en/security/authentication/overview.asciidoc

@@ -18,7 +18,7 @@ Directory.
 The {stack-security-features} provide built-in realms such as `native`,`ldap`,
 `active_directory`, `pki`, `file`, `saml`, and `oidc`. If none of the built-in
 realms meet your needs, you can also build your own custom realm and plug it
-into the {stack}. 
+into the {stack}.
 
 When {security-features} are enabled, depending on the realms you've configured,
 you must attach your user credentials to the requests sent to {es}. For example,
@@ -29,3 +29,22 @@ The {security-features} provide two services: the token service and the api key
 service. You can use these services to exchange the current authentication for
 a token or key. This token or key can then be used as credentials for authenticating
 new requests. These services are enabled by default when TLS/SSL is enabled for HTTP.
+
+include::built-in-users.asciidoc[][]
+include::internal-users.asciidoc[]
+include::token-authentication-services.asciidoc[]
+include::realms.asciidoc[]
+include::realm-chains.asciidoc[]
+include::active-directory-realm.asciidoc[]
+include::file-realm.asciidoc[]
+include::ldap-realm.asciidoc[]
+include::native-realm.asciidoc[]
+include::oidc-realm.asciidoc[]
+include::pki-realm.asciidoc[]
+include::saml-realm.asciidoc[]
+include::kerberos-realm.asciidoc[]
+include::custom-realm.asciidoc[]
+include::anonymous-access.asciidoc[]
+include::user-cache.asciidoc[]
+include::saml-guide.asciidoc[leveloffset=+1]
+include::oidc-guide.asciidoc[leveloffset=+1]

x-pack/docs/en/security/authentication/saml-guide.asciidoc

@@ -1,5 +1,5 @@
 [role="xpack"]
-[[saml-guide]]
+[[saml-guide-stack]]
 
 == Configuring SAML single-sign-on on the {stack}
 
@@ -72,7 +72,7 @@ For `<LogoutRequest>` messages, the message itself must be signed, and the
 signature should be provided as a URL parameter, as required by the HTTP-Redirect
 binding.
 
-[[saml-guide-authentication]]
+[[saml-elasticsearch-authentication]]
 === Configure {es} for SAML authentication
 
 There are five configuration steps to enable SAML authentication in {es}:
@@ -91,7 +91,7 @@ configure the HTTP interface to use SSL/TLS before you can enable SAML
 authentication.
 
 For more information, see
-<<tls-http>>.
+<<encrypt-http-communication>>.
 
 [[saml-enable-token]]
 ==== Enable the token service
@@ -188,10 +188,10 @@ sp.logout::
     proxies involved, but it will typically be +$\{kibana-url}/logout+ where
     _$\{kibana-url}_ is the base URL for your {kib} instance.
 
-attribute.principal:: See <<saml-attribute-mapping>>.
-attribute.groups:: See <<saml-attribute-mapping>>.
+attribute.principal:: See <<saml-attributes-mapping>>.
+attribute.groups:: See <<saml-attributes-mapping>>.
 
-[[saml-attribute-mapping]]
+[[saml-attributes-mapping]]
 ==== Attribute mapping
 
 When a user connects to {kib} through your Identity Provider, the Identity
@@ -627,9 +627,9 @@ The {stack} supports generating such a metadata file using the
 <<saml-metadata,`bin/elasticsearch-saml-metadata` command>> or the
 <<security-api-saml-sp-metadata,SAML service provider metadata API>>.
 
-You can generate the SAML metadata by issuing the API request to {es} and store 
-it as an XML file using tools like `jq`. For example, the following command 
-generates the metadata for the SAML realm `realm1` and saves it to a 
+You can generate the SAML metadata by issuing the API request to {es} and store
+it as an XML file using tools like `jq`. For example, the following command
+generates the metadata for the SAML realm `realm1` and saves it to a
 `metadata.xml` file:
 
 ["source","console"]

x-pack/docs/en/security/authorization/index.asciidoc

@@ -1,26 +0,0 @@
-
-include::overview.asciidoc[]
-
-include::built-in-roles.asciidoc[]
-
-include::managing-roles.asciidoc[]
-
-include::stack-management.asciidoc[]
-
-include::privileges.asciidoc[]
-
-include::document-level-security.asciidoc[]
-
-include::field-level-security.asciidoc[]
-
-include::alias-privileges.asciidoc[]
-
-include::mapping-roles.asciidoc[]
-
-include::field-and-document-access-control.asciidoc[]
-
-include::run-as-privilege.asciidoc[leveloffset=+2]
-
-include::configuring-authorization-delegation.asciidoc[]
-
-include::custom-authorization.asciidoc[]

x-pack/docs/en/security/authorization/overview.asciidoc

@@ -3,10 +3,10 @@
 == User authorization
 
 The {stack-security-features} add _authorization_, which is the process of determining whether the user behind an incoming request is allowed to execute
-the request. 
+the request.
 
-This process takes place after the user is successfully identified and 
-<<setting-up-authentication,authenticated>>. 
+This process takes place after the user is successfully identified and
+<<setting-up-authentication,authenticated>>.
 
 [[roles]]
 [discrete]
@@ -14,7 +14,7 @@ This process takes place after the user is successfully identified and
 
 The {security-features} provide a role-based access control (RBAC) mechanism,
 which enables you to authorize users by assigning privileges to roles and
-assigning roles to users or groups. 
+assigning roles to users or groups.
 
 image::security/authorization/images/authorization.png[This image illustrates role-based access control]
 
@@ -47,17 +47,17 @@ _User_::
 The authenticated user.
 
 _Group_::
-One or more groups to which a user belongs. Groups are not supported in some 
-realms, such as native, file, or PKI realms. 
+One or more groups to which a user belongs. Groups are not supported in some
+realms, such as native, file, or PKI realms.
 
 A role has a unique name and identifies a set of permissions that translate to
-privileges on resources. You can associate a user or group with an arbitrary 
-number of roles. When you map roles to groups, the roles of a user in that group 
-are the combination of the roles assigned to that group and the roles assigned 
-to that user. Likewise, the total set of permissions that a user has is defined 
+privileges on resources. You can associate a user or group with an arbitrary
+number of roles. When you map roles to groups, the roles of a user in that group
+are the combination of the roles assigned to that group and the roles assigned
+to that user. Likewise, the total set of permissions that a user has is defined
 by the union of the permissions in all its roles.
 
-The method for assigning roles to users varies depending on which realms you use 
+The method for assigning roles to users varies depending on which realms you use
 to authenticate users. For more information, see <<mapping-roles>>.
 
 [[attributes]]
@@ -69,7 +69,31 @@ mechanism, which enables you to use attributes to restrict access to documents
 in search queries and aggregations. For example, you can assign attributes to
 users and documents, then implement an access policy in a role definition. Users
 with that role can read a specific document only if they have all the required
-attributes. 
+attributes.
 
-For more information, see 
+For more information, see
 https://www.elastic.co/blog/attribute-based-access-control-with-xpack[Document-level attribute-based access control with X-Pack 6.1].
+
+include::built-in-roles.asciidoc[]
+
+include::managing-roles.asciidoc[]
+
+include::stack-management.asciidoc[]
+
+include::privileges.asciidoc[]
+
+include::document-level-security.asciidoc[]
+
+include::field-level-security.asciidoc[]
+
+include::alias-privileges.asciidoc[]
+
+include::mapping-roles.asciidoc[]
+
+include::field-and-document-access-control.asciidoc[]
+
+include::run-as-privilege.asciidoc[leveloffset=+2]
+
+include::configuring-authorization-delegation.asciidoc[]
+
+include::custom-authorization.asciidoc[]

x-pack/docs/en/security/ccs-clients-integrations/cross-cluster.asciidoc

@@ -28,7 +28,7 @@ For more information about the `xpack.security.enabled` setting, see
 <<security-settings>>.
 
 * Enable encryption globally. To encrypt communications, you must enable
-  <<ssl-tls,enable SSL/TLS>> on every node.
+  <<encrypt-internode-communication,enable SSL/TLS>> on every node.
 
 * Enable a trust relationship between the cluster used for performing cross
   cluster search (the local cluster) and all remote clusters.  This can be done

x-pack/docs/en/security/configuring-es.asciidoc

@@ -8,8 +8,7 @@
 The {es} {security-features} enable you to easily secure a cluster. You can
 password-protect your data as well as implement more advanced security measures
 such as encrypting communications, role-based access control, IP filtering, and
-auditing. For more information, see
-<<elasticsearch-security>>.
+auditing.
 
 . Verify that you are using a license that includes the specific
 {security-features} you want.
@@ -23,17 +22,17 @@ For more information, see https://www.elastic.co/subscriptions and
 your cluster. If you are using basic or trial licenses, the default value is `false`.
 For more information, see <<security-settings>>.
 
-. If you plan to run {es} in a Federal Information Processing Standard (FIPS) 
-140-2 enabled JVM, see <<fips-140-compliance>>. 
+. If you plan to run {es} in a Federal Information Processing Standard (FIPS)
+140-2 enabled JVM, see <<fips-140-compliance>>.
 
-. <<configuring-tls,Configure Transport Layer Security (TLS/SSL) for internode-communication>>.
+. <<encrypt-internode-communication,Configure Transport Layer Security (TLS/SSL) for internode-communication>>.
 +
 --
 NOTE: This requirement applies to clusters with more than one node and to
 clusters with a single node that listens on an external interface. Single-node
 clusters that use a loopback interface do not have this requirement.  For more
 information, see
-<<encrypting-communications>>.
+<<configuring-stack-security>>.
 
 --
 
@@ -70,7 +69,7 @@ user API.
 --
 TIP: The types of authentication realms that you can enable varies according to
 your subscription. For more information, see https://www.elastic.co/subscriptions.
- 
+
 --
 ** <<active-directory-realm,Active Directory realms>>
 ** <<file-realm,File realms>>
@@ -127,7 +126,7 @@ information, see https://www.elastic.co/subscriptions.
 xpack.security.audit.enabled: true
 ----------------------------
 +
-For more information, see <<enable-audit-logging>> and <<auditing-settings>>. 
+For more information, see <<enable-audit-logging>> and <<auditing-settings>>.
 
 .. Restart {es}.
 
@@ -139,4 +138,3 @@ To walk through the configuration of {security-features} in {es}, {kib}, {ls}, a
 
 include::reference/files.asciidoc[]
 include::fips-140-compliance.asciidoc[]
-

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

@@ -0,0 +1,72 @@
+[[configuring-stack-security]]
+== Configure security for the Elastic Stack
+++++
+<titleabbrev>Configuring security</titleabbrev>
+++++
+
+Security needs vary depending on whether you're developing locally on your
+laptop or securing all communications in a production environment. Because
+security needs vary, the following scenarios provide options for configuring
+the Elastic Stack.
+
+TIP: Each subsequent scenario builds on the previous one so that you can add
+additional security by building on the existing layer.
+
+These scenarios don't cover every situation, but provide a framework for
+securing {es} and the Elastic Stack based on typical use cases.
+
+image::images/elastic-security-overview.png[Elastic Security layers]
+
+[discrete]
+[[security-minimal-overview]]
+=== Minimal security ({es} Development)
+
+If you want to set up {es} on your laptop and start developing, this scenario
+is for you. This configuration prevents unauthorized access to your local
+cluster by setting up passwords for the built-in users. You also configure
+password authentication for {kib}.
+
+IMPORTANT: Only use this security configuration for local development.
+
+<<security-minimal-setup,Set up minimal security>>
+
+[discrete]
+[[security-basic-overview]]
+=== Basic security ({es} Production)
+
+This scenario builds on the minimal security requirements by adding transport
+Layer Security (TLS) for communication between nodes. This additional layer
+requires that nodes verify security certificates, which prevents unauthorized
+nodes from joining your {es} cluster.
+
+Your external HTTP traffic between {es} and {kib} won't be encrypted, but
+internode communication will be secured.
+
+<<security-basic-setup,Set up basic security>>
+
+[discrete]
+[[security-basic-https-overview]]
+=== Basic security plus secured HTTPS traffic (Elastic Stack)
+
+This scenario builds on the one for basic security and secures all HTTP
+traffic with TLS. In addition to configuring TLS on the transport interface of
+your {es} cluster, you configure TLS on the HTTP interface for both
+{es} and {kib}.
+
+NOTE: If you need mutual (bidirectional) TLS on the HTTP layer, then you'll
+need to configure mutual authenticated encryption.
+
+You then configure {kib} and Beats to communicate with
+{es} using TLS so that all communications are encrypted. This level
+of security is strong, and ensures that any communications in and out of your
+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[]
+include::securing-communications/configuring-tls-docker.asciidoc[]
+include::securing-communications/enabling-cipher-suites.asciidoc[]
+include::reference/files.asciidoc[]
+include::fips-140-compliance.asciidoc[]

x-pack/docs/en/security/get-started-security.asciidoc

@@ -355,11 +355,11 @@ prevent unauthorized access to the {stack}.
 
 Later, when you're ready to increase the number of nodes in your cluster, you'll
 want to encrypt communications across the {stack}. To learn how, read
-<<encrypting-communications>>.
+<<configuring-stack-security>>.
 
 For more detailed information about securing the {stack}, see:
 
-* <<configuring-security,Configuring security in {es}>>. Encrypt
+* <<configuring-stack-security,Configuring security in {es}>>. Encrypt
 inter-node communications, set passwords for the built-in users, and manage your
 users and roles.
 

x-pack/docs/en/security/index.asciidoc

@@ -1,52 +1,109 @@
 [[secure-cluster]]
-= Secure a cluster
+= Secure the Elastic Stack
 
 [partintro]
 --
-The {stack-security-features} enable you to easily secure a cluster. You can
-password-protect your data as well as implement more advanced security
-measures such as encrypting communications, role-based access control,
-IP filtering, and auditing.
-
-* <<elasticsearch-security>>
-* <<configuring-security>>
-* <<setting-up-authentication>>
-* <<saml-guide>>
-* <<oidc-guide>>
-* <<authorization>>
-* <<enable-audit-logging>>
-* <<encrypting-communications>>
-* <<ccs-clients-integrations>>
-* <<operator-privileges>>
-* <<security-getting-started>>
-* <<encrypting-internode-communications>>
-* <<security-troubleshooting>>
-* <<security-limitations>>
 
---
+The Elastic Stack is comprised of many moving parts. There are the {es}
+nodes that form the cluster, plus {ls} instances, {kib} instances, {beats}
+agents, and clients all communicating with the cluster.
+
+<<configuring-stack-security,Configure security for the Elastic Stack>> 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 Elastic Stack. You can also implement additional security measures, such as
+role-based access control, IP filtering, and auditing.
+
+Enabling security protects {es} clusters by:
+
+* <<preventing-unauthorized-access, Preventing unauthorized access>>
+  with password protection, role-based access control, and IP filtering.
+* <<preserving-data-integrity, Preserving the integrity of your data>>
+  with SSL/TLS encryption.
+* <<maintaining-audit-trail, Maintaining an audit trail>>
+  so you know who's doing what to your cluster and the data it stores.
+
+TIP: If you plan to run {es} in a Federal Information Processing Standard (FIPS)
+140-2 enabled JVM, see <<fips-140-compliance>>.
+
+[discrete]
+[[preventing-unauthorized-access]]
+== Preventing unauthorized access
+
+To prevent unauthorized access to your {es} cluster, you need a way to
+_authenticate_ users in order to validate that a user is who they claim to be. For
+example, making sure that only the person named _Kelsey Andorra_ can sign
+in as the user `kandorra`. The {es-security-features} provide a standalone
+authentication mechanism that enables you to quickly password-protect your
+cluster.
+
+If you're already using LDAP, Active Directory, or PKI to manage users in your
+organization, the {security-features} integrate with those systems to perform
+user authentication.
+
+In many cases, authenticating users isn't enough. You also need a way to
+control what data users can access and what tasks they can perform. By enabling
+the {es-security-features}, you can _authorize_ users by assigning access
+privileges to roles and assigning those roles to users. Using this role-based
+access control mechanism (RBAC), you can limit the user `kandorra` to only
+perform read operations on the `events` index restrict access to all other
+indices.
+
+The {security-features} also enable you to restrict the nodes and clients that
+can connect to the cluster based on <<ip-filtering,IP filters>>. You can
+block and allow specific IP addresses, subnets, or DNS domains to
+control network-level access to a cluster.
+
+See <<setting-up-authentication,User authentication>> and
+<<authorization,User authorization>>.
+
+[discrete]
+[[preserving-data-integrity]]
+== Preserving data integrity and confidentiality
+
+A critical part of security is keeping confidential data secured.
+{es} has built-in protections against accidental data loss and
+corruption. However, there's nothing to stop deliberate tampering or data
+interception. The {stack-security-features} use TLS to preserve the _integrity_
+of your data against tampering, while also providing _confidentiality_ by
+encrypting communications to, from, and within the cluster. For even	greater
+protection, you can increase the <<ciphers,encryption strength>>.
+
+See <<configuring-stack-security,Configure security for the Elastic Stack>>.
+
+[discrete]
+[[maintaining-audit-trail]]
+== Maintaining an audit trail
+
+Keeping a system secure takes vigilance. By using {stack-security-features} to
+maintain an audit trail, you can easily see who is accessing your cluster and
+what they're doing. You can configure the audit level, which accounts for the
+type of events that are logged. These events include failed authentication
+attempts, user access denied, node connection denied, and more. By analyzing
+access patterns and failed attempts to access your cluster, you can gain
+insights into attempted attacks and data breaches. Keeping an auditable log of
+the activity in your cluster can also help diagnose operational issues.
+
+See <<enable-audit-logging,Enable audit logging>>.
 
-include::overview.asciidoc[]
+--
 
-include::configuring-es.asciidoc[]
+include::configuring-stack-security.asciidoc[]
 
-include::authentication/index.asciidoc[]
+include::authentication/overview.asciidoc[]
 
-include::authorization/index.asciidoc[]
+include::authorization/overview.asciidoc[]
 
 include::auditing/index.asciidoc[]
 
-include::securing-communications/index.asciidoc[]
-
 include::using-ip-filtering.asciidoc[]
 
 include::ccs-clients-integrations/index.asciidoc[]
 
 include::operator-privileges/index.asciidoc[]
 
-include::get-started-security.asciidoc[]
-
-include::securing-communications/tutorial-tls-intro.asciidoc[]
-
 include::troubleshooting.asciidoc[]
 
 include::limitations.asciidoc[]

x-pack/docs/en/security/overview.asciidoc

@@ -1,75 +0,0 @@
-[role="xpack"]
-[[elasticsearch-security]]
-== Security overview
-++++
-<titleabbrev>Overview</titleabbrev>
-++++
-
-An {es} cluster is typically made out of many moving parts. There are the {es}
-nodes that form the cluster and often {ls} instances, {kib} instances, Beats
-agents, and clients all communicating with the cluster. It should not come as a
-surprise that securing such clusters has many facets and layers.
-
-Security protects {es} clusters by:
-
-* <<preventing-unauthorized-access, Preventing unauthorized access>>
-  with password protection, role-based access control, and IP filtering.
-* <<preserving-data-integrity, Preserving the integrity of your data>>
-  with SSL/TLS encryption.
-* <<maintaining-audit-trail, Maintaining an audit trail>>
-  so you know who's doing what to your cluster and the data it stores.  
-
-[discrete]
-[[preventing-unauthorized-access]]
-=== Preventing unauthorized access
-
-To prevent unauthorized access to your {es} cluster, you must have a
-way to _authenticate_ users. This simply means that you need a way to validate
-that a user is who they claim to be. For example, you have to make sure only
-the person named _Kelsey Andorra_ can sign in as the user `kandorra`. The
-{es-security-features} provide a standalone authentication mechanism that enables
-you to quickly password-protect your cluster. If you're already using LDAP, 
-Active Directory, or PKI to manage users in your organization, the
-{security-features} are able to integrate with those systems to perform user
-authentication. 
-
-In many cases, simply authenticating users isn't enough. You also need a way to
-control what data users have access to and what tasks they can perform. The
-{es-security-features} enable you to _authorize_ users by assigning access
-_privileges_ to _roles_ and assigning those roles to users. For example, this
-role-based access control mechanism (a.k.a RBAC) enables you to specify that the
-user `kandorra` can only perform read operations on the `events` index and can't
-do anything at all with other indices.
-
-See <<setting-up-authentication>> and <<authorization>>.
-
-The {security-features} also enable you to restrict the nodes and clients that
-can connect to the cluster based on <<ip-filtering,IP filters>>. You can
-block and allow specific IP addresses, subnets, or DNS domains to
-control network-level access to a cluster.
-
-[discrete]
-[[preserving-data-integrity]]
-=== Preserving data integrity
-
-A critical part of security is keeping confidential data confidential.
-{es} has built-in protections against accidental data loss and
-corruption. However, there's nothing to stop deliberate tampering or data
-interception. The {stack-security-features} preserve the integrity of your
-data by encrypting communications to, from, and within the cluster. See
-<<encrypting-communications>>. For even	greater protection, you can increase the
-<<ciphers,encryption strength>>.
-
-[discrete]
-[[maintaining-audit-trail]]
-=== Maintaining an audit trail
-
-Keeping a system secure takes vigilance. By using {stack-security-features} to
-maintain an audit trail, you can easily see who is accessing your cluster and
-what they're doing. You can configure the audit level, which accounts for the
-type of events that are logged. These events include failed authentication
-attempts, user access denied, node connection denied, and more. By analyzing
-access patterns and failed attempts to access your cluster, you can gain
-insights into attempted attacks and data breaches. Keeping an auditable log of
-the activity in your cluster can also help diagnose operational issues. For more
-information, see <<enable-audit-logging>>.

x-pack/docs/en/security/securing-communications/configuring-tls-docker.asciidoc

@@ -10,7 +10,7 @@ HTTPS and transport using the {es} Docker image. The example uses
 Docker Compose to manage the containers.
 
 For further details, see
-<<encrypting-communications>> and
+<<configuring-stack-security>> and
 https://www.elastic.co/subscriptions[available subscriptions].
 
 [discrete]

x-pack/docs/en/security/securing-communications/index.asciidoc

@@ -1,24 +0,0 @@
-[role="xpack"]
-[[encrypting-communications]]
-== Encrypting communications
-
-Elasticsearch nodes store data that may be confidential. Attacks on the data may
-come from the network. These attacks could include sniffing of the data,
-manipulation of the data, and attempts to gain access to the server and thus the
-files storing the data. Securing your nodes helps reduce the risk from
-network-based attacks.
-
-This section shows how to:
-
-* Encrypt traffic to, from and within an Elasticsearch cluster using SSL/TLS,
-* Require nodes to authenticate as they join the cluster using SSL certificates, and
-* Make it more difficult for remote attackers to issue any commands to Elasticsearch.
-
-The authentication of new nodes helps prevent a rogue node from joining the
-cluster and receiving data through replication.
-
-include::setting-up-ssl.asciidoc[]
-include::securing-elasticsearch.asciidoc[]
-include::configuring-tls-docker.asciidoc[]
-include::enabling-cipher-suites.asciidoc[]
-

x-pack/docs/en/security/securing-communications/securing-elasticsearch.asciidoc

@@ -14,22 +14,22 @@ To enable encryption, you need to perform the following steps on each node in
 the cluster:
 
 . Verify that the `xpack.security.enabled` setting is `true`. For more
-information, see <<security-settings>>. 
+information, see <<security-settings>>.
 
 . <<node-certificates, Generate a private key and X.509 certificate>>.
 
 . Configure each node to:
 .. Required: <<tls-transport,Enable TLS on the transport layer>>.
-.. Recommended: <<tls-http,Enable TLS on the HTTP layer>>.
+.. Recommended: <<encrypt-http-communication,Enable TLS on the HTTP layer>>.
 
-. If you are using Active Directory user authentication, 
-<<tls-active-directory,encrypt communications between {es} and your Active Directory server>>. 
+. If you are using Active Directory user authentication,
+<<tls-active-directory,encrypt communications between {es} and your Active Directory server>>.
 
-. If you are using LDAP user authentication, 
-<<tls-ldap,encrypt communications between {es} and your LDAP server>>. 
+. If you are using LDAP user authentication,
+<<tls-ldap,encrypt communications between {es} and your LDAP server>>.
 
 For more information about encrypting communications across the Elastic Stack,
-see <<encrypting-communications>>.
+see <<configuring-stack-security>>.
 
 include::node-certificates.asciidoc[]
 
@@ -39,4 +39,4 @@ include::tls-http.asciidoc[]
 
 include::tls-ad.asciidoc[]
 
-include::tls-ldap.asciidoc[]
+include::tls-ldap.asciidoc[]

x-pack/docs/en/security/securing-communications/security-basic-setup-https.asciidoc

@@ -0,0 +1,596 @@
+[[security-basic-setup-https]]
+=== Set up basic security for the Elastic Stack plus secured HTTPS traffic
+++++
+<titleabbrev>Set up basic security plus HTTPS</titleabbrev>
+++++
+
+In a production environment, some {es} features such as tokens and
+API keys will be disabled unless you enable TLS on the HTTP layer. This
+additional layer of security ensures that all communications to and from your
+cluster are secured.
+
+When you run the `elasticsearch-certutil` tool in `http` mode, the tool asks
+several questions about how you want to generate certificates. While there are
+numerous options, the following choices result in certificates that should
+work for most environments.
+
+[[signing-certificates]]
+.Signing certificates
+****
+The first question that the `elasticsearch-certutil` tool prompts you with is
+whether you want to generate a Certificate Signing Request (CSR). Answer
+`n` if you want to sign your own certificates, or `y` if you want to sign
+certificates with a central CA.
+
+[discrete]
+===== Sign your own certificates
+
+If you want to use the CA that you created when
+<<generate-certificates,Generating the certificate authority>> answer `n` when
+asked if you want to generate a CSR. You then specify the location of your CA,
+which the tool uses to sign and generate a `.p12` certificate. The steps in
+this procedure follow this workflow.
+
+[discrete]
+===== Sign certificates with a central CA
+
+If you work in an environment with a central security team, they can likely
+generate a certificate for you. Infrastructure within your organization
+might already be configured to trust an existing CA, so it may be easier
+for clients to connect to {es} if you use a CSR and send that
+request to the team that controls your CA. To use a central CA, answer `y` to
+the first question.
+****
+
+[[basic-setup-https-prerequisites]]
+==== Prerequisites
+
+Complete all steps in <<security-basic-setup,Set up basic security for the Elastic Stack>>.
+
+[[encrypt-http-communication]]
+==== Encrypt HTTP client communications for {es}
+
+. Stop {es} and {kib} if they are running.
+
+. From the directory where you installed {es}, run the {es}
+   HTTP certificate tool to generate a Certificate Signing Request (CSR).
++
+[source,shell]
+----
+./bin/elasticsearch-certutil http
+----
++
+This command generates a `.zip` file that contains certificates and keys
+to use with {es} and {kib}. Each folder contains a `README.txt`
+explaining how to use these files.
+
+   a. When asked if you want to generate a CSR, enter `n`.
+
+   b. When asked if you want to use an existing CA, enter `y`.
+
+   c. Enter the path to your CA. This is the absolute path to
+   the `elastic-stack-ca.p12` file that you generated for your cluster.
+
+   d. Enter the password for your CA.
+
+   e. Enter an expiration value for your certificate. You can enter the
+   validity period in years, months, or days. For example, enter `90D` for 90
+   days.
+
+   f. When asked if you want to generate one certificate per node, enter `y`.
++
+Each certificate will have its own private key, and will be issued for a
+specific hostname or IP address.
+
+   g. When prompted, enter the name of the first node in your cluster. Use the same node name that you used when <<generate-certificates,generating node certificates>>.
+
+   h. Enter all hostnames used to connect to your first node. These hostnames
+   will be added as DNS names in the Subject Alternative Name (SAN) field in your certificate.
++
+List every hostname and variant used to connect to your cluster over HTTPS.
+
+   i. Enter the IP addresses that clients can use to connect to your node.
+
+   j. Repeat these steps for each additional node in your cluster.
+
+. After generating a certificate for each of your nodes, enter a password for
+   your private key when prompted.
+
+. Unzip the generated `elasticsearch-ssl-http.zip` file. This compressed file
+   contains one directory for both {es} and {kib}.
++
+--
+[source,txt]
+----
+/elasticsearch
+|_ README.txt
+|_ http.p12
+|_ sample-elasticsearch.yml
+----
+
+[source,txt]
+----
+/kibana
+|_ README.txt
+|_ elasticsearch-ca.pem
+|_ sample-kibana.yml
+----
+--
+
+. Copy the relevant `http.p12` certificate to the `ES_PATH_CONF` directory on each node.
+
+. On each node, edit the `elasticsearch.yml` file to enable HTTPS security and
+   specify the location of the `http.p12` security certificate.
++
+[source,yaml]
+----
+xpack.security.http.ssl.enabled: true
+xpack.security.http.ssl.keystore.path: http.p12
+----
+
+. Add the password for your private key to the secure settings in {es}.
++
+[source,shell]
+----
+./bin/elasticsearch-keystore add xpack.security.http.ssl.keystore.secure_password
+----
+
+. Start {es}.
+
+**Next**: <<encrypt-kibana-http,Encrypt HTTP client communications for {kib}>>
+
+[[encrypt-kibana-http]]
+==== Encrypt HTTP client communications for {kib}
+
+Browsers send traffic to {kib} and {kib} sends traffic to {es}.
+These communication channels are configured separately to use TLS. You encrypt
+traffic between your browser and {kib}, and then encrypt traffic between
+{kib} and {es}.
+
+[[encrypt-kibana-elasticsearch]]
+===== Encrypt traffic between {kib} and {es}
+
+When you ran the `elasticsearch-certutil` tool with the `http` option, it
+created a `/kibana` directory containing an `elasticsearch-ca.pem` file. You
+use this file to configure {kib} to trust the {es} CA for the HTTP
+layer.
+
+1. Copy the `elasticsearch-ca.pem` 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/elasticsearch-ca.pem
+----
+
+3. Add the following line to specify the HTTPS URL for your {es}
+cluster.
++
+[source,yaml]
+----
+elasticsearch.hosts: https://<your_elasticsearch_host>.com:9200
+----
+
+4. Restart {kib}.
+
+.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.
+****
+
+**Next**: <<encrypt-kibana-browser,Encrypt traffic between your browser and {kib}>>
+
+[[encrypt-kibana-browser]]
+===== Encrypt traffic between your browser and {kib}
+
+You create a server certificate and private key for {kib}. {kib} uses this
+server certificate and corresponding private key when receiving connections
+from web browsers.
+
+When you obtain a server certificate, you must set its subject alternative
+name (SAN) correctly to ensure that browsers 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, pick whichever attribute you'll use to
+connect to {kib} in your browser, which is likely the FQDN.
+
+The following instructions create a Certificate Signing Request (CSR) for {kib}.
+A CSR contains information that a CA uses to generate and sign a security
+certificate. The certificate can be trusted (signed by a public, trusted CA)
+or untrusted (signed by an internal CA). A self-signed or internally-signed
+certificate is acceptable for development environments and building a proof of
+concept, but should not be used in a production environment.
+
+WARNING: Before going to production, use a trusted CA such as https://letsencrypt.org/[Let's
+Encrypt] or your organization's internal CA to sign the certificate. Using a
+signed certificate establishes browser trust for connections to {kib} for
+internal access or on the public internet.
+
+. Generate a server certificate and private key for {kib}.
++
+[source,shell]
+----
+./bin/elasticsearch-certutil csr -name kibana-server -dns example.com,www.example.com
+----
++
+The CSR has a common name (CN) of `kibana-server`, a SAN of `example.com`,
+and another SAN of `www.example.com`.
++
+This command generates a `csr-bundle.zip` file by default with the following
+contents:
++
+[source,txt]
+----
+/kibana-server
+|_ kibana-server.csr
+|_ kibana-server.key
+----
+
+. Unzip the `csr-bundle.zip` file to obtain the `kibana-server.csr` unsigned
+security certificate and the `kibana-server.key` unencrypted private key.
+
+. Send the `kibana-server.csr` certificate signing request to your internal
+CA or trusted CA for signing to obtain a signed certificate. The signed file
+can be in different formats, such as a `.crt` file like `kibana-server.crt`.
+
+. Open `kibana.yml` and add the following lines to configure {kib} to access
+the server certificate and unencrypted private key.
++
+[source,yaml]
+----
+server.ssl.certificate: KBN_PATH_CONF/kibana-server.crt
+server.ssl.key: KBN_PATH_CONF/kibana-server.key
+----
++
+NOTE: `KBN_PATH_CONF` contains the path for the {kib} configuration files. If
+you installed {kib} using archive distributions (`zip` or `tar.gz`), the
+path defaults to `KBN_HOME/config`. If you used package distributions
+(Debian or RPM), the path defaults to `/etc/kibana`.
+
+. Add the following line to `kibana.yml` to enable TLS for inbound
+connections.
++
+[source,yaml]
+----
+server.ssl.enabled: true
+----
+
+. Start {kib}.
+
+NOTE: After making these changes, you must always access {kib} via HTTPS. For
+example, `https://<your_kibana_host>.com`.
+
+**Next**: <<configure-beats-security,Configure {beats} security>>
+
+[[configure-beats-security]]
+==== Configure {beats} security
+
+The {beats} are open source data shippers that you install as agents on your
+servers to send operational data to {es}. Each Beat is a separately
+installable product. The following steps cover configuring security for
+{metricbeat}. Follow these steps for each https://www.elastic.co/guide/en/elastic-stack-get-started/7.9/get-started-elastic-stack.html#install-beats[additonal Beat] you want to configure security for.
+
+===== Prerequisites
+
+https://www.elastic.co/guide/en/beats/metricbeat/7.9/metricbeat-installation-configuration.html[Install {metricbeat}] using your preferred method.
+
+NOTE: You cannot connect to the Elastic Stack or set up assets for {metricbeat}
+before completing the following steps.
+
+===== Create roles for {metricbeat}
+Typically, you need to create the following separate roles:
+
+- **setup** role for setting up index templates and other dependencies
+- **monitoring** role for sending monitoring information
+- **writer** role for publishing events collected by Metricbeat
+- **reader** role for Kibana users who need to view and create visualizations that access Metricbeat data
+
+NOTE: These instructions assume that you are using the default name for
+{metricbeat} indices. If the indicated index names are not listed, or you are
+using a custom name, enter it manually when defining roles and modify the
+privileges to match your index naming pattern.
+
+To create users and roles from Stack Management in {kib}, select **Roles**
+or **Users** from the side navigation.
+
+**Next**: <<beats-setup-role,Create a setup role>>
+
+[discrete]
+[[beats-setup-role]]
+====== Create a setup role and user
+
+Administrators who set up {metricbeat} typically need to load mappings,
+dashboards, and other objects used to index data into {es} and visualize it in
+{kib}.
+
+WARNING: Setting up {metricbeat} is an admin-level task that requires extra
+privileges. As a best practice, grant the setup role to administrators only,
+and use a more restrictive role for event publishing.
+
+1. Create the setup role:
+
+   a. Enter **metricbeat_setup** as the role name.
+
+   b. Choose the **monitor** and **manage_ilm** cluster privileges.
+
+   c. On the **metricbeat-\*** indices, choose the **manage** and **write**
+   privileges.
++
+If the **metricbeat-\*** indices aren't listed, enter that pattern into the
+list of indices.
+
+2. Create the setup user:
+
+   a. Enter **metricbeat_setup** as the user name.
+
+   b. Enter the username, password, and other user details.
+
+   c. Assign the following roles to the **metricbeat_setup** user:
++
+[cols="1,1"]
+|===
+| Role               | Purpose
+
+| `metricbeat_setup` | Set up {metricbeat}.
+| `kibana_admin`     | Load dependencies, such as example dashboards, if available, into {kib}
+| `ingest_admin`     | Set up index templates and, if available, ingest pipelines
+| `beats_admin`      | Enroll and manage configurations in {beats} central management
+|===
+
+**Next**: <<beats-monitoring-role,Create a monitoring role>>
+
+[discrete]
+[[beats-monitoring-role]]
+====== Create a monitoring role and user
+
+To send monitoring data securely, create a monitoring user and grant it the
+necessary privileges.
+
+You can use the built-in `beats_system` user, if it’s available in your
+environment. Because the built-in users are not available in Elastic Cloud,
+these instructions create a user that is explicitly used for monitoring
+{metricbeat}.
+
+1. Create the monitoring role:
+
+   a. Enter **metricbeat_monitoring** as the role name.
+
+   b. Choose the **monitor** cluster privilege.
+
+   c. On the **.monitoring-beats-\*** indices, choose the **create_index** and
+   **create_doc** privileges.
+
+2. Create the monitoring user:
+
+   a. Enter **metricbeat_monitoring** as the user name.
+
+   b. Enter the username, password, and other user details.
+
+   c. Assign the following roles to the **metricbeat_monitoring** user:
++
+[cols="1,1"]
+|===
+| Role                    | Purpose
+
+| `metricbeat_monitoring` | Monitor {metricbeat}.
+| `kibana_admin`          | Use {kib}
+| `monitoring_user`       | Use Stack Monitoring in {kib} to monitor {metricbeat}
+|===
+
+**Next**: <<beats-writer-role,Create a writer role>>
+
+[discrete]
+[[beats-writer-role]]
+====== Create a writer role and user
+
+Users who publish events to {es} need to create and write to {metricbeat} indices. To minimize the privileges required by the writer role, use the setup role to pre-load dependencies. This section assumes that you’ve
+<<beats-setup-role,created the setup role>>.
+
+1. Create the writer role:
+
+   a. Enter **metricbeat_writer** as the role name.
+
+   b. Choose the **monitor** and **read_ilm** cluster privileges.
+
+   c. On the **metricbeat-\*** indices, choose the **create_doc**, **create_index**, and **view_index_metadata** privileges.
+
+2. Create the writer user:
+
+   a. Enter **metricbeat_writer** as the user name.
+
+   b. Enter the username, password, and other user details.
+
+   c. Assign the following roles to the **metricbeat_writer** user:
++
+[cols="1,1"]
+|===
+| Role                          | Purpose
+
+| `metricbeat_writer`           | Monitor {metricbeat}
+| `remote_monitoring_collector` | Collect monitoring metrics from {metricbeat}
+| `remote_monitoring_agent`     | Send monitoring data to the monitoring cluster
+|===
+
+**Next**: <<beats-reader-role,Create a reader role>>
+
+[discrete]
+[[beats-reader-role]]
+====== Create a reader role and user
+
+{kib} users typically need to view dashboards and visualizations that contain
+{metricbeat} data. These users might also need to create and edit dashboards
+and visualizations. Create the reader role to assign proper privileges to these
+users.
+
+1. Create the reader role:
+
+   a. Enter **metricbeat_reader** as the role name.
+
+   b. On the **metricbeat-\*** indices, choose the **read** privilege.
+
+   c. Under **Kibana**, click **Add Kibana privilege**.
+
+   - Under **Spaces**, choose **Default**.
+
+   - Choose **Read** or **All** for Discover, Visualize, Dashboard, and Metrics.
+
+2. Create the reader user:
+
+   a. Enter **metricbeat_reader** as the user name.
+
+   b. Enter the username, password, and other user details.
+
+   c. Assign the following roles to the **metricbeat_reader** user:
++
+[cols="1,1"]
+|===
+| Role                          | Purpose
+
+| `metricbeat_reader` | Read {metricbeat} data.
+| `monitoring_user`   | Allow users to monitor the health of {metricbeat}
+itself. Only assign this role to users who manage {metricbeat}
+| `beats_admin`       | Create and manage configurations in {beats} central
+management. Only assign this role to users who need to use {beats} central
+management.
+|===
+
+**Next**: <<configure-metricbeat-tls,Configure {metricbeat} to use TLS>>
+
+[discrete]
+[[configure-metricbeat-tls]]
+===== Configure {metricbeat} to use TLS
+
+Before starting {metricbeat}, you configure the connections to {es} and
+Kibana. You can configure authentication to send data to your secured cluster
+using basic authentication, API key authentication, or Public Key
+Infrastructure (PKI) certificates.
+
+The following instructions use the credentials for the `metricbeat_writer`
+and `metricbeat_setup` users that you created. If you need a greater level of
+security, we recommend using PKI certificates.
+
+After configuring connections to Elasticsearch and Kibana, you'll enable the
+`elasticsearch-xpack` module and configure that module to use HTTPS.
+
+WARNING: In production environments, we strongly recommend using a separate
+cluster (referred to as the monitoring cluster) to store your data. Using a
+separate monitoring cluster prevents production cluster outages from impacting
+your ability to access your monitoring data. It also prevents monitoring
+activities from impacting the performance of your production cluster.
+
+. From the directory where you installed Elasticsearch, navigate to the
+`/kibana` directory that you created when <<encrypt-http-communication,encrypting HTTP client communications for {es}>>.
+
+. Copy the `elasticsearch-ca.pem` certificate to the directory where you
+installed Metricbeat.
+
+. Open the `metricbeat.yml` configuration file and configure the connection
+to Elasticsearch.
++
+Under `output.elasticsearch`, specify the following fields:
++
+[source,yaml]
+----
+output.elasticsearch:
+ hosts: ["<your_elasticsearch_host>:9200"]
+ protocol: "https"
+ username: "metricbeat_writer"
+ password: "<password>"
+ ssl:
+   certificate_authorities: ["elasticsearch-ca.pem"]
+   verification_mode: "certificate"
+----
+
+   `hosts`:: Specifies the host where your Elasticsearch cluster is running.
+
+   `protocol`:: Indicates the protocol to use when connecting to Elasticsearch.
+   This value must be `https`.
+
+   `username`:: Name of the user with privileges required to publish events to
+   Elasticsearch. The `metricbeat_writer` user that you created has these
+   privileges.
+
+   `password`:: Password for the indicated `username`.
+
+   `certificate_authorities`:: Indicates the path to your trusted CA.
+
+. Configure the connection to Kibana.
++
+Under `setup.kibana`, specify the following fields:
++
+[source,yaml]
+----
+setup.kibana
+ host: "https://<your_elasticsearch_host>:5601"
+ ssl.enabled: true
+ username: "metricbeat_setup"
+ password: "p@ssw0rd"
+----
+
+   `hosts`:: The URLs of the Elasticsearch instances to use for all your
+   queries. Ensure that you include `https` in the URL.
+
+   `username`:: Name of the user with privileges required to set up dashboards in Kibana. The `metricbeat_setup` user that you created has these privileges.
+
+   `password`:: Password for the indicated `username`.
+
+. Enable the `elasticsearch-xpack` module.
++
+[source,shell]
+----
+./metricbeat modules enable elasticsearch-xpack
+----
+
+. Modify the `elasticsearch-xpack` module to use HTTPS.
++
+Open `/modules.d/elasticsearch-xpack.yml` and specify the following fields:
++
+[source,yaml]
+----
+- module: elasticsearch
+ xpack.enabled: true
+ period: 10s
+ hosts: ["https://<your_elasticsearch_host>:9200"]
+ username: "remote_monitoring_user"
+ password: "<password>"
+----
+
+   `hosts`:: Specifies the host where your Elasticsearch cluster is running.
+   Ensure that you include `https` in the URL.
+
+   `username`:: Name of the user with privileges to collect metric data. The
+   built-in `monitoring_user` user has these privileges. Alternatively,
+   you can create a user and assign it the `monitoring_user` role.
+
+   `password`:: Password for the indicated `username`.
+
+. If you want to use the predefined assets for parsing, indexing, and
+   visualizing your data, run the following command to load these assets:
++
+[source,shell]
+----
+./metricbeat setup -e
+----
+
+. Start Elasticsearch, and then start Metricbeat.
++
+[source,shell]
+----
+/.metricbeat -e
+----
++
+`-e` is optional and sends output to standard error instead of the configured
+log output.
+
+. Log in to Kibana, open the main menu, and click **Stack Monitoring**.
++
+You’ll see cluster alerts that require your attention and a summary of the available monitoring metrics for Elasticsearch. Click any of the header links on the available cards to view additional information.

x-pack/docs/en/security/securing-communications/security-basic-setup.asciidoc

@@ -0,0 +1,184 @@
+[[security-basic-setup]]
+=== Set up basic security for the Elastic Stack
+++++
+<titleabbrev>Set up basic security</titleabbrev>
+++++
+
+After adding password protection in the <<security-minimal-setup,minimal security configuration>>, you'll need to configure Transport Layer Security
+(TLS). The transport layer handles all internal communication between nodes in
+your cluster.
+
+The transport layer relies on mutual TLS for both encryption and
+authentication of nodes. Correctly applying TLS ensures that a malicious node
+cannot join the cluster and exchange data with other nodes. While implementing
+username and password authentication at the HTTP layer is useful for securing a
+local cluster, the security of communication between nodes requires TLS.
+
+Configuring TLS between nodes is the basic security setup to prevent
+unauthorized nodes from accessing to your cluster.
+
+.Understanding transport contexts
+****
+Transport Layer Security (TLS) is the name of an industry standard protocol for
+applying security controls (such as encryption) to network communications. TLS
+is the modern name for what used to be called Secure Sockets Layer (SSL). The
+{es} documentation uses the terms TLS and SSL interchangeably.
+
+Transport Protocol is the name of the protocol that {es} nodes use to
+communicate with one another. This name is specific to {es} and distinguishes
+the transport port (default `9300`) from the HTTP port (default `9200`). Nodes
+communicate with one another using the transport port, and REST clients
+communicate with {es} using the HTTP port.
+
+Although the word _transport_ appears in both contexts, they mean different
+things. It's possible to apply TLS to both the {es} transport port and the HTTP
+port. We know that these overlapping terms can be confusing, so to clarify, in
+this scenario we're applying TLS to the {es} transport port. In
+<<security-basic-setup-https,the next scenario>>, we'll apply TLS to the {es}
+HTTP port.
+****
+
+[[basic-setup-prerequisites]]
+==== Prerequisites
+
+Complete the steps in <<security-minimal-setup,Minimal security for the Elastic Stack>> to enable {es} security features on every node in your cluster. You can
+then encrypt communications between your nodes with TLS.
+
+NOTE: You only need to create passwords for the built-in users one time for the
+entire cluster.
+
+[[generate-certificates]]
+==== Generate the certificate authority
+
+You can add as many nodes as you want in a cluster but they must be able to
+communicate with each other. The communication between nodes in a cluster is
+handled by the transport module. To secure your cluster, you must ensure that
+internode communications are encrypted and verified, which is achieved with
+mutual TLS.
+
+In a secured cluster, {es} nodes use certificates to identify
+themselves when communicating with other nodes.
+
+The cluster must validate the authenticity of these certificates. The
+recommended approach is to trust a specific certificate authority (CA). When
+nodes are added to your cluster they must use a certificate signed by the same
+CA.
+
+For the transport layer, we recommend using a separate, dedicated CA instead
+of an existing, possibly shared CA so that node membership is tightly controlled. Use the `elasticsearch-certutil` tool to
+generate a CA for your cluster.
+
+. Use the `elasticsearch-certutil` tool to generate a CA for your cluster.
++
+[source,shell]
+----
+./bin/elasticsearch-certutil ca
+----
+
+   a. When prompted, accept the default file name, which is `elastic-stack-ca.p12`. This file contains the public certificate for your CA and the private key used to sign certificates for each node.
+
+   b. Enter a password for your CA. You can choose to leave the password blank
+   if you're not deploying to a production environment.
+
+. Generate a certificate and private key for your node. You include the
+   `elastic-stack-ca.p12` output file that you generated in the previous step.
++
+[source,shell]
+----
+./bin/elasticsearch-certutil cert --ca elastic-stack-ca.p12
+----
+
+   a. Enter the password for your CA, or press *Enter* if you did not configure one in the previous step.
+
+   b. Create a password for the certificate and accept the default file name.
++
+The output file is a keystore named `elastic-certificates.p12`. This file
+contains a node certificate, node key, and CA certificate.
++
+   `--ca <ca_file>`:: Name of the CA file used to sign your certificates. The
+   default file name from the `elasticsearch-certutil` tool is `elastic-stack-ca.p12`.
+
+. Copy the `elastic-certificates.p12` file to the `ES_PATH_CONF`
+   directory on every node in your cluster.
+
+*Next*: <<encrypt-internode-communication>>
+
+[[encrypt-internode-communication]]
+==== Encrypt internode communications with TLS
+
+The transport networking layer is used for internal communication between
+nodes in a cluster. When security features are enabled, you must use TLS to
+ensure that communication between the nodes is encrypted.
+
+Now that you've generated a certificate authority and certificates, you'll
+update your cluster to use these files.
+
+NOTE: Complete the following steps for each node in your cluster. To join the
+same cluster, all nodes must share the same `cluster.name` value.
+
+.  Open the `ES_PATH_CONF/elasticsearch.yml` file and make the following
+changes:
+
+   a. Add the `cluster-name` setting and enter a name for your cluster:
++
+[source,yaml]
+----
+cluster.name: my-cluster
+----
+
+b. Add the `node.name` setting and enter the name of the certificate that
+you generated for this node. For simplicity, it's good practice for this value
+to match the certificate name that you defined in your `certificates.yaml` file:
++
+[source,yaml]
+----
+node.name: node-1
+----
+
+c. Add the following settings to enable internode communication and provide
+access to the node's certificate:
++
+[source,yaml]
+----
+xpack.security.transport.ssl.enabled: true
+xpack.security.transport.ssl.verification_mode: certificate
+xpack.security.transport.ssl.client_authentication: required
+xpack.security.transport.ssl.keystore.path: <node-name>.p12
+xpack.security.transport.ssl.truststore.path: <node-name>.p12
+----
+
+.  If you entered a password when creating the node certificate, run the following commands to store the password in the {es} keystore:
++
+--
+[source,shell]
+----
+./bin/elasticsearch-keystore add xpack.security.transport.ssl.keystore.secure_password
+----
+
+[source,shell]
+----
+./bin/elasticsearch-keystore add xpack.security.transport.ssl.truststore.secure_password
+----
+--
+
+.  Complete the previous steps for each node in your cluster.
+
+.  Restart {es}. The method for <<starting-elasticsearch,starting>> and <<starting-elasticsearch,stopping>> {es} varies depending on how you installed it.
++
+For example, if you installed {es} with an archive distribution
+(`tar.gz` or `.zip`), you can enter `Ctrl+C` on the command line to stop
+{es}.
++
+WARNING: You must perform a full cluster restart. Nodes that are configured to
+use TLS for transport cannot communicate with nodes that use unencrypted transport connection (and vice-versa).
+
+[[encrypting-internode-whatsnext]]
+==== What's next?
+
+Congratulations! You've encrypted communications between the nodes in your
+cluster and can pass the
+<<bootstrap-checks-tls,TLS bootstrap check>>.
+
+To add another layer of security, <<security-basic-setup-https,Set up basic security for the Elastic Stack plus secured HTTPS traffic>>. In addition to
+configuring TLS on the transport interface of your {es} cluster, you configure
+TLS on the HTTP interface for both {es} and {kib}.

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

@@ -0,0 +1,149 @@
+[[security-minimal-setup]]
+=== Set up minimal security for {es}
+++++
+<titleabbrev>Set up minimal security</titleabbrev>
+++++
+
+You enable the Elasticsearch 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.
+
+==== Prerequisites
+
+. Install and configure {es} and {kib}. See https://www.elastic.co/guide/en/elastic-stack-get-started/current/get-started-elastic-stack.html[Getting started with the Elastic Stack].
+
+. Verify that you are using a license that includes the specific security
+features you want.
++
+The basic license includes minimal security settings for the Elastic Stack, so
+you can just download the distribution and get to work. You can also enable a
+free trial license to access all features of the Elastic Stack. See https://www.elastic.co/subscriptions[subscriptions] and https://www.elastic.co/guide/en/kibana/current/managing-licenses.html[license management].
+
+==== Enable {es} security features
+
+When you use the basic license, the {es} security features are disabled by
+default. Enabling the {es} security features enables basic authentication so
+that you can run a local cluster with username and password authentication.
+
+. Stop both {kib} and {es} if they are running.
+
+. 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`.
+
+[[security-create-builtin-users]]
+==== Create 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
+user name and password are rejected.
+
+NOTE: You only need to set passwords for the `elastic` and `kibana_system` users
+when enabling minimal or basic security.
+
+. Start Elasticsearch. For example, if you installed Elasticsearch with a
+`.tar.gz` package, run the following command from the Elasticsearch directory:
++
+[source,shell]
+----
+./bin/elasticsearch
+----
+
+. In another terminal window, set the passwords for the built-in users by
+running the `elasticsearch-setup-passwords` utility. Using the `auto` parameter
+outputs randomly-generated passwords to the console that you can change later
+if necessary:
++
+[source,shell]
+----
+./bin/elasticsearch-setup-passwords 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-setup-passwords interactive
+----
+
+. Save the generated passwords. You'll need them to add the built-in user to
+{kib}.
+
+WARNING: After you set a password for the `elastic` user, you cannot run the
+`elasticsearch-setup-passwords` command a second time.
+
+*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.
+
+{kib} also performs some background tasks that require use of the built-in
+`elastic` user.
+
+You'll configure {kib} to use the built-in `elastic` user and the
+password that you created earlier.
+
+. Add the `elasticsearch.username` setting to the `KIB_PATH_CONF/kibana.yml`
+file and set the value to the `elastic` user:
++
+[source,yaml]
+----
+elasticsearch.username: "elastic"
+----
++
+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 `elastic` user to the {kib} keystore:
++
+[source,shell]
+----
+./bin/kibana-keystore add elasticsearch.password
+----
++
+When prompted, enter the password for the `elastic` 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.
+
+[[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.
+
+To add another layer of security, <<security-basic-setup,Set up basic security for the Elastic Stack>>. You'll configure Transport Layer Security (TLS) to
+secure all internal communication between nodes in your cluster.

x-pack/docs/en/security/securing-communications/setting-up-ssl.asciidoc

@@ -1,37 +0,0 @@
-[[ssl-tls]]
-=== Setting up TLS on a cluster
-
-The {stack} {security-features} enable you to encrypt traffic to, from, and
-within your {es} cluster. Connections are secured using Transport Layer Security
-(TLS), which is commonly referred to as "SSL".
-
-WARNING: Clusters that do not have encryption enabled send all data in plain text
-including passwords. If the {es} {security-features} are enabled, unless you have a trial license, you must configure SSL/TLS for internode-communication.
-
-The following steps describe how to enable encryption across the various
-components of the {stack}. You must perform each of the steps that are
-applicable to your cluster.
-
-. Generate a private key and X.509 certificate for each of your {es} nodes. See
-<<node-certificates>>.
-
-. Configure each node in the cluster to identify itself using its signed
-certificate and enable TLS on the transport layer. You can also optionally
-enable TLS on the HTTP layer. See
-<<tls-transport>> and
-<<tls-http>>.
-
-. Configure the {monitor-features} to use encrypted connections. See <<secure-monitoring>>.
-
-. Configure {kib} to encrypt communications between the browser and
-the {kib} server and to connect to {es} via HTTPS. See
-{kibana-ref}/using-kibana-with-security.html[Configuring security in {kib}].
-
-. Configure Logstash to use TLS encryption. See
-{logstash-ref}/ls-security.html[Configuring security in {ls}].
-
-. Configure Beats to use encrypted connections. For example, see
-{filebeat-ref}/securing-filebeat.html[Configure {filebeat} to use {security-features}].
-
-. Configure {es} for Apache Hadoop to use secured transport. See
-{hadoop-ref}/security.html[{es} for Apache Hadoop Security].

x-pack/docs/en/security/securing-communications/tutorial-tls-addnodes.asciidoc

@@ -14,7 +14,7 @@ Let's add two nodes to our cluster!
 nodes using a shared installation. In this tutorial, however, we're keeping
 things simple by using the `zip` or `tar.gz` packages and by putting each copy
 in a separate folder. You can simply repeat the steps that you used to install
-{es} in the 
+{es} in the
 {stack-gs}/get-started-elastic-stack.html#install-elasticsearch[Getting started with the {stack}]
 tutorial.
 
@@ -29,7 +29,7 @@ For example, run the following command:
 --ca elastic-stack-ca.p12 \ <1>
 --multiple
 ----------------------------------------------------------------------
-<1> Use the certificate authority that you created in <<encrypting-communications-certificates>>.
+<1> Use the certificate authority that you created in <<generate-certificates>>.
 
 You are prompted for information about each new node. Specify `node-2` and
 `node-3` for the instance names. For the purposes of this tutorial, specify the
@@ -47,15 +47,15 @@ which contains the generated certificates and keys.
 --
 ["source","sh",subs="attributes,callouts"]
 ----------------------------------------------------------------------
-unzip certificate-bundle.zip 
+unzip certificate-bundle.zip
 
 Archive:  certificate-bundle.zip
    creating: node-2/
-  inflating: node-2/node-2.p12       
+  inflating: node-2/node-2.p12
    creating: node-3/
-  inflating: node-3/node-3.p12   
+  inflating: node-3/node-3.p12
 ----------------------------------------------------------------------
-  
+
 The `certificate-bundle.zip` file contains a folder for each of your nodes. Each
 folder contains a single PKCS#12 keystore that includes a node certificate,
 node key, and CA certificate.
@@ -165,10 +165,10 @@ node:
 [source,console]
 ----------------------------------
 GET _cat/nodes?v=true
----------------------------------- 
+----------------------------------
 
 The node that has an asterisk(*) in the `master` column is the elected master
-node. 
+node.
 --
 
 Now that you have multiple nodes, your data can be distributed across the
@@ -181,7 +181,7 @@ concepts of clusters, nodes, and shards, see
 === What's next?
 
 Congratulations! You've encrypted communications between the nodes in your
-cluster and can pass the 
+cluster and can pass the
 <<bootstrap-checks-tls,TLS bootstrap check>>.
 
 If you want to encrypt communications between other products in the {stack}, see

x-pack/docs/en/security/troubleshooting.asciidoc

@@ -79,7 +79,7 @@ jacknich       : monitoring,unknown_role* <1>
 ------------------------------------------
 <1> `unknown_role` was not found in `roles.yml`
 
-For more information about this command, see the 
+For more information about this command, see the
 <<users-command,`elasticsearch-users` command>>.
 --
 
@@ -211,7 +211,7 @@ below with tips on how to resolve these issues.
 Indicates that a client connection was made to `node01.example.com` but the
 certificate returned did not contain the name `node01.example.com`. In most
 cases, the issue can be resolved by ensuring the name is specified during
-certificate creation. For more information, see <<ssl-tls>>. Another scenario is
+certificate creation. For more information, see <<encrypt-internode-communication>>. Another scenario is
 when the environment does not wish to use DNS names in certificates at all. In
 this scenario, all settings in `elasticsearch.yml` should only use IP addresses
 including the `network.publish_host` setting.
@@ -225,7 +225,7 @@ certificate did not contain any `SubjectAlternativeName` entries. IP addresses
 are only used for hostname verification if they are specified as a
 `SubjectAlternativeName` during certificate creation. If the intent was to use
 IP addresses for hostname verification, then the certificate will need to be
-regenerated with the appropriate IP address. See <<ssl-tls>>.
+regenerated with the appropriate IP address. See <<encrypt-internode-communication>>.
 --
 
 `javax.net.ssl.SSLHandshakeException: null cert chain` and `javax.net.ssl.SSLException: Received fatal alert: bad_certificate`::
@@ -253,7 +253,7 @@ certificate.
 --
 The `Invalid ECDH ServerKeyExchange signature` can indicate that a key and a corresponding certificate don't match and are
 causing the handshake to fail.
-Verify the contents of each of the files you are using for your configured certificate authorities, certificates and keys. In particular, check that the key and certificate belong to the same key pair. 
+Verify the contents of each of the files you are using for your configured certificate authorities, certificates and keys. In particular, check that the key and certificate belong to the same key pair.
 --
 
 [[trb-security-ssl]]
@@ -339,9 +339,9 @@ In this case, you must install the
 
 *Symptoms:*
 
-* User authentication fails due to either GSS negotiation failure 
-or a service login failure (either on the server or in the {es} http client). 
-Some of the common exceptions are listed below with some tips to help resolve 
+* User authentication fails due to either GSS negotiation failure
+or a service login failure (either on the server or in the {es} http client).
+Some of the common exceptions are listed below with some tips to help resolve
 them.
 
 *Resolution:*
@@ -350,21 +350,21 @@ them.
 +
 --
 
-When you see this error message on the HTTP client side, then it may be 
+When you see this error message on the HTTP client side, then it may be
 related to an incorrect password.
 
-When you see this error message in the {es} server logs, then it may be 
-related to the {es} service keytab. The keytab file is present but it failed 
-to log in as the user. Please check the keytab expiry. Also check whether the 
+When you see this error message in the {es} server logs, then it may be
+related to the {es} service keytab. The keytab file is present but it failed
+to log in as the user. Please check the keytab expiry. Also check whether the
 keytab contain up-to-date credentials; if not, replace them.
 
-You can use tools like `klist` or `ktab` to list principals inside 
-the keytab and validate them. You can use `kinit` to see if you can acquire 
-initial tickets using the keytab. Please check the tools and their documentation 
+You can use tools like `klist` or `ktab` to list principals inside
+the keytab and validate them. You can use `kinit` to see if you can acquire
+initial tickets using the keytab. Please check the tools and their documentation
 in your Kerberos environment.
 
 Kerberos depends on proper hostname resolution, so please check your DNS infrastructure.
-Incorrect DNS setup, DNS SRV records or configuration for KDC servers in `krb5.conf` 
+Incorrect DNS setup, DNS SRV records or configuration for KDC servers in `krb5.conf`
 can cause problems with hostname resolution.
 
 --
@@ -375,8 +375,8 @@ can cause problems with hostname resolution.
 +
 --
 
-To prevent replay attacks, Kerberos V5 sets a maximum tolerance for computer 
-clock synchronization and it is typically 5 minutes. Please check whether 
+To prevent replay attacks, Kerberos V5 sets a maximum tolerance for computer
+clock synchronization and it is typically 5 minutes. Please check whether
 the time on the machines within the domain is in sync.
 
 --
@@ -387,10 +387,10 @@ the time on the machines within the domain is in sync.
 +
 --
 
-You would usually see this error message on the client side when using `curl` to 
-test {es} Kerberos setup. For example, these messages occur when you are using 
+You would usually see this error message on the client side when using `curl` to
+test {es} Kerberos setup. For example, these messages occur when you are using
 an old version of curl on the client and therefore Kerberos Spnego support is missing.
-The Kerberos realm in {es} only supports Spengo mechanism (Oid 1.3.6.1.5.5.2); 
+The Kerberos realm in {es} only supports Spengo mechanism (Oid 1.3.6.1.5.5.2);
 it does not yet support Kerberos mechanism (Oid 1.2.840.113554.1.2.2).
 
 Make sure that:
@@ -406,12 +406,12 @@ To download latest curl version visit https://curl.haxx.se/download.html
 
 --
 
-As Kerberos logs are often cryptic in nature and many things can go wrong 
-as it depends on external services like DNS and NTP. You might 
+As Kerberos logs are often cryptic in nature and many things can go wrong
+as it depends on external services like DNS and NTP. You might
 have to enable additional debug logs to determine the root cause of the issue.
 
-{es} uses a JAAS (Java Authentication and Authorization Service) Kerberos login 
-module to provide Kerberos support. To enable debug logs on {es} for the login 
+{es} uses a JAAS (Java Authentication and Authorization Service) Kerberos login
+module to provide Kerberos support. To enable debug logs on {es} for the login
 module use following Kerberos realm setting:
 [source,yaml]
 ----------------
@@ -420,8 +420,8 @@ xpack.security.authc.realms.kerberos.<realm-name>.krb.debug: true
 
 For detailed information, see <<ref-kerberos-settings>>.
 
-Sometimes you may need to go deeper to understand the problem during SPNEGO 
-GSS context negotiation or look at the Kerberos message exchange. To enable 
+Sometimes you may need to go deeper to understand the problem during SPNEGO
+GSS context negotiation or look at the Kerberos message exchange. To enable
 Kerberos/SPNEGO debug logging on JVM, add following JVM system properties:
 
 `-Dsun.security.krb5.debug=true`
@@ -433,13 +433,13 @@ For more information about JVM system properties, see <<jvm-options>>.
 [[trb-security-saml]]
 === Common SAML issues
 
-Some of the common SAML problems are shown below with tips on how to resolve 
+Some of the common SAML problems are shown below with tips on how to resolve
 these issues.
 
 . *Symptoms:*
 +
 --
-Authentication in {kib} fails and the following error is printed in the {es} 
+Authentication in {kib} fails and the following error is printed in the {es}
 logs:
 
 ....
@@ -519,7 +519,7 @@ Cannot find metadata for entity [your:entity.id] in [metadata.xml]
 
 *Resolution:*
 
-We could not find the metadata for the SAML Entity ID `your:entity.id` in the 
+We could not find the metadata for the SAML Entity ID `your:entity.id` in the
 configured metadata file (`metadata.xml`).
 
 .. Ensure that the `metadata.xml` file you are using is indeed the one provided
@@ -527,7 +527,7 @@ by your SAML Identity Provider.
 .. Ensure that the `metadata.xml` file contains one <EntityDescriptor> element
 as follows: `<EntityDescriptor ID="0597c9aa-e69b-46e7-a1c6-636c7b8a8070" entityID="https://saml.example.com/f174199a-a96e-4201-88f1-0d57a610c522/" ...`
 where the value of the `entityID` attribute is the same as the value of the
-`idp.entity_id` that you have set in your SAML realm configuration in 
+`idp.entity_id` that you have set in your SAML realm configuration in
 `elasticsearch.yml`.
 .. Note that these are also compared as case-sensitive strings and not as
 canonicalized URLs even when the values are URL-like.
@@ -712,7 +712,7 @@ PUT /_cluster/settings
 -----------------------------------------------
 
 
-Alternatively, you can add the following lines to the end of the 
+Alternatively, you can add the following lines to the end of the
 `log4j2.properties` configuration file in the `ES_PATH_CONF`:
 
 [source,properties]
@@ -824,28 +824,27 @@ For more information about these settings, see
 
 *Symptoms:*
 
-* Active Directory or LDAP realms might stop working after upgrading to {es} 6.3 
-or later releases. In 6.4 or later releases, you might see messages in the {es} 
-log that indicate a config file is in a deprecated location. 
+* Active Directory or LDAP realms might stop working after upgrading to {es} 6.3
+or later releases. In 6.4 or later releases, you might see messages in the {es}
+log that indicate a config file is in a deprecated location.
 
 *Resolution:*
 
 By default, in 6.2 and earlier releases, the security configuration files are
 located in the `ES_PATH_CONF/x-pack` directory, where `ES_PATH_CONF` is an
-environment variable that defines the location of the 
-<<config-files-location,config directory>>. 
-
-In 6.3 and later releases, the config directory no longer contains an `x-pack` 
-directory. The files that were stored in this folder, such as the 
-`log4j2.properties`, `role_mapping.yml`, `roles.yml`, `users`, and `users_roles` 
-files, now exist directly in the config directory. 
+environment variable that defines the location of the
+<<config-files-location,config directory>>.
 
-IMPORTANT: If you upgraded to 6.3 or later releases, your old security 
-configuration files still exist in an `x-pack` folder. That file path is 
-deprecated, however, and you should move your files out of that folder. 
+In 6.3 and later releases, the config directory no longer contains an `x-pack`
+directory. The files that were stored in this folder, such as the
+`log4j2.properties`, `role_mapping.yml`, `roles.yml`, `users`, and `users_roles`
+files, now exist directly in the config directory.
 
-In 6.3 and later releases, settings such as `files.role_mapping` default to 
-`ES_PATH_CONF/role_mapping.yml`. If you do not want to use the default locations, 
-you must update the settings appropriately. See 
-<<security-settings>>. 
+IMPORTANT: If you upgraded to 6.3 or later releases, your old security
+configuration files still exist in an `x-pack` folder. That file path is
+deprecated, however, and you should move your files out of that folder.
 
+In 6.3 and later releases, settings such as `files.role_mapping` default to
+`ES_PATH_CONF/role_mapping.yml`. If you do not want to use the default locations,
+you must update the settings appropriately. See
+<<security-settings>>.