[DOCS] Moves security content into user folder (#45555)

docs/user/index.asciidoc

@@ -42,7 +42,7 @@ include::management.asciidoc[]
 
 include::{kib-repo-dir}/spaces/index.asciidoc[]
 
-include::{kib-repo-dir}/security/index.asciidoc[]
+include::security/index.asciidoc[]
 
 include::{kib-repo-dir}/management/watcher-ui/index.asciidoc[]
 

docs/user/security/audit-logging.asciidoc

@@ -0,0 +1,36 @@
+[role="xpack"]
+[[xpack-security-audit-logging]]
+===  Audit Logging
+
+You can enable auditing to keep track of security-related events such as
+authorization success and failures. Logging these events enables you
+to monitor {kib} for suspicious activity and provides evidence in the
+event of an attack.
+
+Use the {kib} audit logs in conjunction with {es}'s
+audit logging to get a holistic view of all security related events. 
+{kib} defers to {es}'s security model for authentication, data
+index authorization, and features that are driven by cluster-wide privileges.
+For more information on enabling audit logging in {es}, see
+{stack-ov}/auditing.html[Auditing Security Events].
+
+[IMPORTANT]
+============================================================================
+Audit logs are **disabled** by default. To enable this functionality, you
+must set `xpack.security.audit.enabled` to `true` in `kibana.yml`.
+============================================================================
+
+Audit logging uses the standard {kib} logging output, which can be configured
+in the `kibana.yml` and is discussed in <<settings>>.
+
+==== Audit event types
+
+When you are auditing security events, each request can generate 
+multiple audit events. The following is a list of the events that can be generated:
+
+|======
+| `saved_objects_authorization_success`    | Logged when a user is authorized to access a saved
+                                             objects when using a role with <<kibana-privileges>>
+| `saved_objects_authorization_failure`    | Logged when a user isn't authorized to access a saved
+                                             objects when using a role with <<kibana-privileges>>
+|======

docs/user/security/authentication/index.asciidoc

@@ -0,0 +1,196 @@
+[role="xpack"]
+[[kibana-authentication]]
+=== Authentication in Kibana
+++++
+<titleabbrev>Authentication</titleabbrev>
+++++
+
+{kib} supports the following authentication mechanisms:
+
+- <<basic-authentication>>
+- <<token-authentication>>
+- <<pki-authentication>>
+- <<saml>>
+- <<oidc>>
+
+[[basic-authentication]]
+==== Basic Authentication
+
+Basic authentication requires a username and password to successfully log in to {kib}. It is enabled by default and based on the Native security realm provided by {es}. The basic authentication provider uses a Kibana provided login form, and supports authentication using the `Authorization` request header's `Basic` scheme.
+
+The session cookies that are issued by the basic authentication provider are stateless. Therefore, logging out of Kibana when using the basic authentication provider clears the session cookies from the browser but does not invalidate the session cookie for reuse.
+
+For more information about basic authentication and built-in users, see {xpack-ref}/setting-up-authentication.html[Setting Up User Authentication].
+
+[[token-authentication]]
+==== Token Authentication
+
+Token authentication allows users to login using the same Kibana provided login form as basic authentication. The token authentication provider is built on {es}'s token APIs. The bearer tokens returned by {es}'s {ref}/security-api-get-token.html[get token API] can be used directly with Kibana using the `Authorization` request header with the `Bearer` scheme.
+
+The session cookies that are issued by the token authentication provider are stateful, and logging out of Kibana invalidates the session cookies for reuse.
+
+Prior to configuring Kibana, ensure token support is enabled in Elasticsearch. See the {ref}/security-api-get-token.html[Elasticsearch token API] documentation for more information.
+
+To enable the token authentication provider in Kibana, set the following value in your `kibana.yml`:
+
+[source,yaml]
+--------------------------------------------------------------------------------
+xpack.security.authc.providers: [token]
+--------------------------------------------------------------------------------
+
+The token authentication provider can be used in conjunction with the basic authentication provider. The login form will continue to use the token authentication provider, while enabling applications like `curl` to use the `Authorization` request header with the `Basic` scheme. Set the following in your `kibana.yml`, maintaining the order of the auth providers:
+
+[source,yaml]
+--------------------------------------------------------------------------------
+xpack.security.authc.providers: [token, basic]
+--------------------------------------------------------------------------------
+
+[[pki-authentication]]
+==== Public Key Infrastructure (PKI) Authentication
+
+[IMPORTANT]
+============================================================================
+PKI authentication will not work if {kib} is hosted behind a TLS termination reverse proxy. In this configuration, {kib} does not have direct access to the client certificates and cannot authenticate the user.
+============================================================================
+
+PKI authentication allows users to log into {kib} using X.509 client certificates that must be presented while connecting to {kib}. The certificates must first be accepted for authentication on the {kib} TLS layer, and then they are further validated by an {es} PKI realm. The PKI authentication provider relies on the {es} {ref}/security-api-delegate-pki-authentication.html[Delegate PKI authentication API] to exchange X.509 client certificates to access tokens. All subsequent requests to {es} APIs on behalf of users will be authenticated using these access tokens.
+
+Prior to configuring {kib}, ensure that the PKI realm is enabled in {es} and configured to permit delegation. See {ref}/configuring-pki-realm.html[Configuring a PKI realm] for more information.
+
+To enable the PKI authentication provider in {kib}, you must first <<configuring-tls,configure {kib} to encrypt communications between the browser and {kib} server>>. You must also enable TLS client authentication and include the certificate authority (CA) used to sign client certificates into a list of CAs trusted by {kib} in your `kibana.yml`:
+
+[source,yaml]
+--------------------------------------------------------------------------------
+server.ssl.certificateAuthorities: /path/to/your/cacert.pem
+server.ssl.clientAuthentication: required
+xpack.security.authc.providers: [pki]
+--------------------------------------------------------------------------------
+
+PKI support in {kib} is designed to be the primary (or sole) authentication method for users of that {kib} instance. However, you can configure both PKI and Basic authentication for the same {kib} instance:
+
+[source,yaml]
+--------------------------------------------------------------------------------
+xpack.security.authc.providers: [pki, basic]
+--------------------------------------------------------------------------------
+
+Note that with `server.ssl.clientAuthentication` set to `required`, users are asked to provide a valid client certificate, even if they want to authenticate with username and password. Depending on the security policies, it may or may not be desired. If not, `server.ssl.clientAuthentication` can be set to `optional`. In this case, {kib} still requests a client certificate, but the client won't be required to present one. The `optional` client authentication mode might also be needed in other cases, for example, when PKI authentication is used in conjunction with Reporting.
+
+[[saml]]
+==== SAML Single Sign-On
+
+SAML authentication allows users to log in to {kib} with an external Identity Provider, such as Okta or Auth0. Make sure that SAML is enabled and configured in {es} before setting it up in {kib}. See {xpack-ref}/saml-guide.html[Configuring SAML Single-Sign-On on the Elastic Stack].
+
+Set the configuration values in `kibana.yml` as follows:
+
+. Enable the SAML authentication:
++
+[source,yaml]
+--------------------------------------------------------------------------------
+xpack.security.authc.providers: [saml]
+--------------------------------------------------------------------------------
+
+. {kib} needs to specify which SAML realm in {es} should be used:
++
+[source,yaml]
+--------------------------------------------------------------------------------
+xpack.security.authc.saml.realm: realm-name
+--------------------------------------------------------------------------------
+
+. The Identify Provider sends authentication requests to the `Assertion Consumer Service` endpoint that {kib} exposes through a "non-safe" `POST` HTTP method. This does not include CSRF protection HTTP headers specific to {kib}. You must disable the CSRF check for this endpoint.
++
+[source,yaml]
+--------------------------------------------------------------------------------
+server.xsrf.whitelist: [/api/security/v1/saml]
+--------------------------------------------------------------------------------
+
+Users will be able to log in to {kib} via SAML Single Sign-On by navigating directly to the {kib} URL. Users who aren't authenticated are redirected to the Identity Provider for login. Most Identity Providers maintain a long-lived session—users who logged in to a different application using the same Identity Provider in the same browser are automatically authenticated. An exception is if {es} or the Identity Provider is configured to force user to re-authenticate. This login scenario is called _Service Provider initiated login_.
+
+[float]
+===== SAML and Basic Authentication
+
+SAML support in {kib} is designed to be the primary (or sole) authentication method for users of that {kib} instance. However, you can configure both SAML and Basic authentication for the same {kib} instance:
+
+[source,yaml]
+--------------------------------------------------------------------------------
+xpack.security.authc.providers: [saml, basic]
+--------------------------------------------------------------------------------
+
+The order of `saml` and `basic` is important. Users who open {kib} will go through the SAML Single Sign-On process unless the direct Basic authentication `/login` link is used. This might be the case for {kib} or {es} admins whose accounts aren't linked to the Single Sign-On users database. Or, when the `Authorization: Basic base64(username:password)` HTTP header is included in the request (for example, by reverse proxy).
+
+Basic authentication is supported _only_ if `basic` authentication provider is explicitly declared in `xpack.security.authc.providers` setting in addition to `saml`.
+
+[[oidc]]
+==== OpenID Connect Single Sign-On
+
+Similar to SAML, authentication with OpenID Connect allows users to log in to {kib} using an OpenID Connect Provider such as Google, or Okta. OpenID Connect
+should also be configured in {es}, see {xpack-ref}/saml-guide.html[Configuring OpenID Connect Single-Sign-On on the Elastic Stack] for more details.
+
+Set the configuration values in `kibana.yml` as follows:
+
+. Enable the OpenID Connect authentication:
++
+[source,yaml]
+--------------------------------------------------------------------------------
+xpack.security.authc.providers: [oidc]
+--------------------------------------------------------------------------------
+
+. {kib} needs to specify which OpenID Connect realm in {es} should be used, in case there are more than one configured there.
++
+[source,yaml]
+--------------------------------------------------------------------------------
+xpack.security.authc.oidc.realm: oidc1
+--------------------------------------------------------------------------------
+
+. {kib} supports Third Party initiated Single Sign On, which might start with an external application instructing the user's
+browser to perform a "non-safe" `POST` HTTP method. This request will not include CSRF protection HTTP headers that are
+required by {kib}. If you want to use Third Party initiated SSO , then you must disable the CSRF check for this endpoint.
++
+[source,yaml]
+--------------------------------------------------------------------------------
+server.xsrf.whitelist: [/api/security/v1/oidc]
+--------------------------------------------------------------------------------
+
+[float]
+===== OpenID Connect and Basic Authentication
+
+Similar to SAML, OpenID Connect support in {kib} is designed to be the primary (or sole) authentication method for users
+of that {kib} instance. However, you can configure both OpenID Connect and Basic authentication for the same {kib} instance:
+
+[source,yaml]
+--------------------------------------------------------------------------------
+xpack.security.authc.providers: [oidc, basic]
+--------------------------------------------------------------------------------
+
+Users will be able to access the login page and use Basic authentication by navigating to the `/login` URL.
+
+[float]
+==== Single Sign-On provider details
+
+The following sections apply both to <<saml>> and <<oidc>> 
+
+[float]
+===== 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 `xpack.security.sessionTimeout` 
+setting 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.
+
+{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
+redirects the user to the external authentication provider (SAML Identity Provider or OpenID Connect Provider)
+Depending on {es} and the external authentication provider configuration, the user might be asked to re-enter credentials.
+
+If {kib} can't redirect the user to the external authentication provider (for example, for AJAX/XHR requests), an error
+indicates that both access and refresh tokens are expired. Reloading the current {kib} page fixes the error.
+
+[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.
+
+{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
+all applications associated with the active provider session.

docs/user/security/authorization/index.asciidoc

@@ -0,0 +1,93 @@
+[role="xpack"]
+[[xpack-security-authorization]]
+
+=== Granting access to {kib}
+The Elastic Stack comes with the `kibana_user` {stack-ov}/built-in-roles.html[built-in role], which you can use to grant access to all Kibana features in all spaces. To grant users access to a subset of spaces or features, you can create a custom role that grants the desired Kibana privileges. 
+
+When you assign a user multiple roles, the user receives a union of the roles’ privileges. Therefore, assigning the `kibana_user` role in addition to a custom role that grants Kibana privileges is ineffective because `kibana_user` has access to all the features in all spaces.
+
+NOTE: When running multiple tenants of Kibana by changing the `kibana.index` in your `kibana.yml`, you cannot use `kibana_user` to grant access. You must create custom roles that authorize the user for that specific tenant. Although multi-tenant installations are supported, the recommended approach to securing access to Kibana segments is to grant users access to specific spaces.
+
+[role="xpack"]
+=== {kib} role management
+
+To create a role that grants {kib} privileges, go to **Management -> Security -> Roles** and click **Create role**. 
+
+[[adding_kibana_privileges]]
+==== Adding {kib} privileges
+
+To assign {kib} privileges to the role, click **Add space privilege** in the Kibana section.
+
+[role="screenshot"]
+image::security/images/add-space-privileges.png[Add space privileges]
+
+Open the **Spaces** selection control to specify whether to grant the role access to all spaces *** Global (all spaces)** or one or more individual spaces. If you select *** Global (all spaces)**, you can’t select individual spaces until you clear your selection.
+
+Use the **Privilege** menu to grant access to features. The default is **Custom**, which you can use to grant access to individual features. Otherwise, you can grant read and write access to all current and future features by selecting **All**, or grant read access to all current and future features by selecting **Read**.
+
+[IMPORTANT]
+If a feature is hidden using the Spaces disabled features, it will remain hidden even if the user has the necessary privileges.
+
+When using the **Customize by feature** option, you can choose either **All**, **Read** or **None** for access to each feature. As new features are added to Kibana, roles that use the custom option do not automatically get access to the new features. You must manually update the roles.
+
+NOTE: Machine Learning and Stack Monitoring rely on built-in roles to grant access. When a user is assigned the appropriate roles, the Machine Learning and Stack Monitoring application are available; otherwise, these applications are not visible.
+
+To apply your changes, click **Create space privilege**. The space privilege shows up under the Kibana privileges section of the role.
+
+
+[role="screenshot"]
+image::security/images/create-space-privilege.png[Create space privilege]
+
+==== Assigning different privileges to different spaces
+
+Using the same role, it’s possible to assign different privileges to different spaces. After you’ve added space privileges, click **Add space privilege**. If you’ve already added privileges for either *** Global (all spaces)** or an individual space, you will not be able to select these in the **Spaces** selection control.
+
+Additionally, if you’ve already assigned privileges at *** Global (all spaces)**, you are only able to assign additional privileges to individual spaces. Similar to the behavior of multiple roles granting the union of all privileges, space privileges are also a union. If you’ve already granted the user the **All** privilege at *** Global (all spaces)**, you’re not able to restrict the role to only the **Read** privilege at an individual space. 
+
+
+==== Privilege summary
+
+To view a summary of the privileges granted, click **View privilege summary**.
+
+[role="screenshot"]
+image::security/images/view-privilege-summary.png[View privilege summary]
+
+==== Example 1: Grant all access to Dashboard at an individual space
+
+. Click **Add space privilege**.
+. For **Spaces**, select an individual space.
+. For **Privilege**, leave the default selection of **Custom**.
+. For the Dashboard feature, select **All**
+. Click **Create space privilege**.
+
+[role="screenshot"]
+image::security/images/privilege-example-1.png[Privilege example 1]
+
+==== Example 2: Grant all access to one space and read access to another
+
+. Click **Add space privilege**.
+. For **Spaces**, select the first space.
+. For **Privilege**, select **All**.
+. Click **Create space privilege**.
+. Click **Add space privilege**.
+. For **Spaces**, select the second space.
+. For **Privilege**, select **Read**.
+. Click **Create space privilege**.
+
+[role="screenshot"]
+image::security/images/privilege-example-2.png[Privilege example 2]
+
+==== Example 3: Grant read access to all spaces and write access to an individual space
+
+. Click **Add space privilege**.
+. For **Spaces**, select *** Global (all spaces)**.
+. For **Privilege**, select **Read**.
+. Click **Create space privilege**.
+. Click **Add space privilege**.
+. For **Spaces**, select the individual space.
+. For **Privilege**, select **All**.
+. Click **Create space privilege**.
+
+[role="screenshot"]
+image::security/images/privilege-example-3.png[Privilege example 3]
+

docs/user/security/authorization/kibana-privileges.asciidoc

@@ -0,0 +1,71 @@
+[role="xpack"]
+[[kibana-privileges]]
+=== Kibana privileges
+
+{kib} privileges grant users access to features within {kib}. Roles have privileges to determine whether users have write or read access.
+
+==== Base privileges
+Assigning a base privilege grants access to all available features in Kibana (Discover, Visualize, Dashboard, and so on).
+[[kibana-privileges-all]]
+`all`:: Grants full read-write access.
+`read`:: Grants read-only access.
+
+===== Assigning base privileges
+From the role management screen:
+
+[role="screenshot"]
+image::security/images/assign_base_privilege.png[Assign base privilege]
+
+From the <<role-management-api-put, role management API>>:
+[source,js]
+--------------------------------------------------
+PUT /api/security/role/my_kibana_role
+{
+  "elasticsearch": {
+    "cluster" : [ ],
+    "indices" : [ ]
+  },
+  "kibana": [
+    {
+      "base": ["all"],
+      "feature": {},
+      "spaces": ["marketing"]
+    }
+  ]
+}
+--------------------------------------------------
+
+
+[[kibana-feature-privileges]]
+==== Feature privileges
+Assigning a feature privilege grants access to a specific feature.
+
+`all`:: Grants full read-write access.
+`read`:: Grants read-only access.
+
+===== Assigning feature privileges
+From the role management screen:
+
+[role="screenshot"]
+image::security/images/assign_feature_privilege.png[Assign feature privilege]
+
+From the <<role-management-api-put, role management API>>:
+[source,js]
+--------------------------------------------------
+PUT /api/security/role/my_kibana_role
+{
+  "elasticsearch": {
+    "cluster" : [ ],
+    "indices" : [ ]
+  },
+  "kibana": [
+    {
+      "base": [],
+      "feature": {
+        "dashboard": ["all"]
+      },
+      "spaces": ["marketing"]
+    }
+  ]
+}
+--------------------------------------------------

docs/user/security/cross-cluster-kibana.asciidoc

@@ -0,0 +1,39 @@
+[[cross-cluster-kibana]]
+==== {ccs-cap} and {kib}
+
+When {kib} is used to search across multiple clusters, a two-step authorization
+process determines whether or not the user can access indices on a remote
+cluster:
+
+* First, the local cluster determines if the user is authorized to access remote
+clusters. (The local cluster is the cluster {kib} is connected to.)
+* If they are, the remote cluster then determines if the user has access
+to the specified indices.
+
+To grant {kib} users access to remote clusters, assign them a local role
+with read privileges to indices on the remote clusters. You specify remote
+cluster indices as `<remote_cluster_name>:<index_name>`.
+
+To enable users to actually read the remote indices, you must create a matching
+role on the remote clusters that grants the `read_cross_cluster` privilege
+and access to the appropriate indices.
+
+For example, if {kib} is connected to the cluster where you're actively
+indexing {ls} data (your _local cluster_) and you're periodically
+offloading older time-based indices to an archive cluster
+(your _remote cluster_) and you want to enable {kib} users to search both
+clusters:
+
+. On the local cluster, create a `logstash_reader` role that grants
+`read` and `view_index_metadata` privileges on the local `logstash-*` indices.
++
+NOTE: If you configure the local cluster as another remote in {es}, the
+`logstash_reader` role on your local cluster also needs to grant the
+`read_cross_cluster` privilege.
+
+. Assign your {kib} users the `kibana_user` role and your `logstash_reader`
+role.
+
+. On the remote cluster, create a `logstash_reader` role that grants the
+`read_cross_cluster` privilege and `read` and `view_index_metadata` privileges
+for the `logstash-*` indices.

docs/user/security/index.asciidoc

@@ -0,0 +1,38 @@
+[role="xpack"]
+[[xpack-security]]
+== Security
+
+The {stack} {security-features} enable you to easily secure a cluster. With
+security, 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
+{stack-ov}/elasticsearch-security.html[Securing {es} and {kib}] and
+<<using-kibana-with-security,Configuring Security in {kib}>>.
+
+[float]
+=== Users
+
+You can create and manage users on the *Management -> Security -> Users* page.
+You can also change their passwords and roles. For more information about
+authentication and built-in users, see
+{stack-ov}/setting-up-authentication.html[Setting up user authentication].
+
+[float]
+=== Roles
+
+You can manage roles on the *Management -> Security -> Roles* page, or use
+the <<role-management-api>>. For more information on configuring roles for {kib}, see <<xpack-security-authorization, Granting access to {kib}>>.
+
+For a more holistic overview of configuring roles for the entire stack,
+see {stack-ov}/authorization.html[Configuring role-based access control].
+
+[NOTE]
+============================================================================
+Managing roles that grant <<kibana-privileges>> using the {es} 
+{ref}/security-api.html#security-role-apis[role management APIs] is not supported. Doing so will likely
+cause Kibana's authorization to behave unexpectedly.
+============================================================================
+
+include::authorization/index.asciidoc[]
+include::authorization/kibana-privileges.asciidoc[]

docs/user/security/reporting.asciidoc

@@ -0,0 +1,85 @@
+[role="xpack"]
+[[secure-reporting]]
+=== Reporting and Security
+
+Reporting operates by creating and updating documents in {es} in response to
+user actions in {kib}.
+
+To use {reporting} with {security} enabled, you need to
+<<using-kibana-with-security,set up {kib} to work with {security}>>.
+If you are automatically generating reports with
+{xpack-ref}/xpack-alerting.html[{watcher}], you also need to configure {watcher}
+to trust the {kib} server's certificate. For more information, see
+<<securing-reporting>>.
+
+[[reporting-app-users]]
+To enable users to generate reports, assign them the built in `reporting_user`
+and `kibana_user` roles:
+
+* If you're using the `native` realm, you can assign roles through
+**Management / Users** UI in Kibana or with the `user` API. For example,
+the following request creates a `reporter` user that has the
+`reporting_user` and `kibana_user` roles:
++
+[source, sh]
+---------------------------------------------------------------
+POST /_security/user/reporter
+{
+  "password" : "x-pack-test-password",
+  "roles" : ["kibana_user", "reporting_user"],
+  "full_name" : "Reporting User"
+}
+---------------------------------------------------------------
+
+* If you are using an LDAP or Active Directory realm, you can either assign
+roles on a per user basis, or assign roles to groups of users. By default, role
+mappings are configured in
+{xpack-ref}/mapping-roles.html[`config/shield/role_mapping.yml`].
+For example, the following snippet assigns the user named Bill Murray the
+`kibana_user` and `reporting_user` roles:
++
+[source,yaml]
+--------------------------------------------------------------------------------
+kibana_user:
+  - "cn=Bill Murray,dc=example,dc=com"
+reporting_user:
+  - "cn=Bill Murray,dc=example,dc=com"
+--------------------------------------------------------------------------------
+
+[role="xpack"]
+[[securing-reporting]]
+=== Securing the Reporting Endpoints
+
+In a production environment, you should restrict access to
+the {reporting} endpoints to authorized users. This requires that you:
+
+. Enable {security} on your {es} cluster. For more information,
+see {xpack-ref}/security-getting-started.html[Getting Started with Security].
+. Configure an SSL certificate for Kibana. For more information, see
+<<using-kibana-with-security>>.
+. Configure {watcher} to trust the Kibana server's certificate by adding it to
+the {watcher} truststore on each node:
+.. Import the {kib} server certificate into the {watcher} truststore using
+Java Keytool:
++
+[source,shell]
+---------------------------------------------------------
+keytool -importcert -keystore watcher-truststore.jks -file server.crt
+---------------------------------------------------------
++
+NOTE: If the truststore doesn't already exist, it is created.
+
+.. Make sure the `xpack.http.ssl.truststore.path` setting in
+`elasticsearch.yml` specifies the location of the {watcher}
+truststore.
+. Add one or more users who have the permissions
+necessary to use {kib} and {reporting}. For more information, see
+<<secure-reporting>>.
+
+Once you've enabled SSL for {kib}, all requests to the {reporting} endpoints
+must include valid credentials. For example, see the following page which
+includes a watch that submits requests as the built-in `elastic` user:
+<<automating-report-generation>>.
+
+For more information about configuring watches, see
+{xpack-ref}/how-watcher-works.html[How Watcher Works].

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

@@ -0,0 +1,124 @@
+[[configuring-tls]]
+=== Encrypting communications in {kib}
+++++
+<titleabbrev>Encrypting communications</titleabbrev>
+++++
+
+{kib} supports Transport Layer Security (TLS/SSL) encryption for client 
+requests. 
+//TBD: It is unclear what "client requests" are in this context. Is it just 
+// communication between the browser and the Kibana server or are we talking 
+// about other types of clients connecting to the Kibana server?
+
+If you are using {security} or a proxy that provides an HTTPS endpoint for {es}, 
+you can configure {kib} to access {es} via HTTPS. Thus, communications between 
+{kib} and {es} are also encrypted. 
+
+. Configure {kib} to encrypt communications between the browser and the {kib}
+server:
++
+--
+NOTE: You do not need to enable {security} for this type of encryption. 
+
+--
+
+.. Generate a server certificate for {kib}. 
++
+--
+//TBD: Can we provide more information about how they generate the certificate? 
+//Would they be able to use something like the elasticsearch-certutil command?
+You must either set the certificate's
+`subjectAltName` to the hostname, fully-qualified domain name (FQDN), or IP
+address of the {kib} server, or set the CN to the {kib} server's hostname
+or FQDN. Using the server's IP address as the CN does not work.
+--
+
+.. Set the `server.ssl.enabled`, `server.ssl.key`, and `server.ssl.certificate` 
+properties in `kibana.yml`:
++
+--
+[source,yaml]
+--------------------------------------------------------------------------------
+server.ssl.enabled: true
+server.ssl.key: /path/to/your/server.key
+server.ssl.certificate: /path/to/your/server.crt
+--------------------------------------------------------------------------------
+
+After making these changes, you must always access {kib} via HTTPS. For example, 
+https://localhost:5601.
+
+// TBD: The reference information for server.ssl.enabled says it "enables SSL for 
+// outgoing requests from the Kibana server to the browser". Do we need to 
+// reiterate here that only one side of the communications is encrypted?
+
+For more information, see <<settings,{kib} configuration settings>>.
+--
+
+. Configure {kib} to connect to {es} via HTTPS:
++
+--
+NOTE: To perform this step, you must 
+{ref}/configuring-security.html[enable the {es} {security-features}] or you 
+must have a proxy that provides an HTTPS endpoint for {es}. 
+
+--
+
+.. Specify the HTTPS protocol in the `elasticsearch.hosts` setting in the {kib}
+configuration file, `kibana.yml`:
++
+--
+[source,yaml]
+--------------------------------------------------------------------------------
+elasticsearch.hosts: ["https://<your_elasticsearch_host>.com:9200"]
+--------------------------------------------------------------------------------
+--
+
+.. If you are using your own CA to sign certificates for {es}, set the
+`elasticsearch.ssl.certificateAuthorities` setting in `kibana.yml` to specify
+the location of the PEM file.
++
+--
+[source,yaml]
+--------------------------------------------------------------------------------
+elasticsearch.ssl.certificateAuthorities: /path/to/your/cacert.pem
+--------------------------------------------------------------------------------
+
+Setting the `certificateAuthorities` property lets you use the default 
+`verificationMode` option of `full`. 
+//TBD: Is this still true? It isn't mentioned in https://www.elastic.co/guide/en/kibana/master/settings.html
+
+For more information, see <<settings,{kib} configuration settings>>. 
+--
+
+. (Optional) If the Elastic {monitor-features} are enabled, configure {kib} to 
+connect to the {es} monitoring cluster via HTTPS: 
++
+--
+NOTE: To perform this step, you must 
+{ref}/configuring-security.html[enable the {es} {security-features}] or you 
+must have a proxy that provides an HTTPS endpoint for {es}. 
+
+--
+
+.. Specify the HTTPS URL in the `xpack.monitoring.elasticsearch.hosts` setting in 
+the {kib} configuration file, `kibana.yml`
++
+--
+[source,yaml]
+--------------------------------------------------------------------------------
+xpack.monitoring.elasticsearch.hosts: ["https://<your_monitoring_cluster>:9200"]
+--------------------------------------------------------------------------------
+--
+
+.. Specify the `xpack.monitoring.elasticsearch.ssl.*` settings in the 
+`kibana.yml` file.
++
+--
+For example, if you are using your own certificate authority to sign
+certificates, specify the location of the PEM file in the `kibana.yml` file:
+
+[source,yaml]
+--------------------------------------------------------------------------------
+xpack.monitoring.elasticsearch.ssl.certificateAuthorities: /path/to/your/cacert.pem
+--------------------------------------------------------------------------------
+--

docs/user/security/securing-kibana.asciidoc

@@ -0,0 +1,127 @@
+[role="xpack"]
+[[using-kibana-with-security]]
+== Configuring security in {kib}
+++++
+<titleabbrev>Configuring security</titleabbrev>
+++++
+
+{kib} users have to log in when {security} is enabled on your cluster. You
+configure {security} roles for your {kib} users to control what data those users
+can access.
+
+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.
+
+With {security} 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. {security} do not currently provide a way to control which
+users can load which dashboards.
+
+To use {kib} with {security}:
+
+. {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"
+elasticsearch.password: "kibanapassword"
+-----------------------------------------------
+
+The {kib} server submits requests as this user to access the cluster monitoring
+APIs and the `.kibana` index. The server does _not_ need access to user indices.
+
+The password for the built-in `kibana` user is typically set as part of the
+{security} configuration process on {es}. For more information, see
+{stack-ov}/built-in-users.html[Built-in users].
+--
+
+. 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}>>.
+--
+
+. Optional: Change the default session duration. By default, sessions stay
+active until the browser is closed. To change the duration, set the
+`xpack.security.sessionTimeout` property in the `kibana.yml` configuration file.
+The timeout is specified in milliseconds. For example, set the timeout to 600000
+to expire sessions after 10 minutes:
++
+--
+[source,yaml]
+--------------------------------------------------------------------------------
+xpack.security.sessionTimeout: 600000
+--------------------------------------------------------------------------------
+--
+
+. Optional: <<configuring-tls,Configure {kib} to encrypt communications>>. 
+
+. Restart {kib}.
+
+. [[kibana-roles]]Choose an authentication mechanism and grant users the privileges they need to
+use {kib}.
++
+--
+For more information on Basic Authentication and additional methods of
+authenticating {kib} users, see <<kibana-authentication>>.
+
+You can manage privileges on the *Management / Security / Roles* page in {kib}.
+
+If you're using the native realm with Basic Authentication, you can assign roles
+using the *Management / Security / Users* page in {kib} or the
+{ref}/security-api.html#security-user-apis[user management APIs]. For example, 
+the following creates a user named `jacknich` and assigns it the `kibana_user` 
+role:
+
+[source,js]
+--------------------------------------------------------------------------------
+POST /_security/user/jacknich
+{
+  "password" : "t0pS3cr3t",
+  "roles" : [ "kibana_user" ]
+}
+--------------------------------------------------------------------------------
+// CONSOLE
+--
+
+. Grant users access to the indices that they will be working with in {kib}.
++
+--
+TIP: You can define as many different roles for your {kib} users as you need.
+
+For example, create roles that have `read` and `view_index_metadata` privileges
+on specific index patterns. For more information, see
+{xpack-ref}/authorization.html[Configuring Role-based Access Control].
+
+--
+
+. Verify that you can log in as a user. If you are running
+{kib} locally, go to `https://localhost:5601` and enter the credentials for a
+user you've assigned a {kib} user role. For example, you could log in as the
+`jacknich` user created above.
++
+--
+
+NOTE: This must be a user who has been assigned the `kibana_user` role.
+{kib} server credentials should only be used internally by the {kib} server.
+
+--
+
+include::authentication/index.asciidoc[]
+include::securing-communications/index.asciidoc[]
+include::audit-logging.asciidoc[]