[DOCS] Update security configuration for security ON by default (#118088

)

* [DOCS] Update security configuration for security ON by default

* Incorporating reviewer feedback + fixing a link

Co-authored-by: Kibana Machine <[email protected]>

docs/user/production-considerations/security-production-considerations.asciidoc

@@ -17,7 +17,10 @@ For more information on {kib}'s security controls, see <<using-kibana-with-secur
 === Enable SSL/TLS
 
 You should use SSL/TLS encryption to ensure that traffic between browsers and the {kib} server cannot be viewed or tampered with by third
-parties. See <<configuring-tls>>.
+parties. See 
+{ref}/security-basic-setup-https.html#encrypt-kibana-http[encrypt HTTP client communications for {kib}].
+
+encrypt-kibana-http
 
 [float]
 [[configuring-kibana-shield]]

docs/user/security/securing-communications/elasticsearch-mutual-tls.asciidoc

@@ -5,36 +5,42 @@
 <titleabbrev>Mutual TLS with {es}</titleabbrev>
 ++++
 
-Secure Sockets Layer (SSL) and Transport Layer Security (TLS) provide encryption for data-in-transit. While these terms are often used
-interchangeably, {kib} supports only TLS, which supersedes the old SSL protocols.
-
-TLS requires X.509 certificates to authenticate the communicating parties and perform encryption of data-in-transit. Each certificate
-contains a public key and has and an associated -- but separate -- private key; these keys are used for cryptographic operations. {kib}
-supports certificates and private keys in PEM or PKCS#12 format.
-
-In a standard TLS configuration, the server presents a signed certificate to authenticate itself to the client. In a mutual TLS
-configuration, the client also presents a signed certificate to authenticate itself to the server.
-
-When {es} {security-features} is enabled on your cluster, each request that {kib} (the client) makes to {es} (the server) must be
-authenticated. Most requests made by end users through {kib} to {es} are authenticated by using the credentials of the logged-in user. There
-are, however, a few internal requests that {kib} needs to make to {es}. For this reason, you must configure credentials for {kib} to use for
-those requests.
-
-If {kib} has `elasticsearch.username` and `elasticsearch.password` configured, it will attempt to use these to authenticate to {es} via the
-{ref}/native-realm.html[native realm]. However, {kib} also supports mutual TLS authentication with {es} via a {ref}/pki-realm.html[Public
-Key Infrastructure (PKI) realm]. To do so, {es} needs to verify the signature on the {kib} client certificate, and it also needs to map the
-client certificate's distinguished name (DN) to the appropriate `kibana_system` role.
-
-NOTE: Using a PKI realm is a gold feature. For a comparison of the Elastic license levels, see https://www.elastic.co/subscriptions[the
-subscription page].
-
-To configure {kib} and {es} to use mutual TLS authentication:
-
-. <<using-kibana-with-security,Set up {kib} to work with {stack} {security-features} with a username and password>>.
-
-. <<configuring-tls-kib-es,Set up TLS encryption between {kib} and {es}>>.
-+
-This entails generating a "server certificate" for {es} to use on the HTTP layer.
+Secure Sockets Layer (SSL) and Transport Layer Security (TLS) provide encryption
+for data-in-transit. While these terms are often used interchangeably, {kib}
+supports only TLS, which supersedes the old SSL protocols.
+
+TLS requires X.509 certificates to authenticate the communicating parties and
+perform encryption of data-in-transit. Each certificate contains a public key
+and has and an associated -- but separate -- private key; these keys are used
+for cryptographic operations. {kib} supports certificates and private keys in
+PEM or PKCS#12 format.
+
+In a standard TLS configuration, the server presents a signed certificate to
+authenticate itself to the client. In a mutual TLS configuration, the client
+also presents a signed certificate to authenticate itself to the server.
+
+{es} {security-features} are enabled on your cluster by default, so each request
+that {kib} (the client) makes to {es} (the server) is authenticated. Most
+requests made by end users through {kib} to {es} are authenticated by using the
+credentials of the logged-in user.
+
+To {ref}/configuring-stack-security.html#stack-start-with-security[enroll {kib} with an {es} cluster], you pass a generated enrollment token. This token 
+configures {kib} to authenticate with {es} using a
+{ref}/service-accounts.html#service-accounts-tokens[service account token].
+{kib} also supports mutual TLS authentication with {es} via a
+{ref}/pki-realm.html[Public Key Infrastructure (PKI) realm]. With this setup,
+{es} needs to verify the signature on the {kib} client certificate, and it also
+needs to map the client certificate's distinguished name (DN) to the appropriate
+`kibana_system` role.
+
+NOTE: Using a PKI realm is a gold feature. For a comparison of the Elastic
+license levels, see https://www.elastic.co/subscriptions[the subscription page].
+
+[discrete]
+==== Configure {kib} and {es} to use mutual TLS authentication
+
+If you haven't already, start {kib} and connect it to {es} using the
+{ref}/configuring-stack-security.html#stack-start-with-security[enrollment token].
 
 . Obtain a client certificate and private key for {kib}.
 +
