Skip to content

Commit

Permalink
[7.1] Backport: Simplify Beats security docs (#11329) (#12287)
Browse files Browse the repository at this point in the history 
* Simplify Beats security docs (#11329)

* Simplify Beats security docs

* Add changes from review

* Apply suggestions from code review

Add attribute substitution to resolve attribute.

* Remove to-do.
  • Loading branch information
@dedemorton
dedemorton authored May 28, 2019
1 parent 949fd68 commit 1d50dd2
Show file tree
Hide file tree
Showing 5 changed files with 227 additions and 274 deletions.
8 changes: 6 additions & 2 deletions libbeat/docs/monitoring/monitoring-beats.asciidoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,9 +37,13 @@ information, see
configured {es} output, specify the following minimal configuration:
+
--
[source, yml]
["source","yml",subs="attributes"]
--------------------
xpack.monitoring.enabled: true
xpack.monitoring:
enabled: true
elasticsearch:
username: {beat_monitoring_user}
password: somepassword
--------------------

If you configured a different output, such as {ls}, you must specify additional
Expand Down
179 changes: 33 additions & 146 deletions libbeat/docs/security/basic-auth.asciidoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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}].
62 changes: 7 additions & 55 deletions libbeat/docs/security/securing-beats.asciidoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,25 +10,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>>.
+
Expand All @@ -44,48 +34,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[]
71 changes: 0 additions & 71 deletions libbeat/docs/security/user-access.asciidoc
View file

This file was deleted.

Loading

0 comments on commit 1d50dd2

Please sign in to comment.