[7.x] Document authentication settings. (#69565)

Co-authored-by: Kaarina Tungseth <kaarina.tungseth@elastic.co>
Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>

docs/settings/security-settings.asciidoc

@@ -30,6 +30,150 @@ You do not need to configure any additional settings to use the
 
 |===
 
+[float]
+[[authentication-security-settings]]
+==== Authentication security settings
+
+You configure authentication settings in the `xpack.security.authc` namespace in `kibana.yml`.
+
+For example:
+
+[source,yaml]
+----------------------------------------
+xpack.security.authc:
+    providers:
+      basic.basic1: <1>
+          order: 0 <2>
+          ...
+
+      saml.saml1: <3>
+          order: 1
+          ...
+  
+      saml.saml2: <4>
+          order: 2
+          ...
+  
+      pki.realm3:
+          order: 3
+          ...
+    ...
+----------------------------------------
+<1> Specifies the type of authentication provider (for example, `basic`, `token`, `saml`, `oidc`, `kerberos`, `pki`) and the provider name. This setting is mandatory.
+<2> Specifies the order of the provider in the authentication chain and on the Login Selector UI. This setting is mandatory.
+<3> Specifies the settings for the SAML authentication provider with a `saml1` name.
+<4> Specifies the settings for the SAML authentication provider with a `saml2` name.
+
+The valid settings in the `xpack.security.authc.providers` namespace vary depending on the authentication provider type. For more information, refer to <<kibana-authentication>>.
+
+[float]
+[[authentication-provider-settings]]
+===== Valid settings for all authentication providers
+
+[cols="2*<"]
+|===
+| `xpack.security.authc.providers.`
+`<provider-type>.<provider-name>.enabled`
+| Determines if the authentication provider should be enabled. By default, {kib} enables the provider as soon as you configure any of its properties.
+
+| `xpack.security.authc.providers.`
+`<provider-type>.<provider-name>.order`
+| Order of the provider in the authentication chain and on the Login Selector UI.
+
+| `xpack.security.authc.providers.`
+`<provider-type>.<provider-name>.description`
+| Custom description of the provider entry displayed on the Login Selector UI.
+
+| `xpack.security.authc.providers.`
+`<provider-type>.<provider-name>.hint`
+| Custom hint for the provider entry displayed on the Login Selector UI.
+
+| `xpack.security.authc.providers.`
+`<provider-type>.<provider-name>.icon`
+| Custom icon for the provider entry displayed on the Login Selector UI.
+
+| `xpack.security.authc.providers.`
+`<provider-type>.<provider-name>.showInSelector`
+| Flag that indicates if the provider should have an entry on the Login Selector UI. Setting this to `false` doesn't remove the provider from the authentication chain.
+
+|===
+
+[NOTE]
+============
+You are unable to set this setting to `false` for `basic` and `token` authentication providers.
+============
+
+[cols="2*<"]
+|===
+
+| `xpack.security.authc.providers.`
+`<provider-type>.<provider-name>.accessAgreement.message`
+| Access agreement text in Markdown format. For more information, refer to <<xpack-security-access-agreement>>.
+
+|===
+
+[float]
+[[saml-authentication-provider-settings]]
+===== SAML authentication provider settings
+
+In addition to <<authentication-provider-settings,the settings that are valid for all providers>>, you can specify the following settings:
+
+[cols="2*<"]
+|===
+| `xpack.security.authc.providers.`
+`saml.<provider-name>.realm`
+| SAML realm in {es} that provider should use.
+
+| `xpack.security.authc.providers.`
+`saml.<provider-name>.maxRedirectURLSize`
+| The maximum size of the URL that {kib} is allowed to store during the authentication SAML handshake. For more information, refer to <<security-saml-and-long-urls>>.
+
+|===
+
+[float]
+[[oidc-authentication-provider-settings]]
+===== OpenID Connect authentication provider settings
+
+In addition to <<authentication-provider-settings,the settings that are valid for all providers>>, you can specify the following settings:
+
+[cols="2*<"]
+|===
+| `xpack.security.authc.providers.`
+`oidc.<provider-name>.realm`
+| OpenID Connect realm in {es} that the provider should use.
+
+|===
+
+[float]
+[[http-authentication-settings]]
+===== HTTP authentication settings
+
+There is a very limited set of cases when you'd want to change these settings. For more information, refer to <<http-authentication>>.
+
+[cols="2*<"]
+|===
+| `xpack.security.authc.http.enabled`
+| Determines if HTTP authentication should be enabled. By default, this setting is set to `true`.
+
+| `xpack.security.authc.http.autoSchemesEnabled`
+| Determines if HTTP authentication schemes used by the enabled authentication providers should be automatically supported during HTTP authentication. By default, this setting is set to `true`.
+
+| `xpack.security.authc.http.schemes`
+| List of HTTP authentication schemes that {kib} HTTP authentication should support. By default, this setting is set to `['apikey']` to support HTTP authentication with <<api-keys, `ApiKey`>> scheme.
+
+|===
+
+[float]
+[[login-selector-settings]]
+===== Login Selector UI settings
+
+[cols="2*<"]
+|===
+| `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.
+
+|===
+
 [float]
 [[security-ui-settings]]
 ==== User interface security settings
@@ -96,4 +240,7 @@ string of `<count>[ms|s|m|h|d|w|M|Y]` (e.g. '70ms', '5s', '3d', '1Y').
 | `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/access-agreement.asciidoc

@@ -0,0 +1,27 @@
+[role="xpack"]
+[[xpack-security-access-agreement]]
+=== Access agreement
+
+Some work environments require you to acknowledge and accept an agreement before you can access {kib}, which can contain sensitive information. The agreement text supports Markdown format and can be specified using the `xpack.security.authc.providers.<provider-type>.<provider-name>.accessAgreement.message` setting.
+
+[NOTE]
+============================================================================
+You need to acknowledge the access agreement only once per session, and {kib} reports the acknowledgement in the audit logs.
+============================================================================
+
+Here is how your `kibana.yml` can look like if you define an access agreement:
+
+[source,yaml]
+--------------------------------------------------------------------------------
+xpack.security.authc.providers:
+  basic.basic1:
+    order: 0
+    accessAgreement:
+      message: "**You are accessing a system with a sensitive information** \n\n
+                  By logging in, you acknowledge that (shortened ...)"
+--------------------------------------------------------------------------------
+
+When you authenticate using `basic.basic1`, you'll see the following agreement that you must acknowledge before you can access {kib}:
+
+[role="screenshot"]
+image::user/security/images/access-agreement.png["Access Agreement UI"]

docs/user/security/audit-logging.asciidoc

@@ -1,6 +1,6 @@
 [role="xpack"]
 [[xpack-security-audit-logging]]
-===  Audit Logging
+=== Audit logs
 
 You can enable auditing to keep track of security-related events such as
 authorization success and failures. Logging these events enables you

docs/user/security/authentication/index.asciidoc

@@ -17,22 +17,29 @@
 
 Enable multiple authentication mechanisms at the same time specifying a prioritized list of the authentication _providers_ (typically of various types) in the configuration. Providers are consulted in ascending order. Make sure each configured provider has a unique name (e.g. `basic1` or `saml1` in the configuration example) and `order` setting. In the event that two or more providers have the same name or `order`, {kib} will fail to start.
 
-When two or more providers are configured, you can choose the provider you want to use on the Login Selector UI. The order the providers appear is determined by the order setting. The appearance of the specific provider entry can be customized with the `description` setting.
+When two or more providers are configured, you can choose the provider you want to use on the Login Selector UI. The order the providers appear is determined by the `order` setting. The appearance of the specific provider entry can be customized with the `description`, `hint`, and `icon` settings.
+
+TIP: To provide login instructions to users, use the `xpack.security.loginHelp` setting, which supports Markdown format. When you specify the `xpack.security.loginHelp` setting, the Login Selector UI displays a `Need help?` link that lets users access login help information.
 
 If you don't want a specific provider to show up at the Login Selector UI (e.g. to only support third-party initiated login) you can hide it with `showInSelector` setting set to `false`. However, in this case, the provider is presented in the provider chain and may be consulted during authentication based on its `order`. To disable the provider, use the `enabled` setting.
 
 TIP: The Login Selector UI can also be disabled or enabled with `xpack.security.authc.selector.enabled` setting. 
 
-Here is how your `kibana.yml` can look like if you deal with multiple authentication providers:
+Here is how your `kibana.yml` and Login Selector UI can look like if you deal with multiple authentication providers:
 
+[source,yaml]
 --------------------------------------------------------------------------------
+xpack.security.loginHelp: "**Help** info with a [link](...)"
 xpack.security.authc.providers:
   basic.basic1:
     order: 0
+    icon: "logoElasticsearch"
+    hint: "Typically for administrators"
   saml.saml1:
     order: 1
     realm: saml1
     description: "Log in with SSO"
+    icon: "https://my-company.xyz/saml-logo.svg"
   saml.saml2:
     order: 2
     realm: saml2
@@ -42,6 +49,11 @@ xpack.security.authc.providers:
     enabled: false
 --------------------------------------------------------------------------------
 
+[role="screenshot"]
+image::user/security/images/kibana-login.png["Login Selector UI"]
+
+For more information, refer to <<authentication-security-settings, authentication security settings>>.
+
 [[basic-authentication]]
 ==== Basic authentication
 
@@ -170,6 +182,7 @@ Basic authentication is supported _only_ if the `basic` authentication provider
 To support basic authentication for the applications like `curl` or when the `Authorization: Basic base64(username:password)` HTTP header is included in the request (for example, by reverse proxy), add `Basic` scheme to the list of supported schemes for the <<http-authentication,HTTP authentication>>.
 
 [float]
+[[security-saml-and-long-urls]]
 ===== SAML and long URLs
 
 At the beginning of the SAML handshake, {kib} stores the initial URL in the session cookie, so it can redirect the user back to that URL after successful SAML authentication.
@@ -325,4 +338,4 @@ NOTE: Don't forget to explicitly specify default `apikey` scheme when you just w
 xpack.security.authc.http.schemes: [apikey, basic, something-custom]
 --------------------------------------------------------------------------------
 
-With this configuration, you can send requests to {kib} with the `Authorization` header using `ApiKey`, `Basic` or `Something-Custom` HTTP schemes (case insensitive). Under the hood, {kib} relays this header to {es}, then {es} authenticates the request using the credentials in the header.
+With this configuration, you can send requests to {kib} with the `Authorization` header using `ApiKey`, `Basic` or `Something-Custom` HTTP schemes (case insensitive). Under the hood, {kib} relays this header to {es}, then {es} authenticates the request using the credentials in the header.

docs/user/security/securing-kibana.asciidoc

@@ -145,3 +145,4 @@ include::authentication/index.asciidoc[]
 include::securing-communications/index.asciidoc[]
 include::securing-communications/elasticsearch-mutual-tls.asciidoc[]
 include::audit-logging.asciidoc[]
+include::access-agreement.asciidoc[]