Review#7: handle more docs comments.

docs/settings/security-settings.asciidoc

@@ -126,7 +126,7 @@ In addition to <<authentication-provider-settings,the settings that are valid fo
 
 | `xpack.security.authc.providers.`
 `saml.<provider-name>.useRelayStateDeepLink`
-| Determines if provider should treat `RelayState` parameter as a deep link in {kib} during Identity Provider initiated login. By default, this setting is set to `false`. The link specified in `RelayState` should be a relative, URL-encoded {kib} URL, e.g. for `/app/dashboards#/list` link `RelayState` parameter would look like this `RelayState=%2Fapp%2Fdashboards%23%2Flist` for .
+| Determines if the provider should treat the `RelayState` parameter as a deep link in {kib} during Identity Provider initiated log in. By default, this setting is set to `false`. The link specified in `RelayState` should be a relative, URL-encoded {kib} URL. For example, the `/app/dashboards#/list` link in `RelayState` parameter would look like this `RelayState=%2Fapp%2Fdashboards%23%2Flist`.
 
 |===
 
@@ -164,19 +164,25 @@ There is a very limited set of cases when you'd want to change these settings. F
 |===
 
 [float]
-[[login-selector-settings]]
-===== Login Selector UI settings
+[[login-ui-settings]]
+===== Login user interface settings
 
 [cols="2*<"]
 |===
+| `xpack.security.loginAssistanceMessage`
+| Adds a message to the login UI. Useful for displaying information about maintenance windows, links to corporate sign up pages etc.
+
+| `xpack.security.loginHelp`
+| Adds a message accessible at the login UI with additional help information for the login process.
+
 | `xpack.security.authc.selector.enabled`
-| Determines if the Login Selector UI should be enabled. By default, this setting is set to `true` if more than one authentication provider is configured.
+| Determines if the login selector UI should be enabled. By default, this setting is set to `true` if more than one authentication provider is configured.
 
 |===
 
 [float]
-[[security-ui-settings]]
-==== User interface security settings
+[[security-session-and-cookie-settings]]
+==== Session and cookie security settings
 
 You can configure the following settings in the `kibana.yml` file.
 
@@ -186,7 +192,7 @@ You can configure the following settings in the `kibana.yml` file.
   | Sets the name of the cookie used for the session. The default value is `"sid"`.
 
 | `xpack.security.encryptionKey`
-  | An arbitrary string of 32 characters or more that is used to encrypt session information. It is crucial that this key is not exposed to users of {kib}. By
+  | An arbitrary string of 32 characters or more that is used to encrypt session information. Do **not** expose this key to users of {kib}. By
   default, a value is automatically generated in memory. If you use that default
   behavior, all sessions are invalidated when {kib} restarts.
   In addition, high-availability deployments of {kib} will behave unexpectedly
@@ -204,56 +210,33 @@ You can configure the following settings in the `kibana.yml` file.
   This is *not set* by default, which modern browsers will treat as `Lax`. If you use Kibana embedded in an iframe in modern browsers, you might need to set it to `None`. Setting this value to `None` requires cookies to be sent over a secure connection by setting `xpack.security.secureCookies: true`.
 
 | `xpack.security.session.idleTimeout`
-  | Sets the session duration. By default, sessions stay active until the
-  browser is closed. When this is set to an explicit idle timeout, closing the
-  browser still requires the user to log back in to {kib}.
-
-|===
+  | This setting ensures that user sessions will expire after a period of inactivity. This and `xpack.security.session.lifespan` are both
+highly recommended. By default, this setting is not set.
 
+2+a|
 [TIP]
 ============
-The format is a string of `<count>[ms|s|m|h|d|w|M|Y]`
-(e.g. '70ms', '5s', '3d', '1Y').
+The format is a string of `<count>[ms\|s\|m\|h\|d\|w\|M\|Y]` (e.g. '70ms', '5s', '3d', '1Y').
 ============
 
-[cols="2*<"]
-|===
-
 | `xpack.security.session.lifespan`
-  | Sets the maximum duration, also known as "absolute timeout". By default,
-  a session can be renewed indefinitely. When this value is set, a session will end
-  once its lifespan is exceeded, even if the user is not idle. NOTE: if `idleTimeout`
-  is not set, this setting will still cause sessions to expire.
-
-|===
+  | This setting ensures that user sessions will expire after the defined time period. This behavior also known as an "absolute timeout". If
+this is _not_ set, user sessions could stay active indefinitely. This and `xpack.security.session.idleTimeout` are both highly
+recommended. By default, this setting is not set.
 
+2+a|
 [TIP]
 ============
-The format is a
-string of `<count>[ms|s|m|h|d|w|M|Y]` (e.g. '70ms', '5s', '3d', '1Y').
+The format is a string of `<count>[ms\|s\|m\|h\|d\|w\|M\|Y]` (e.g. '70ms', '5s', '3d', '1Y').
 ============
 
