Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Simplify Beats security docs #11329

Merged
merged 2 commits into from
May 24, 2019
Merged

Simplify Beats security docs #11329

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b0350c9
Simplify Beats security docs
dedemorton Feb 28, 2019
f94d55a
Add changes from review
dedemorton Apr 23, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion libbeat/docs/monitoring/monitoring-beats.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,11 @@ the same {es} cluster, specify the following minimal configuration:
--
[source, yml]
--------------------
monitoring.enabled: true
xpack.monitoring:
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ycombinator When I remove xpack from this, I no longer see Beats monitoring data in Kibana 7.0.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @dedemorton, that would be expected as the new monitoring.* settings were only introduced in 7.1.0: #9260.

Just to avoid confusion, the xpack.monitoring.* settings will continue to be available in 7.1.0 and above. However they will be deprecated in favor of the monitoring.* settings.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, I need to backport this to 7.0, so I will use xpack.monitoring in this PR and then change it back after I backport to 7.1.

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}
Expand Down
179 changes: 33 additions & 146 deletions libbeat/docs/security/basic-auth.asciidoc
View file
Open in desktop
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
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>>.
+
Expand All @@ -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[]
80 changes: 0 additions & 80 deletions libbeat/docs/security/user-access.asciidoc
View file
Open in desktop

This file was deleted.

Loading