Simplify Beats security docs

libbeat/docs/monitoring/monitoring-beats.asciidoc

@@ -40,7 +40,11 @@ the same {es} cluster, specify the following minimal configuration:
 --
 [source, yml]
 --------------------
-monitoring.enabled: true
+xpack.monitoring:
+  enabled: true
+  elasticsearch:
+    username: {beat_monitoring_user}
+    password: somepassword
 --------------------
 
 If you configured a different output, such as {ls} or you want to send {beatname_uc}

libbeat/docs/security/basic-auth.asciidoc

@@ -6,168 +6,55 @@ When sending data to a secured cluster through the `elasticsearch`
 output, {beatname_uc} must either provide basic authentication credentials
 or present a client certificate.
 
-To configure authentication credentials for {beatname_uc}:
+*Before you begin:* <<feature-roles>>.
 
-. Create a writer role that has the following privileges:
-+
---
-ifeval::["{beatname_lc}"!="filebeat"]
-* *Cluster*: `manage_index_templates` and `monitor`
-endif::[]
-ifeval::["{beatname_lc}"=="filebeat"]
-* *Cluster*: `manage_index_templates`, `monitor`, and
-`manage_ingest_pipelines`
-endif::[]
-* *Index*: `write` and `create_index` on the {beatname_uc} indices 
---
-+
-You can create roles from the **Management / Roles** UI in {kib} or through the
-`role` API. For example, the following request creates a role named
-++{beat_default_index_prefix}_writer++:
-+
---
-ifeval::["{beatname_lc}"!="filebeat"]
-["source","sh",subs="attributes,callouts"]
----------------------------------------------------------------
-POST _security/role/{beat_default_index_prefix}_writer
-{
-  "cluster": ["manage_index_templates","monitor"],
-  "indices": [
-    {
-      "names": [ "{beat_default_index_prefix}-*" ], <1>
-      "privileges": ["write","create_index"]
-    }
-  ]
-}
----------------------------------------------------------------
-// CONSOLE
-<1> If you use a custom {beatname_uc} index pattern, specify that pattern
-instead of the default ++{beat_default_index_prefix}-*++ pattern.
-endif::[]
-ifeval::["{beatname_lc}"=="filebeat"]
-["source","sh",subs="attributes,callouts"]
----------------------------------------------------------------
-POST _security/role/{beat_default_index_prefix}_writer
-{
-  "cluster": ["manage_index_templates","monitor","manage_ingest_pipelines"], <1>
-  "indices": [
-    {
-      "names": [ "{beat_default_index_prefix}-*" ], <2>
-      "privileges": ["write","create_index"]
-    }
-  ]
-}
----------------------------------------------------------------
-// CONSOLE
-<1> The `manage_ingest_pipelines` cluster privilege is required to run
-{beatname_uc} modules.
-<2> If you use a custom {beatname_uc} index pattern, specify that pattern
-instead of the default ++{beat_default_index_prefix}-*++ pattern.
-endif::[]
---
-
-ifndef::no_ilm[]
-. If you plan to use {ref}/getting-started-index-lifecycle-management.html[index
-lifecycle management], create a role that has the following privileges. These
-privileges are required to load index lifecycle policies and create and manage
-rollover indices:
-+
-* *Cluster:* `manage_ilm`
-* *Index:* `write`, `create_index`, `manage`, and `manage_ilm` on the 
-{beatname_uc} indices
-+
---
-["source","sh",subs="attributes"]
----------------------------------------------------------------
-POST _xpack/security/role/{beat_default_index_prefix}_ilm
-{
-  "cluster": ["manage_ilm"],
-  "indices": [
-    {
-      "names": [ "{beat_default_index_prefix}-*","shrink-{beat_default_index_prefix}-*"],
-      "privileges": ["write","create_index","manage","manage_ilm"]
-    }
-  ]
-}
----------------------------------------------------------------
-// CONSOLE
---
-endif::no_ilm[]
-
-. Assign the writer role to the user that {beatname_uc} will use to connect to
-{es}. Make sure you also assign any roles that are required for specific
-features. For the list of features and required roles, see <<feature-roles>>.
-
-.. To authenticate as a native user, create a user for {beatname_uc} to use
-internally and assign it the writer role, plus any other roles that are
-needed.
-+
-You can create users from the **Management / Users** UI in {kib} or through the
-`user` API. For example, following request creates a user
-named ++{beat_default_index_prefix}_internal++ that has the
-++{beat_default_index_prefix}_writer++ and `kibana_user` roles:
-+
---
-["source","sh",subs="attributes,callouts"]
----------------------------------------------------------------
-POST /_security/user/{beat_default_index_prefix}_internal
-{
-  "password" : "{pwd}",
-  "roles" : [ "{beat_default_index_prefix}_writer","kibana_user"],
-  "full_name" : "Internal {beatname_uc} User"
-}
----------------------------------------------------------------
-// CONSOLE
+You specify authentication credentials in the {beatname_uc} configuration
+file: 
 