-[cols="2*<"]
-|===
-
 | `xpack.security.session.cleanupInterval`
 | Sets the interval at which {kib} tries to remove expired and invalid sessions from the session index. By default, this value is 1 hour. The minimum value is 10 seconds.
 
-|===
-
+2+a|
 [TIP]
 ============
-The format is a
-string of `<count>[ms|s|m|h|d|w|M|Y]` (e.g. '20m', '24h', '7d', '1w').
+The format is a string of `<count>[ms\|s\|m\|h\|d\|w\|M\|Y]` (e.g. '20m', '24h', '7d', '1w').
 ============
 
-[cols="2*<"]
-|===
-
-| `xpack.security.loginAssistanceMessage`
-  | Adds a message to the login screen. Useful for displaying information about maintenance windows, links to corporate sign up pages etc.
-
-| `xpack.security.loginHelp`
-  | Adds a message accessible at the Login Selector UI with additional help information for the login process.
-
 |===

docs/user/security/authentication/index.asciidoc

@@ -59,8 +59,6 @@ For more information, refer to <<authentication-security-settings, authenticatio
 
 To successfully log in to {kib}, basic authentication requires a username and password. Basic authentication is enabled by default, and is based on the Native, LDAP, or Active Directory security realm that is provided by {es}. The basic authentication provider uses a {kib} provided login form, and supports authentication using the `Authorization` request header `Basic` scheme.
 
-The session cookies that are issued by the basic authentication provider are stateless. Therefore, logging out of {kib} when using the basic authentication provider clears the session cookies from the browser, but does not invalidate the session cookie for reuse.
-
 NOTE: You can configure only one Basic provider per {kib} instance.
 
 For more information about basic authentication and built-in users, see
@@ -71,8 +69,6 @@ For more information about basic authentication and built-in users, see
 
 Token authentication allows users to log in using the same {kib} provided login form as basic authentication, and is based on the Native security realm or LDAP security realm that is provided by {es}. The token authentication provider is built on {es} token APIs.
 
-The session cookies that are issued by the token authentication provider are stateful, and logging out of {kib} invalidates the session cookies for reuse.
-
 Prior to configuring {kib}, ensure token support is enabled in {es}. See the {ref}/security-api-get-token.html[{es} token API] documentation for more information.
 
 To enable the token authentication provider in {kib}, set the following value in your `kibana.yml`:
@@ -243,11 +239,11 @@ The following sections apply both to <<saml>> and <<oidc>>
 ===== Access and refresh tokens
 
 Once the user logs in to {kib} Single Sign-On, either using SAML or OpenID Connect, {es} issues access and refresh tokens
-that {kib} encrypts and stores them in its own session cookie. This way, the user isn't redirected to the Identity Provider
-for every request that requires authentication. It also means that the {kib} session depends on the <<security-ui-settings,
+that {kib} encrypts and stores them as a part of its own session. This way, the user isn't redirected to the Identity Provider
+for every request that requires authentication. It also means that the {kib} session depends on the <<security-session-and-cookie-settings,
 `xpack.security.session.idleTimeout` and `xpack.security.session.lifespan`>> settings, and the user is automatically logged
-out if the session expires. An access token that is stored in the session cookie can expire, in which case {kib} will
-automatically renew it with a one-time-use refresh token and store it in the same cookie.
+out if the session expires. An access token that is stored in the session can expire, in which case {kib} will
+automatically renew it with a one-time-use refresh token and store it in the same session.
 
 {kib} can only determine if an access token has expired if it receives a request that requires authentication. If both access
 and refresh tokens have already expired (for example, after 24 hours of inactivity), {kib} initiates a new "handshake" and
@@ -260,8 +256,7 @@ indicates that both access and refresh tokens are expired. Reloading the current
 [float]
 ===== Local and global logout
 
-During logout, both the {kib} session cookie and access/refresh token pair are invalidated. Even if the cookie has been
-leaked, it can't be re-used after logout. This is known as "local" logout.
+During logout, both the {kib} session and {es} access/refresh token pair are invalidated. This is known as "local" logout.
 
 {kib} can also initiate a "global" logout or _Single Logout_ if it's supported by the external authentication provider and not
 explicitly disabled by {es}. In this case, the user is redirected to the external authentication provider for log out of

docs/user/security/securing-kibana.asciidoc

@@ -56,7 +56,17 @@ xpack.security.encryptionKey: "something_at_least_32_characters"
 For more information, see <<security-settings-kb,Security settings in {kib}>>.
 --
 
-. Optional: <<xpack-security-session-management, Configure {kib} session settings>>.
+. Configure {kib}'s session expiration settings. We strongly recommend setting both 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>>.
 

docs/user/security/session-management.asciidoc

@@ -2,59 +2,59 @@
 [[xpack-security-session-management]]
 === Session management
 
