From b0350c968078150673c968ac4301d24279ae69c9 Mon Sep 17 00:00:00 2001 From: dedemorton Date: Thu, 28 Feb 2019 13:52:57 -0800 Subject: [PATCH 1/2] Simplify Beats security docs --- libbeat/docs/security/basic-auth.asciidoc | 179 ++--------- libbeat/docs/security/securing-beats.asciidoc | 68 +--- libbeat/docs/security/user-access.asciidoc | 80 ----- libbeat/docs/security/users.asciidoc | 295 ++++++++++++++++++ 4 files changed, 341 insertions(+), 281 deletions(-) delete mode 100644 libbeat/docs/security/user-access.asciidoc create mode 100644 libbeat/docs/security/users.asciidoc diff --git a/libbeat/docs/security/basic-auth.asciidoc b/libbeat/docs/security/basic-auth.asciidoc index 986b277d6304..fa7ac9de12ca 100644 --- a/libbeat/docs/security/basic-auth.asciidoc +++ b/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:* <>. -. 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 <>. - -.. 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 <>. +-- ++ +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}]. diff --git a/libbeat/docs/security/securing-beats.asciidoc b/libbeat/docs/security/securing-beats.asciidoc index e9d5173fa4f7..d2238dac516f 100644 --- a/libbeat/docs/security/securing-beats.asciidoc +++ b/libbeat/docs/security/securing-beats.asciidoc @@ -7,29 +7,25 @@ Use {security} ++++ +// REVIEWERS: I don't want to duplicate the content in the security docs like we +// have in the past. By the time users are configuring security in Beats, they +// should know their security strategy and how to set up users in the Management +// UI. In the Beats docs, I just want to cover beats-specific requirements. Let +// me know if I'm missing anything. + If you want {beatname_uc} to connect to a cluster that has {stack-ov}/elasticsearch-security.html[{security}] enabled, there are extra configuration steps: -. <>. +. <>. + -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. -. <>. +. <>. + -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. . <>. + @@ -45,48 +41,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 <> and -<>. 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[] diff --git a/libbeat/docs/security/user-access.asciidoc b/libbeat/docs/security/user-access.asciidoc deleted file mode 100644 index fe77d4596faa..000000000000 --- a/libbeat/docs/security/user-access.asciidoc +++ /dev/null @@ -1,80 +0,0 @@ -[role="xpack"] -[[beats-user-access]] -=== Grant users access to {beatname_uc} indices - -To enable users to access the indices {beatname_uc} creates, grant them `read` -and `view_index_metadata` privileges on the {beatname_uc} indices. If they're -using {kib}, they also need the `kibana_user` role. - -ifdef::apm-server[] -X-Pack security provides a built-in role called `apm_user` that you can explicitly assign to users. -This role grants them the necessary `read` and `view_index_metadata` privileges on the {beatname_uc} indices. -endif::apm-server[] - -ifndef::apm-server[] -. Create a role that has the `read` and `view_index_metadata` privileges -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 -++{access_role}++: -+ --- -["source","sh",subs="attributes,callouts"] ---------------------------------------------------------------- -POST _security/role/{access_role} -{ - "indices": [ - { - "names": [ "{beat_default_index_prefix}-*" ], <1> - "privileges": ["read","view_index_metadata"] - } - ] -} ---------------------------------------------------------------- -// CONSOLE -<1> If you use a custom {beatname_uc} index pattern, specify that pattern -instead of the default ++{beat_default_index_prefix}-*++ pattern. --- -endif::apm-server[] - -. Assign your users the ++{access_role}++ -role so they can access the {beatname_uc} indices. -For {kib} users who need to visualize the data, -also assign the `kibana_user` role: - -.. If you're using the `native` realm, you can assign roles with the -**Management > Users** UI in {kib} or through the `user` API. For example, the -following request grants ++{beat_default_index_prefix}_account++ the -++{access_role}++ and `kibana_user` roles: -+ --- -["source", "sh", subs="attributes,callouts"] ---------------------------------------------------------------- -POST /_security/user/{beat_default_index_prefix}_account -{ - "password" : "{pwd}", - "roles" : [ "{access_role}","kibana_user"], - "full_name" : "{beatname_uc} account" -} ---------------------------------------------------------------- -// CONSOLE --- -.. If you're using the LDAP, Active Directory, or PKI realms, -you assign the roles in the `role_mapping.yml` configuration file. -For example, the following snippet grants -++{beat_default_index_prefix}_account++ the -++{access_role}++ and `kibana_user` roles: -+ --- -["source", "yaml", subs="attributes,callouts"] ---------------------------------------------------------------- -{access_role}: - - "cn={beat_default_index_prefix}_account,dc=example,dc=com" -kibana_user: - - "cn={beat_default_index_prefix}_account,dc=example,dc=com" ---------------------------------------------------------------- - -For more information, see -{xpack-ref}/mapping-roles.html#mapping-roles-file[Using Role Mapping Files]. --- diff --git a/libbeat/docs/security/users.asciidoc b/libbeat/docs/security/users.asciidoc new file mode 100644 index 000000000000..1a6b2a40b55a --- /dev/null +++ b/libbeat/docs/security/users.asciidoc @@ -0,0 +1,295 @@ +[role="xpack"] +[[feature-roles]] +=== Grant users access to secured resources + +//TODO: Redirect beats-user-access to feature-roles to prevent 404s. + +// REVIEWERS: Our built-in roles don't provide enough granularity for some users, +// and in some cases, the roles don't cover all the tasks that a single user +// might perform (such as running the setup). Plus the roles don't grant access +// to Beats indices. I list privileges here (rather than roles) so that the person +// setting up security has more flexibility and the knowledge they need to +// create their own roles, if necessary. Is this a likely scenario? + +You can use role-based access control to grant {beatname_uc} users access to +secured resources. The roles that you set up depend on your organization's +security requirements and the minimum privileges required to use specific +features. + +{beatname_uc} users typically perform these main roles: they do the initial +setup, publish monitoring information, and publish events. If they're using +{kib}, they view and sometimes create visualizations that access {beatname_uc} +indices. + +To assign the most restrictive privileges to users, create a role for each +purpose. The easiest way to create roles is by using the +*Management > Security > Roles* UI in {kib}. + +Also consider using the <> provided by +{security}. + +Want to learn more about creating users and roles? See +{stack-ov}/elasticsearch-security.html[Securing the {stack}]. Also see +{stack-ov}/security-privileges.html[Security privileges] for a description of +available privileges. + +// REVIEWERS: I had to grant `monitor` to users to avoid errors, even though I +// didn't enable monitoring. Is this expected? I've added `monitor` to the +// privileges described below. Please let me know how I should handle this in +// the docs. + +[[privileges-to-setup-beats]] +==== Privileges needed for initial setup + +Users who set up {beatname_uc} typically need to load mappings, dashboards, and +other objects used to index data into {es} and visualize it in {kib}. The +privileges required depend on the setup tasks users need to perform: + +[options="header"] +|==== +|Task | Required privileges + +|Set up index templates +|`manage_index_templates` and `monitor` on cluster + +ifndef::no_dashboards[] +.2+|Set up example dashboards +|`monitor` on cluster + +|`index` on `.kibana*` indices +endif::no_dashboards[] + +ifdef::has_ml_jobs[] +.3+|Set up machine learning job configurations +|`manage_ml` and `monitor` on cluster + +|`read` on +{beat_default_index_prefix}-*+ indices + +|`read` and `index` on `.kibana*` indices +endif::has_ml_jobs[] + +ifeval::["{beatname_lc}"=="filebeat"] +|Set up ingest pipelines +|`manage_ingest_pipelines` and `monitor` on cluster +endif::[] + +ifndef::no_ilm[] +|Set up index lifecycle policies +|`manage_ilm` and `monitor` on cluster +endif::no_ilm[] + +ifdef::has_central_config[] +|Enroll and manage configurations in Beats central management +|`all` on `.management-beats` index +endif::has_central_config[] +|==== + +// REVIEWERS: We currently have manage_pipeline and +// manage_ingest_pipelines. How are they different? Which is the correct one to +// use here? + +[[privileges-to-publish-monitoring]] +==== Privileges needed to publish monitoring information + +{security} provides the +{beat_default_index_prefix}_system+ +{stack-ov}/built-in-users.html[built-in user] and ++{beat_default_index_prefix}_system+ {stack-ov}/built-in-roles.html[built-in +role] for sending monitoring information. You can use the built-in user, or +create a user who has the privileges needed to send monitoring information. +If you use the +{beat_default_index_prefix}_system+ user, make sure you +<>. + +[options="header"] +|==== +|Task | Required privileges + +|Send monitoring info | `monitor` on cluster +|==== + +// REVIEWERS: I don't have time to test the full monitoring set up. Is this +// correct, or are additional privileges required? + + +[[privileges-to-publish-events]] +==== Privileges needed to publish events + +Users who publish events to {es} need to create and read from {beatname_uc} +indices. The privileges required for this role depend on the tasks users +need to perform: + +[options="header"] +|==== +|Task | Required privileges + +.2+|Send data to a secured cluster +|`monitor` on cluster + +|`create_index` and `index` on {beatname_uc} indices + +.2+|Send data to a secured cluster when automatic template loading is enabled +footnote:[Automatic template loading is enabled by +default. To disable it, set `setup.template.enabled: false`. Note that you +cannot disable automatic template loading if you're using index lifecycle +management.] + +|`monitor` and `manage_index_templates` on cluster + +|`create_index` and `index` on {beatname_uc} indices + +ifeval::["{beatname_lc}"=="filebeat"] +.2+|Send data to a secured cluster when {beatname_uc} modules are enabled +|`monitor` and `manage_ingest_pipelines` on cluster + +|`create_index` and `index` on {beatname_uc} indices +endif::[] + +.2+|Send data to a secured cluster when index lifecycle management is enabled +|`manage_index_templates` and `monitor` on cluster + +| `index` and `manage` on {beatname_uc} indices +ifdef::has_central_config[] +.2+|Read configurations from Beats central management +| `monitor` on cluster + +|`all` on `.management-beats` index +endif::has_central_config[] +|==== + +//REVIEWERS: Some questions about the above info: +// +// 1 - When is `read_ilm` needed? +// Also, do users need `index` and `manage` on `shrink-beatname-*`, too? +// Are there other privileges that might be required as indices move through the +// lifecycle stages? +// +// 2 - Is there a more restrictive privilege than `all` that we can assign to users who +// need to read configs in central management, but not craete or manage configs? I tried +// `read` on .management-beats but got "ERROR process/process.go:47 Error getting +// process details. pid=35087: error getting process mem for pid=35087: +// Could not read process info for pid 35087" Beats still sent events. + +// REVIEWERS: I have some concerns about how our default config settings affect +// the privileges users need to assign: +// In some cases, users either need to change the defaults that we've set, or +// grant privileges that are less restrictive than they might want. +// For example, on 6.7, I get the following +// error when I run Filebeat (with the system module enabled) +// when the user doesn't have the `manage_ingest_pipelines` cluster +// privilege (this happens even if I load the pipeline in advance): +// +// ERROR fileset/factory.go:142 Error loading pipeline: 1 error: Error loading +// pipeline for fileset system/auth: couldn't load pipeline: couldn't load json +// Error: 403 Forbidden: {"error":{"root_cause":[{"type":"security_exception", +// "reason":"action [cluster:admin/ingest/pipeline/put] is unauthorized for user +//[filebeat_writer]"}] +// +// I thought I would be able to load ingest pipelines as part of the setup +// phase, and run the system module without granting this privilege. I tried +// setting filebeat.overwrite_pipelines: false (even though it's supposedly the +// default), but I still got the error. Is this a bug or expected behavior? +// +// Also note that the default behavior of auto loading the index template +// means that users will need `manage_index_templates` unless they explicitly +// disable automatic template loading. If they are using ILM, however, they +// CANNOT disable automatic template loading. They must grant the user +//`manage_index_templates`, or they will see the following error: +// +// ERROR pipeline/output.go:100 Failed to connect to +// backoff(elasticsearch(http://localhost:9200)): Connection marked as failed +// because the onConnect callback failed: Error loading Elasticsearch template: +// could not load template. Elasticsearch returned: couldn't load template: +// couldn't load json. Error: 403 Forbidden: {"error":{"root_cause" +// [{"type":"security_exception","reason":"action [indices:admin/template/put] +// is unauthorized for user [filebeat_writer]"}],"type":"security_exception", +// "reason":"action [indices:admin/template/put] is unauthorized for user +// [filebeat_writer]"},"status":403} +// + + +[[kibana-user-privileges]] +==== Privileges needed by {kib} users + +{kib} users typically need to view dashboards and visualizations that contain +{beatname_uc} data. These users might also need to create and edit dashboards +and visualizations. +ifdef::has_central_config[] +If you're using Beats central management, they need to create and manage +configurations. +endif::has_central_config[] + +The privileges required for {kib} users depend on the tasks they need to +perform: + +[options="header"] +|==== +|Task | Required privileges + +.2+|View {beatname_uc} dashboards +|`read` on {beatname_uc} indices + +|`read` on `.kibana*` indices + +.2+|View and edit {beatname_uc} dashboards +|`read` on {beatname_uc} indices + +|`manage`, `read`, `index`, and `delete` on `.kibana*` indices + +ifdef::has_central_config[] +.2+|Create and manage configurations in Beats central management +|`all` on `.management-beats` index + +|`manage`, `read`, `index`, and `delete` on `.kibana*` indices +endif::[] +|==== + +// REVIEWERS: Granting `read` on the .kibana* indices results +// in the message "[warning][deprecated][security] username relies +// on index privileges on the Kibana index. This is deprecated and will be +// removed in Kibana 7.0". +// +// What should I use instead? + +// REVIEWERS: It seems like the CM UI expects the user to have the beats_admin +// role. Is that true? If so, then all users who define configs in central +// management will need beats_admin and kibana_user roles. What if a user +// wants to create a custom role that has all the privileges in a single role? +// Is that possible? + +[[built-in-beats-roles]] +==== Built-in roles for Beats users + +For your convenience, {security} provides built-in roles that you can assign to +your users. These roles group related privileges, but they may not provide all +the privileges required for your users. For example, the roles don't grant +access to {beatname_uc} indices. + +Here's a list of roles you might want to assign to {beatname_uc} users. For a +full description of these and other available roles, see +{stack-ov}/built-in-roles.html[built-in roles]. + + +[options="header"] +|==== +|Role | Uses + +ifdef::has_ml_jobs[] +|`machine_learning_admin` +|Set up and manage machine learning job configurations +endif::has_ml_jobs[] + +ifeval::["{beatname_lc}"=="filebeat"] +|`ingest_admin` +|Set up ingest pipelines +endif::[] + +ifdef::has_central_config[] +|`beats_admin` +|Create and manage configurations in Beats central management +endif::has_central_config[] + +|`kibana_dashboard_only_user` +|View dashboards (read-only view) in {kib} + +|`kibana_user` +|View dashboards and use editing tools in {kib} +|==== From f94d55a6eeb510959de7d3b025adec1f6f528a25 Mon Sep 17 00:00:00 2001 From: dedemorton Date: Mon, 22 Apr 2019 17:52:21 -0700 Subject: [PATCH 2/2] Add changes from review --- .../docs/monitoring/monitoring-beats.asciidoc | 6 +- libbeat/docs/security/securing-beats.asciidoc | 6 - libbeat/docs/security/users.asciidoc | 255 +++++------------- 3 files changed, 76 insertions(+), 191 deletions(-) diff --git a/libbeat/docs/monitoring/monitoring-beats.asciidoc b/libbeat/docs/monitoring/monitoring-beats.asciidoc index f9dee1ed6f66..3a85a73ab401 100644 --- a/libbeat/docs/monitoring/monitoring-beats.asciidoc +++ b/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} diff --git a/libbeat/docs/security/securing-beats.asciidoc b/libbeat/docs/security/securing-beats.asciidoc index d2238dac516f..13b55dc15963 100644 --- a/libbeat/docs/security/securing-beats.asciidoc +++ b/libbeat/docs/security/securing-beats.asciidoc @@ -7,12 +7,6 @@ Use {security} ++++ -// REVIEWERS: I don't want to duplicate the content in the security docs like we -// have in the past. By the time users are configuring security in Beats, they -// should know their security strategy and how to set up users in the Management -// UI. In the Beats docs, I just want to cover beats-specific requirements. Let -// me know if I'm missing anything. - If you want {beatname_uc} to connect to a cluster that has {stack-ov}/elasticsearch-security.html[{security}] enabled, there are extra configuration steps: diff --git a/libbeat/docs/security/users.asciidoc b/libbeat/docs/security/users.asciidoc index 1a6b2a40b55a..cb6b78b3f2a5 100644 --- a/libbeat/docs/security/users.asciidoc +++ b/libbeat/docs/security/users.asciidoc @@ -4,92 +4,78 @@ //TODO: Redirect beats-user-access to feature-roles to prevent 404s. -// REVIEWERS: Our built-in roles don't provide enough granularity for some users, -// and in some cases, the roles don't cover all the tasks that a single user -// might perform (such as running the setup). Plus the roles don't grant access -// to Beats indices. I list privileges here (rather than roles) so that the person -// setting up security has more flexibility and the knowledge they need to -// create their own roles, if necessary. Is this a likely scenario? - -You can use role-based access control to grant {beatname_uc} users access to -secured resources. The roles that you set up depend on your organization's -security requirements and the minimum privileges required to use specific -features. +You can use role-based access control to grant users access to secured +resources. The roles that you set up depend on your organization's security +requirements and the minimum privileges required to use specific features. {beatname_uc} users typically perform these main roles: they do the initial setup, publish monitoring information, and publish events. If they're using {kib}, they view and sometimes create visualizations that access {beatname_uc} indices. -To assign the most restrictive privileges to users, create a role for each -purpose. The easiest way to create roles is by using the -*Management > Security > Roles* UI in {kib}. +{security} provides pre-built roles that grant _some_ of the privileges needed +by {beatname_uc} users. When possible, use the built-in roles to minimize the +affect of future changes on your security strategy. -Also consider using the <> provided by -{security}. +For privileges not granted by existing roles, create new roles. At a minimum, +create a role for setting up {beatname_uc}, a role for publishing events, and a +role for reading {beatname_uc} indices. Assign these new roles, along with the +pre-built roles, to grant the full set of privileges required by {beatname_uc} +users. -Want to learn more about creating users and roles? See -{stack-ov}/elasticsearch-security.html[Securing the {stack}]. Also see -{stack-ov}/security-privileges.html[Security privileges] for a description of -available privileges. - -// REVIEWERS: I had to grant `monitor` to users to avoid errors, even though I -// didn't enable monitoring. Is this expected? I've added `monitor` to the -// privileges described below. Please let me know how I should handle this in -// the docs. +The following sections describe the privileges and roles required to perform +specific job roles. [[privileges-to-setup-beats]] ==== Privileges needed for initial setup Users who set up {beatname_uc} typically need to load mappings, dashboards, and other objects used to index data into {es} and visualize it in {kib}. The -privileges required depend on the setup tasks users need to perform: +privileges required depend on the setup tasks users need to perform. + +NOTE: These instructions assume that you are using the default name for +{beatname_uc} indices. If you are using a custom name, modify the privileges to +match your index naming pattern. [options="header"] |==== -|Task | Required privileges +|Task | Required privileges and roles -|Set up index templates +.3+|Set up index templates |`manage_index_templates` and `monitor` on cluster +|`manage_ilm` on cluster (if cluster supports index lifecycle management) +|`manage` on +{beat_default_index_prefix}-*+ indices (if cluster supports index lifecycle management) ifndef::no_dashboards[] -.2+|Set up example dashboards -|`monitor` on cluster - -|`index` on `.kibana*` indices +|Set up example dashboards +|`kibana_user` role endif::no_dashboards[] ifdef::has_ml_jobs[] .3+|Set up machine learning job configurations |`manage_ml` and `monitor` on cluster - |`read` on +{beat_default_index_prefix}-*+ indices - -|`read` and `index` on `.kibana*` indices +|`kibana_user` role endif::has_ml_jobs[] ifeval::["{beatname_lc}"=="filebeat"] -|Set up ingest pipelines -|`manage_ingest_pipelines` and `monitor` on cluster +.2+|Set up ingest pipelines +|`monitor` on cluster +|`ingest_admin` role endif::[] -ifndef::no_ilm[] -|Set up index lifecycle policies -|`manage_ilm` and `monitor` on cluster -endif::no_ilm[] +.2+|Set up index lifecycle policies +|`manage_ilm`, `manage_index_templates`, and `monitor` on cluster +|`manage` on +{beat_default_index_prefix}-*+ indices ifdef::has_central_config[] |Enroll and manage configurations in Beats central management -|`all` on `.management-beats` index +|`beats_admin` and `kibana_user` roles endif::has_central_config[] |==== -// REVIEWERS: We currently have manage_pipeline and -// manage_ingest_pipelines. How are they different? Which is the correct one to -// use here? - [[privileges-to-publish-monitoring]] -==== Privileges needed to publish monitoring information +==== Privileges needed to publish and view monitoring information {security} provides the +{beat_default_index_prefix}_system+ {stack-ov}/built-in-users.html[built-in user] and @@ -101,13 +87,14 @@ If you use the +{beat_default_index_prefix}_system+ user, make sure you [options="header"] |==== -|Task | Required privileges +|Task | Required privileges and roles -|Send monitoring info | `monitor` on cluster -|==== +|Send monitoring info +|`monitor` on cluster -// REVIEWERS: I don't have time to test the full monitoring set up. Is this -// correct, or are additional privileges required? +|Use *Stack Monitoring* in {kib} to monitor {beatname_uc} +|`monitoring_user` and `kibana_user` roles +|==== [[privileges-to-publish-events]] @@ -119,92 +106,36 @@ need to perform: [options="header"] |==== -|Task | Required privileges +|Task | Required privileges and roles -.2+|Send data to a secured cluster +.3+|Send data to a secured cluster without index lifecycle management |`monitor` on cluster - -|`create_index` and `index` on {beatname_uc} indices - -.2+|Send data to a secured cluster when automatic template loading is enabled -footnote:[Automatic template loading is enabled by -default. To disable it, set `setup.template.enabled: false`. Note that you -cannot disable automatic template loading if you're using index lifecycle -management.] - -|`monitor` and `manage_index_templates` on cluster - -|`create_index` and `index` on {beatname_uc} indices - ifeval::["{beatname_lc}"=="filebeat"] -.2+|Send data to a secured cluster when {beatname_uc} modules are enabled -|`monitor` and `manage_ingest_pipelines` on cluster - -|`create_index` and `index` on {beatname_uc} indices +(and `manage_pipeline` if {beatname_uc} modules are used) endif::[] +|`create_index` and `index` on +{beat_default_index_prefix}-*+ indices +|also requires privileges to <> +unless you've disabled automatic template loading + +.2+|Send data to a secured cluster that supports index lifecycle management +|`manage_index_templates`,`manage_ilm` footnote:[Use `read_ilm` instead of +`manage_ilm` if you pre-loaded the lifecycle policy], and `monitor` +on cluster +ifeval::["{beatname_lc}"=="filebeat"] +(and `manage_pipeline` if {beatname_uc} modules are used) +endif::[] +| `index` and `manage` on +{beat_default_index_prefix}-*+ indices -.2+|Send data to a secured cluster when index lifecycle management is enabled -|`manage_index_templates` and `monitor` on cluster - -| `index` and `manage` on {beatname_uc} indices ifdef::has_central_config[] .2+|Read configurations from Beats central management | `monitor` on cluster - -|`all` on `.management-beats` index +|`beats_admin` role endif::has_central_config[] |==== -//REVIEWERS: Some questions about the above info: -// -// 1 - When is `read_ilm` needed? -// Also, do users need `index` and `manage` on `shrink-beatname-*`, too? +// REVIEWERS: Do users need `index` and `manage` on `shrink-beatname-*`, too? // Are there other privileges that might be required as indices move through the // lifecycle stages? -// -// 2 - Is there a more restrictive privilege than `all` that we can assign to users who -// need to read configs in central management, but not craete or manage configs? I tried -// `read` on .management-beats but got "ERROR process/process.go:47 Error getting -// process details. pid=35087: error getting process mem for pid=35087: -// Could not read process info for pid 35087" Beats still sent events. - -// REVIEWERS: I have some concerns about how our default config settings affect -// the privileges users need to assign: -// In some cases, users either need to change the defaults that we've set, or -// grant privileges that are less restrictive than they might want. -// For example, on 6.7, I get the following -// error when I run Filebeat (with the system module enabled) -// when the user doesn't have the `manage_ingest_pipelines` cluster -// privilege (this happens even if I load the pipeline in advance): -// -// ERROR fileset/factory.go:142 Error loading pipeline: 1 error: Error loading -// pipeline for fileset system/auth: couldn't load pipeline: couldn't load json -// Error: 403 Forbidden: {"error":{"root_cause":[{"type":"security_exception", -// "reason":"action [cluster:admin/ingest/pipeline/put] is unauthorized for user -//[filebeat_writer]"}] -// -// I thought I would be able to load ingest pipelines as part of the setup -// phase, and run the system module without granting this privilege. I tried -// setting filebeat.overwrite_pipelines: false (even though it's supposedly the -// default), but I still got the error. Is this a bug or expected behavior? -// -// Also note that the default behavior of auto loading the index template -// means that users will need `manage_index_templates` unless they explicitly -// disable automatic template loading. If they are using ILM, however, they -// CANNOT disable automatic template loading. They must grant the user -//`manage_index_templates`, or they will see the following error: -// -// ERROR pipeline/output.go:100 Failed to connect to -// backoff(elasticsearch(http://localhost:9200)): Connection marked as failed -// because the onConnect callback failed: Error loading Elasticsearch template: -// could not load template. Elasticsearch returned: couldn't load template: -// couldn't load json. Error: 403 Forbidden: {"error":{"root_cause" -// [{"type":"security_exception","reason":"action [indices:admin/template/put] -// is unauthorized for user [filebeat_writer]"}],"type":"security_exception", -// "reason":"action [indices:admin/template/put] is unauthorized for user -// [filebeat_writer]"},"status":403} -// - [[kibana-user-privileges]] ==== Privileges needed by {kib} users @@ -222,74 +153,30 @@ perform: [options="header"] |==== -|Task | Required privileges +|Task | Required privileges and roles .2+|View {beatname_uc} dashboards -|`read` on {beatname_uc} indices - -|`read` on `.kibana*` indices +|`read` on +{beat_default_index_prefix}-*+ indices +|`kibana_dashboard_only_user` role .2+|View and edit {beatname_uc} dashboards -|`read` on {beatname_uc} indices - -|`manage`, `read`, `index`, and `delete` on `.kibana*` indices +|`read` on +{beat_default_index_prefix}-*+ indices +|`kibana_user` role ifdef::has_central_config[] .2+|Create and manage configurations in Beats central management -|`all` on `.management-beats` index - -|`manage`, `read`, `index`, and `delete` on `.kibana*` indices +|`beats_admin` role +|`kibana_user` role endif::[] |==== -// REVIEWERS: Granting `read` on the .kibana* indices results -// in the message "[warning][deprecated][security] username relies -// on index privileges on the Kibana index. This is deprecated and will be -// removed in Kibana 7.0". -// -// What should I use instead? - -// REVIEWERS: It seems like the CM UI expects the user to have the beats_admin -// role. Is that true? If so, then all users who define configs in central -// management will need beats_admin and kibana_user roles. What if a user -// wants to create a custom role that has all the privileges in a single role? -// Is that possible? - -[[built-in-beats-roles]] -==== Built-in roles for Beats users - -For your convenience, {security} provides built-in roles that you can assign to -your users. These roles group related privileges, but they may not provide all -the privileges required for your users. For example, the roles don't grant -access to {beatname_uc} indices. - -Here's a list of roles you might want to assign to {beatname_uc} users. For a -full description of these and other available roles, see -{stack-ov}/built-in-roles.html[built-in roles]. - - -[options="header"] -|==== -|Role | Uses - -ifdef::has_ml_jobs[] -|`machine_learning_admin` -|Set up and manage machine learning job configurations -endif::has_ml_jobs[] - -ifeval::["{beatname_lc}"=="filebeat"] -|`ingest_admin` -|Set up ingest pipelines -endif::[] - -ifdef::has_central_config[] -|`beats_admin` -|Create and manage configurations in Beats central management -endif::has_central_config[] +[[learn-more-security]] +==== Learn more about users and roles -|`kibana_dashboard_only_user` -|View dashboards (read-only view) in {kib} +Want to learn more about creating users and roles? See +{stack-ov}/elasticsearch-security.html[Securing the {stack}]. Also see: -|`kibana_user` -|View dashboards and use editing tools in {kib} -|==== +* {stack-ov}/security-privileges.html[Security privileges] for a description of +available privileges +* {stack-ov}/built-in-roles.html[Built-in roles] for a description of roles that +you can assign to users \ No newline at end of file