---
-
-.. To use PKI authentication, assign the writer role, plus any other roles that are
-needed, in the `role_mapping.yml` configuration file. Specify the user by the
-distinguished name that appears in its certificate:
+* To use basic authentication, specify the `username` and `password` settings
+under `output.elasticsearch`. For example: 
 +
 --
 ["source","yaml",subs="attributes,callouts"]
----------------------------------------------------------------
-{beat_default_index_prefix}_writer:
-  - "cn=Internal {beatname_uc} User,ou=example,o=com"
-kibana_user:
-  - "cn=Internal {beatname_uc} User,ou=example,o=com"
----------------------------------------------------------------
-
-
-For more information, see
-{xpack-ref}/mapping-roles.html#mapping-roles-file[Using Role Mapping Files].
---
-
-. In the {beatname_uc} configuration file, specify authentication credentials
-for the `elasticsearch` output:
-
-
-.. To use basic authentication, configure the `username` and `password` settings.
-For example, the following {beatname_uc} output configuration uses the native
-++{beat_default_index_prefix}_internal++ user to connect to {es}: 
-+
-["source","js",subs="attributes,callouts"]
---------------------------------------------------
+----
 output.elasticsearch:
   hosts: ["localhost:9200"]
   username: "{beat_default_index_prefix}_internal" <1>
   password: "{pwd}" <2>
---------------------------------------------------
-<1> You created this user earlier.
+----
+<1> Let's assume this user has the privileges required to publish events to
+{es}.
 <2> The example shows a hard-coded password, but you should store sensitive
 values in the <<keystore,secrets keystore>>.
+--
++
+If you've configured the {kib} endpoint, also specify credentials for
+authenticating with {kib}. For example:
++
+["source","yaml",subs="attributes,callouts"]
+----
+setup.kibana:
+  host: "mykibanahost:5601"
+  username: "{beat_default_index_prefix}_internal" <1>
+  password: "{pwd}" 
+----
+<1> Let's assume this user has the privileges required to set up dashboards.
 
-.. To use PKI authentication, configure the `certificate` and `key` settings:
+* To use Public Key Infrastructure (PKI) certificates to authenticate users,
+configure the `certificate` and `key` settings. These settings assume that the
+distinguished name (DN) in the certificate is mapped to the appropriate roles in
+the `role_mapping.yml` file on each node in the {es} cluster. For more
+information, see {xpack-ref}/mapping-roles.html#mapping-roles-file[Using Role
+Mapping Files].
 +
-["source","js",subs="attributes,callouts"]
+["source","yaml",subs="attributes,callouts"]
 --------------------------------------------------
 output.elasticsearch:
   hosts: ["localhost:9200"]
-  ssl.certificate: "/etc/pki/client/cert.pem" <1>
+  ssl.certificate: "/etc/pki/client/cert.pem"
   ssl.key: "/etc/pki/client/cert.key"
 --------------------------------------------------