@@ -43,15 +49,14 @@ This entails generating a "server certificate" for {es} to use on the HTTP layer
 
 NOTE: This is not the same as the <<configuring-tls-browser-kib,server certificate>> that {kib} will present to web browsers.
 
-You may choose to generate a client certificate and private key using the {ref}/certutil.html[`elasticsearch-certutil`] tool. If you
-followed the {es} documentation for {ref}/configuring-tls.html#node-certificates[generating node certificates], then you likely have already
-set up a certificate authority (CA) to sign the {es} server certificate. You may choose to use the same CA to sign the {kib} client
-certificate. For example:
+You may choose to generate a client certificate and private key using the {ref}/certutil.html[`elasticsearch-certutil`] tool. If you followed the {es} documentation for {ref}/security-basic-setup.html#generate-certificates[generating the certificates authority], then you already have a certificate authority (CA) to sign
+the {es} server certificate. You may choose to use the same CA to sign the {kib}
+client certificate. For example:
 
 [source,sh]
---------------------------------------------------------------------------------
+----
 bin/elasticsearch-certutil cert -ca elastic-stack-ca.p12 -name kibana-client -dns <your_kibana_hostname>
---------------------------------------------------------------------------------
+----
 
 This will generate a client certificate and private key in a PKCS#12 file named `kibana-client.p12`. In this example, the client certificate
 has a Common Name (CN) of `"kibana-client"` and a subject alternative name (SAN) of `"<your_kibana_hostname>"`. The SAN may be required if
@@ -67,9 +72,9 @@ If you followed the instructions to generate a client certificate, then you will
 certificate chain from this file. For example:
 
 [source,sh]
---------------------------------------------------------------------------------
+----
 openssl pkcs12 -in kibana-client.p12 -cacerts -nokeys -out kibana-ca.crt
---------------------------------------------------------------------------------
+----
 
 This will produce a PEM-formatted file named `kibana-ca.crt` that contains the CA certificate from the PKCS#12 file.
 --
@@ -81,11 +86,11 @@ By default, {es} provides a native realm for authenticating with a username and
 and a native realm (for end users), you must configure each realm in `elasticsearch.yml`:
 
 [source,yaml]
---------------------------------------------------------------------------------
+----
 xpack.security.authc.realms.pki.realm1.order: 1
 xpack.security.authc.realms.pki.realm1.certificate_authorities: "/path/to/kibana-ca.crt"
 xpack.security.authc.realms.native.realm2.order: 2
---------------------------------------------------------------------------------
+----
 --
 
 . Configure {es} to request client certificates.
@@ -95,9 +100,9 @@ By default, {es} will not request a client certificate when establishing a TLS c
 certificate authentication in `elasticsearch.yml`:
 
 [source,yaml]
---------------------------------------------------------------------------------
+----
 xpack.security.http.ssl.client_authentication: "optional"
---------------------------------------------------------------------------------
+----
 --
 
 . Restart {es}.
@@ -124,16 +129,16 @@ You need to specify the information required to access your client certificate a
 Specify your PKCS#12 file in `kibana.yml`:
 
 [source,yaml]
---------------------------------------------------------------------------------
+----
 elasticsearch.ssl.keystore.path: "/path/to/kibana-client.p12"
---------------------------------------------------------------------------------
+----
 
 If your PKCS#12 file is encrypted, add the decryption password to your <<secure-settings,{kib} keystore>>:
 
 [source,yaml]
---------------------------------------------------------------------------------
+----
 bin/kibana-keystore add elasticsearch.ssl.keystore.password
---------------------------------------------------------------------------------
+----
 
 TIP: If your PKCS#12 file isn't protected with a password, depending on how it was generated, you may need to set
 `elasticsearch.ssl.keystore.password` to an empty string.
@@ -145,17 +150,17 @@ TIP: If your PKCS#12 file isn't protected with a password, depending on how it w
 Specify your certificate and private key in `kibana.yml`:
 
 [source,yaml]
---------------------------------------------------------------------------------
+----
 elasticsearch.ssl.certificate: "/path/to/kibana-client.crt"
 elasticsearch.ssl.key: "/path/to/kibana-client.key"
---------------------------------------------------------------------------------
+----
 
 If your private key is encrypted, add the decryption password to your <<secure-settings,{kib} keystore>>:
 
 [source,yaml]
---------------------------------------------------------------------------------
+----
 bin/kibana-keystore add elasticsearch.ssl.keyPassphrase
---------------------------------------------------------------------------------
+----
 --
 
 . Configure {kib} _not_ to use a username and password for {es}.

