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

[7.1] Backport: Simplify Beats security docs (#11329) #12287

Merged
merged 3 commits into from
May 28, 2019
Merged

[7.1] Backport: Simplify Beats security docs (#11329) #12287

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5935825
Simplify Beats security docs (#11329)
dedemorton May 24, 2019
9c74fc8
Apply suggestions from code review
dedemorton May 24, 2019
4d1a3b1
Remove to-do.
dedemorton May 24, 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 @@ -39,7 +39,11 @@ configured {es} output, specify the following minimal configuration:
--
[source, yml]
dedemorton marked this conversation as resolved.
Show resolved Hide resolved
--------------------
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
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 @@ -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
Open in desktop

This file was deleted.

Loading