-<1> The distinguished name (DN) in the certificate must be mapped to
-the ++{beat_default_index_prefix}_writer++ and `kibana_user` roles in the
-`role_mapping.yml` configuration file on each node in the {es} cluster.
 
+To learn more about {stack} security features and other types of
+authentication, see {stack-ov}/elasticsearch-security.html[Securing the
+{stack}].

libbeat/docs/security/securing-beats.asciidoc

@@ -11,25 +11,15 @@ If you want {beatname_uc} to connect to a cluster that has
 {stack-ov}/elasticsearch-security.html[{security}] enabled, there are extra
 configuration steps:
 
-. <<beats-basic-auth>>.
+. <<feature-roles>>.
 +
-ifeval::["{beatname_lc}"=="filebeat"]
-To send data to a secured cluster through the `elasticsearch` output,
-{beatname_uc} needs to authenticate as a user who can manage index templates,
-monitor the cluster, create indices, read and write to the indices
-it creates, and manage ingest pipelines. 
-endif::[]
-ifeval::["{beatname_lc}"!="filebeat"]
-To send data to a secured cluster through the `elasticsearch` output,
-{beatname_uc} needs to authenticate as a user who can manage index templates,
-monitor the cluster, create indices, and read and write to the indices
-it creates. 
-endif::[]
+You can use role-based access control to grant {beatname_uc} users access to
+secured resources. 
 
-. <<beats-user-access>>.
+. <<beats-basic-auth>>.
 +
-To search the indexed {beatname_uc} data and visualize it in {kib}, users need
-access to the indices {beatname_uc} creates.
+To interact with a secured cluster, {beatname_uc} must either provide basic
+authentication credentials or present a client certificate.
 
 . <<beats-tls>>.
 +
@@ -45,48 +35,10 @@ password, set it up now.
 For more information about {security}, see
 {xpack-ref}/elasticsearch-security.html[Securing the {stack}].
 
-[[feature-roles]]
-=== {beatname_uc} features that require authorization
-
-After securing {beatname_uc}, make sure your users have the roles (or associated
-privileges) required to use these {beatname_uc} features. Note that some of the
-roles shown here are {xpack-ref}/built-in-roles.html[built-in], and some
-are user-defined.
-
-[options="header"]
-|=======
-|Feature | Role
-|Send data to a secured cluster   | ++{beat_default_index_prefix}_writer++ footnoteref:[noteA,These roles are user-defined.]
-ifeval::["{beatname_lc}"=="filebeat"]
-|Run Filebeat modules | ++{beat_default_index_prefix}_writer++ footnoteref:[noteA]
-endif::[]
-|Load index templates | ++{beat_default_index_prefix}_writer++ footnoteref:[noteA] and `kibana_user`
-ifndef::no_dashboards[]
-|Load {beatname_uc} dashboards into {kib} | ++{beat_default_index_prefix}_writer++ footnoteref:[noteA] and `kibana_user`
-endif::[]
-ifdef::has_ml_jobs[]
-|Load machine learning jobs | `machine_learning_admin`
-endif::[]
-|Read indices created by {beatname_uc} | ++{beat_default_index_prefix}_reader++ footnoteref:[noteA] 
-ifndef::no_dashboards[]
-|View {beatname_uc} dashboards in {kib} | `kibana_user`
-endif::[]
-ifdef::has_central_config[]
-|Store and manage configurations in a central location in {kib} | `beats_admin`
-endif::[]
-ifndef::no_ilm[]
-|Load index lifecycle policies and use index lifecycle management | +{beatname_lc}_ilm+ footnoteref:[noteA]
-endif::[]
-|=======
-
-To create the user-defined roles shown here, see <<beats-basic-auth>> and
-<<beats-user-access>>. You may want to define additional roles to provide more
-restrictive access.
+include::users.asciidoc[]
 
 include::basic-auth.asciidoc[]
 
-include::user-access.asciidoc[]
-
 include::tls.asciidoc[]
 
 include::beats-system.asciidoc[]