docs/user/security/securing-kibana.asciidoc

@@ -5,79 +5,59 @@
 <titleabbrev>Configure security</titleabbrev>
 ++++
 
-{kib} users have to log in when {stack-security-features} are enabled on your
-cluster. You configure roles for your {kib} users to control what data those
-users can access.
+When you start {es} for the first time, {stack-security-features} are enabled on
+your cluster and TLS is configured automatically. The security configuration
+process generates a password for the `elastic` user and an enrollment token for
+{kib}.
+{ref}/configuring-stack-security.html[Start the {stack} with security enabled]
+and then enroll {kib} as part of the configuration process.
 
-Most requests made through {kib} to {es} are authenticated by using the
-credentials of the logged-in user. There are, however, a few internal requests
-that the {kib} server needs to make to the {es} cluster. For this reason, you
-must configure credentials for the {kib} server to use for those requests.
+You can then log in to {kib} as the `elastic` user to create additional roles
+and users.
 
-With {security-features} enabled, if you load a {kib} dashboard that accesses
-data in an index that you are not authorized to view, you get an error that
-indicates the index does not exist. The {security-features} do not currently
-provide a way to control which users can load which dashboards.
+NOTE: When a user is not authorized to view data in an index (such as an {es}
+index), the entire index will be inaccessible and not display in {kib}.
 
-To use {kib} with {security-features}:
+[discrete]
+[[security-configure-settings]]
+=== Configure security settings
 
-. {ref}/configuring-security.html[Configure security in {es}].
-
-. Configure {kib} to use the appropriate built-in user.
-+
---
-Update the following settings in the `kibana.yml` configuration
-file:
-
-[source,yaml]
------------------------------------------------
-elasticsearch.username: "kibana_system"
-elasticsearch.password: "kibanapassword"
------------------------------------------------
-
-The {kib} server submits requests as this user to access the cluster monitoring
-APIs and the `.kibana` index. The server does _not_ need access to user indices.
-
-NOTE: The password for the built-in `kibana_system` user is typically set as part of the security configuration process on {es}. For more
-information, see {ref}/built-in-users.html[Built-in users].
---
+Set an encryption key so that sessions are not invalidated. You can optionally
+configure additional security settings and authentication.
 
 . Set the `xpack.security.encryptionKey` property in the `kibana.yml`
 configuration file. You can use any text string that is 32 characters or longer
 as the encryption key.
 +
 --
 [source,yaml]
---------------------------------------------------------------------------------
+----
 xpack.security.encryptionKey: "something_at_least_32_characters"
---------------------------------------------------------------------------------
+----
 
 For more information, see <<security-settings-kb,Security settings in {kib}>>.
 --
 
-. Configure {kib}'s session expiration settings. Set both the idle timeout and lifespan settings:
-+
---
-[source,yaml]
---------------------------------------------------------------------------------
-xpack.security.session.idleTimeout: "1h"
-xpack.security.session.lifespan: "30d"
---------------------------------------------------------------------------------
-
-For more information, see <<xpack-security-session-management, Session management in {kib}>>.
---
-
-. Optional: <<configuring-tls,Configure {kib} to encrypt communications>>.
+. Optional: <<xpack-security-session-management,Configure {kib}'s session expiration settings>>.
 
 . Optional: <<elasticsearch-mutual-tls,Configure {kib} to authenticate to {es} with a client certificate>>.
 
 . Restart {kib}.
 
-. Temporarily log in to {kib} using the built-in `elastic` superuser so you can create new users and assign roles. If you are running {kib}
-locally, go to `https://localhost:5601` to view the login page.
+[discrete]
+[[security-create-roles]]
+=== Create roles and users
+Configure roles for your {kib} users to control what data those users can
+access.
+
+. Temporarily log in to {kib} using the built-in `elastic` superuser so you can
+create new users and assign roles. If you are running {kib} locally, go to
+`https://localhost:5601` to view the login page.
 +
-NOTE: The password for the built-in `elastic` user is typically set as part of the security configuration process on {es}. For more
-information, see {ref}/built-in-users.html[Built-in users].
+NOTE: The password for the built-in `elastic` user is generated as part of the
+security configuration process on {es}. If you need to reset the password for
+the `elastic` user or other built-in users, run the
+{ref}/reset-password.html[`elasticsearch-reset-password`] tool.
 
 . [[kibana-roles]]Create roles and users to grant access to {kib}.
 +
@@ -120,7 +100,6 @@ NOTE: This must be a user who has been assigned <<kibana-privileges, Kibana priv
 `kibana_system` user) should only be used internally by the {kib} server.
 
 include::authentication/index.asciidoc[]
-include::securing-communications/index.asciidoc[]
 include::securing-communications/elasticsearch-mutual-tls.asciidoc[]
 include::audit-logging.asciidoc[]
 include::access-agreement.asciidoc[]