-When you log in to {kib} it creates a session that is used to authenticate subsequent requests to {kib}. A session consists of two components: an encrypted cookie that is stored in your browser, and an encrypted document in a dedicated {es} hidden index. By default, the name of that index is `.kibana_security_session_1` where the prefix is derived from {kib}'s primary `.kibana` index.
+When you log in, {kib} creates a session that is used to authenticate subsequent requests to {kib}. A session consists of two components: an encrypted cookie that is stored in your browser, and an encrypted document in a dedicated {es} hidden index. By default, the name of that index is `.kibana_security_session_1`, where the prefix is derived from the primary `.kibana` index. If either of these components are missing, the session is no longer valid.
 
-When your session expires, or you log out of {kib} explicitly it will invalidate your cookie and remove session information from the index. {kib} also periodically invalidates and removes any expired sessions that weren't invalidated explicitly.
+When your session expires, or you log out, {kib} will invalidate your cookie and remove session information from the index. {kib} also periodically invalidates and removes any expired sessions that weren't explicitly invalidated.
 
 [[session-idle-timeout]]
 ==== Session idle timeout
 
-You can optionally expire sessions after a period of inactivity. By default, a session stays
-active until the browser is closed. To define a sliding session expiration, set
+You can expire sessions after a period of inactivity. This and `xpack.security.session.lifespan` are both
+highly recommended. By default, session doesn't expire because of inactivity. To define a sliding session expiration, set
 the `xpack.security.session.idleTimeout` property in the `kibana.yml`
 configuration file. The idle timeout is formatted as a duration of
 `<count>[ms|s|m|h|d|w|M|Y]` (e.g. '70ms', '5s', '3d', '1Y'). For example, set
-the idle timeout to expire idle sessions after 10 minutes of inactivity:
+the idle timeout to expire sessions after 1 hour of inactivity:
 
 --
 [source,yaml]
 --------------------------------------------------------------------------------
-xpack.security.session.idleTimeout: "10m"
+xpack.security.session.idleTimeout: "1h"
 --------------------------------------------------------------------------------
 --
 
 [[session-lifespan]]
 ==== Session lifespan
 
 You can configure the maximum session duration or "lifespan" -- also known as
-the "absolute timeout". By default, a session stays active until the browser is
-closed. If an idle timeout is defined, a session can still be extended
+the "absolute timeout". This and `xpack.security.session.idleTimeout` are both highly
+recommended. By default, session doesn't have a fixed lifespan, and if an idle timeout is defined, a session can still be extended
 indefinitely. To define a maximum session lifespan, set the
 `xpack.security.session.lifespan` property in the `kibana.yml` configuration
 file. The lifespan is formatted as a duration of `<count>[ms|s|m|h|d|w|M|Y]`
 (e.g. '70ms', '5s', '3d', '1Y'). For example, set the lifespan to expire
-sessions after 8 hours:
+sessions after 30 days:
 
 --
 [source,yaml]
 --------------------------------------------------------------------------------
-xpack.security.session.lifespan: "8h"
+xpack.security.session.lifespan: "30d"
 --------------------------------------------------------------------------------
 --
 
 [[session-cleanup-interval]]
 ==== Session cleanup interval
 
-You can configure the interval at which {kib} tries to remove expired and invalid sessions from the session index. By default, this value is 1 hour and cannot be less than 10 seconds. To define another interval, set the `xpack.security.session.cleanupInterval` property in the `kibana.yml` configuration file. The interval is formatted as a duration of `<count>[ms|s|m|h|d|w|M|Y]` (e.g. '70000ms', '50s', '3d', '1Y'). For example, schedule session index cleanup to be performed only once a day:
+[IMPORTANT]
+============================================================================
+If you specify neither session idle timeout nor lifespan, then {kib} will not automatically remove session information from the index unless you explicitly log out. This might lead to an infinitely growing session index. Configure the idle timeout and lifespan settings for the {kib} sessions so that they can be cleaned up even if you don't explicitly log out.
+============================================================================
+
+You can configure the interval at which {kib} tries to remove expired and invalid sessions from the session index. By default, this value is 1 hour and cannot be less than 10 seconds. To define another interval, set the `xpack.security.session.cleanupInterval` property in the `kibana.yml` configuration file. The interval is formatted as a duration of `<count>[ms|s|m|h|d|w|M|Y]` (e.g. '70000ms', '50s', '3d', '1Y'). For example, schedule the session index cleanup to perform once a day:
 
 --
 [source,yaml]
 --------------------------------------------------------------------------------
 xpack.security.session.cleanupInterval: "1d"
 --------------------------------------------------------------------------------
 --
-
-[IMPORTANT]
-============================================================================
-If you specify neither session idle timeout nor lifespan, then {kib} will not automatically remove session information from the index unless you explicitly log out of {kib}. This may lead to an infinitely growing session index. It's one of the reasons why we strongly recommend configuring idle timeout and lifespan settings for the {kib} sessions so that they can be eventually cleaned up even if you don't log out of {kib} explicitly.
-============================================================================