[DOCS] Reorganizes RBAC documentation
This commit is contained in:
lcawl
parent
7b6d0faec2
commit
4f41018753
|
|
@ -0,0 +1,114 @@
|
||||||
|
[role="xpack"]
|
||||||
|
[[built-in-roles]]
|
||||||
|
=== Built-in roles
|
||||||
|
|
||||||
|
{security} applies a default role to all users, including
|
||||||
|
<<anonymous-access, anonymous users>>. The default role enables users to access
|
||||||
|
the authenticate endpoint, change their own passwords, and get information about
|
||||||
|
themselves.
|
||||||
|
|
||||||
|
{security} also provides a set of built-in roles you can explicitly assign
|
||||||
|
to users. These roles have a fixed set of privileges and cannot be updated.
|
||||||
|
|
||||||
|
[[built-in-roles-ingest-user]] `ingest_admin` ::
|
||||||
|
Grants access to manage *all* index templates and *all* ingest pipeline configurations.
|
||||||
|
+
|
||||||
|
NOTE: This role does *not* provide the ability to create indices; those privileges
|
||||||
|
must be defined in a separate role.
|
||||||
|
|
||||||
|
[[built-in-roles-kibana-dashboard]] `kibana_dashboard_only_user` ::
|
||||||
|
Grants access to the {kib} Dashboard and read-only permissions on the `.kibana`
|
||||||
|
index. This role does not have access to editing tools in {kib}. For more
|
||||||
|
information, see
|
||||||
|
{kibana-ref}/xpack-dashboard-only-mode.html[{kib} Dashboard Only Mode].
|
||||||
|
|
||||||
|
[[built-in-roles-kibana-system]] `kibana_system` ::
|
||||||
|
Grants access necessary for the {kib} system user to read from and write to the
|
||||||
|
{kib} indices, manage index templates, and check the availability of the {es} cluster.
|
||||||
|
This role grants read access to the `.monitoring-*` indices and read and write access
|
||||||
|
to the `.reporting-*` indices. For more information, see
|
||||||
|
{kibana-ref}/using-kibana-with-security.html[Configuring Security in {kib}].
|
||||||
|
+
|
||||||
|
NOTE: This role should not be assigned to users as the granted permissions may
|
||||||
|
change between releases.
|
||||||
|
|
||||||
|
[[built-in-roles-kibana-user]] `kibana_user`::
|
||||||
|
Grants the minimum privileges required for any user of {kib}. This role grants
|
||||||
|
access to the {kib} indices and grants monitoring privileges for the cluster.
|
||||||
|
|
||||||
|
[[built-in-roles-logstash-admin]] `logstash_admin` ::
|
||||||
|
Grants access to the `.logstash*` indices for managing configurations.
|
||||||
|
|
||||||
|
[[built-in-roles-logstash-system]] `logstash_system` ::
|
||||||
|
Grants access necessary for the Logstash system user to send system-level data
|
||||||
|
(such as monitoring) to {es}. For more information, see
|
||||||
|
{logstash-ref}/ls-security.html[Configuring Security in Logstash].
|
||||||
|
+
|
||||||
|
NOTE: This role should not be assigned to users as the granted permissions may
|
||||||
|
change between releases.
|
||||||
|
+
|
||||||
|
NOTE: This role does not provide access to the logstash indices and is not
|
||||||
|
suitable for use within a Logstash pipeline.
|
||||||
|
|
||||||
|
[[built-in-roles-beats-system]] `beats_system` ::
|
||||||
|
Grants access necessary for the Beats system user to send system-level data
|
||||||
|
(such as monitoring) to {es}.
|
||||||
|
+
|
||||||
|
NOTE: This role should not be assigned to users as the granted permissions may
|
||||||
|
change between releases.
|
||||||
|
+
|
||||||
|
NOTE: This role does not provide access to the beats indices and is not
|
||||||
|
suitable for writing beats output to {es}.
|
||||||
|
|
||||||
|
[[built-in-roles-ml-admin]] `machine_learning_admin`::
|
||||||
|
Grants `manage_ml` cluster privileges and read access to the `.ml-*` indices.
|
||||||
|
|
||||||
|
[[built-in-roles-ml-user]] `machine_learning_user`::
|
||||||
|
Grants the minimum privileges required to view {xpackml} configuration,
|
||||||
|
status, and results. This role grants `monitor_ml` cluster privileges and
|
||||||
|
read access to the `.ml-notifications` and `.ml-anomalies*` indices,
|
||||||
|
which store {ml} results.
|
||||||
|
|
||||||
|
[[built-in-roles-monitoring-user]] `monitoring_user`::
|
||||||
|
Grants the minimum privileges required for any user of {monitoring} other than those
|
||||||
|
required to use {kib}. This role grants access to the monitoring indices and grants
|
||||||
|
privileges necessary for reading basic cluster information. Monitoring users should
|
||||||
|
also be assigned the `kibana_user` role.
|
||||||
|
|
||||||
|
[[built-in-roles-remote-monitoring-agent]] `remote_monitoring_agent`::
|
||||||
|
Grants the minimum privileges required for a remote monitoring agent to write data
|
||||||
|
into this cluster.
|
||||||
|
|
||||||
|
[[built-in-roles-reporting-user]] `reporting_user`::
|
||||||
|
Grants the specific privileges required for users of {reporting} other than those
|
||||||
|
required to use {kib}. This role grants access to the reporting indices. Reporting
|
||||||
|
users should also be assigned the `kibana_user` role and a role that grants them
|
||||||
|
access to the data that will be used to generate reports with.
|
||||||
|
|
||||||
|
[[built-in-roles-superuser]] `superuser`::
|
||||||
|
Grants full access to the cluster, including all indices and data. A user with
|
||||||
|
the `superuser` role can also manage users and roles and
|
||||||
|
<<run-as-privilege, impersonate>> any other user in the system. Due to the
|
||||||
|
permissive nature of this role, take extra care when assigning it to a user.
|
||||||
|
|
||||||
|
[[built-in-roles-transport-client]] `transport_client`::
|
||||||
|
Grants the privileges required to access the cluster through the Java Transport
|
||||||
|
Client. The Java Transport Client fetches information about the nodes in the
|
||||||
|
cluster using the _Node Liveness API_ and the _Cluster State API_ (when
|
||||||
|
sniffing is enabled). Assign your users this role if they use the
|
||||||
|
Transport Client.
|
||||||
|
+
|
||||||
|
NOTE: Using the Transport Client effectively means the users are granted access
|
||||||
|
to the cluster state. This means users can view the metadata over all indices,
|
||||||
|
index templates, mappings, node and basically everything about the cluster.
|
||||||
|
However, this role does not grant permission to view the data in all indices.
|
||||||
|
|
||||||
|
[[built-in-roles-watcher-admin]] `watcher_admin`::
|
||||||
|
+
|
||||||
|
Grants write access to the `.watches` index, read access to the watch history and
|
||||||
|
the triggered watches index and allows to execute all watcher actions.
|
||||||
|
|
||||||
|
[[built-in-roles-watcher-user]] `watcher_user`::
|
||||||
|
+
|
||||||
|
Grants read access to the `.watches` index, the get watch action and the watcher
|
||||||
|
stats.
|
||||||
|
|
@ -0,0 +1,175 @@
|
||||||
|
[role="xpack"]
|
||||||
|
[[defining-roles]]
|
||||||
|
=== Defining roles
|
||||||
|
|
||||||
|
A role is defined by the following JSON structure:
|
||||||
|
|
||||||
|
[source,js]
|
||||||
|
-----
|
||||||
|
{
|
||||||
|
"run_as": [ ... ], <1>
|
||||||
|
"cluster": [ ... ], <2>
|
||||||
|
"indices": [ ... ] <3>
|
||||||
|
}
|
||||||
|
-----
|
||||||
|
<1> A list of usernames the owners of this role can <<run-as-privilege, impersonate>>.
|
||||||
|
<2> A list of cluster privileges. These privileges define the
|
||||||
|
cluster level actions users with this role are able to execute. This field
|
||||||
|
is optional (missing `cluster` privileges effectively mean no cluster level
|
||||||
|
permissions).
|
||||||
|
<3> A list of indices permissions entries. This field is optional (missing `indices`
|
||||||
|
privileges effectively mean no index level permissions).
|
||||||
|
|
||||||
|
[[valid-role-name]]
|
||||||
|
NOTE: Role names must be at least 1 and no more than 1024 characters. They can
|
||||||
|
contain alphanumeric characters (`a-z`, `A-Z`, `0-9`), spaces,
|
||||||
|
punctuation, and printable symbols in the https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)[Basic Latin (ASCII) block].
|
||||||
|
Leading or trailing whitespace is not allowed.
|
||||||
|
|
||||||
|
The following describes the structure of an indices permissions entry:
|
||||||
|
|
||||||
|
[source,js]
|
||||||
|
-------
|
||||||
|
{
|
||||||
|
"names": [ ... ], <1>
|
||||||
|
"privileges": [ ... ], <2>
|
||||||
|
"field_security" : { ... }, <3>
|
||||||
|
"query": "..." <4>
|
||||||
|
}
|
||||||
|
-------
|
||||||
|
<1> A list of indices (or index name patterns) to which the permissions in this
|
||||||
|
entry apply.
|
||||||
|
<2> The index level privileges the owners of the role have on the associated
|
||||||
|
indices (those indices that are specified in the `name` field)
|
||||||
|
<3> Specification for document fields the owners of the role have read access to.
|
||||||
|
See <<field-and-document-access-control>> for details.
|
||||||
|
<4> A search query that defines the documents the owners of the role have read
|
||||||
|
access to. A document within the associated indices must match this query
|
||||||
|
in order for it to be accessible by the owners of the role.
|
||||||
|
|
||||||
|
[TIP]
|
||||||
|
==============================================================================
|
||||||
|
When specifying index names, you can use indices and aliases with their full
|
||||||
|
names or regular expressions that refer to multiple indices.
|
||||||
|
|
||||||
|
* Wildcard (default) - simple wildcard matching where `*` is a placeholder
|
||||||
|
for zero or more characters, `?` is a placeholder for a single character
|
||||||
|
and `\` may be used as an escape character.
|
||||||
|
|
||||||
|
* Regular Expressions - A more powerful syntax for matching more complex
|
||||||
|
patterns. This regular expression is based on Lucene's regexp automaton
|
||||||
|
syntax. To enable this syntax, it must be wrapped within a pair of
|
||||||
|
forward slashes (`/`). Any pattern starting with `/` and not ending with
|
||||||
|
`/` is considered to be malformed.
|
||||||
|
|
||||||
|
.Example Regular Expressions
|
||||||
|
[source,yaml]
|
||||||
|
------------------------------------------------------------------------------
|
||||||
|
"foo-bar": # match the literal `foo-bar`
|
||||||
|
"foo-*": # match anything beginning with "foo-"
|
||||||
|
"logstash-201?-*": # ? matches any one character
|
||||||
|
"/.*-201[0-9]-.*/": # use a regex to match anything containing 2010-2019
|
||||||
|
"/foo": # syntax error - missing final /
|
||||||
|
------------------------------------------------------------------------------
|
||||||
|
==============================================================================
|
||||||
|
|
||||||
|
The following snippet shows an example definition of a `clicks_admin` role:
|
||||||
|
|
||||||
|
[source,js]
|
||||||
|
-----------
|
||||||
|
{
|
||||||
|
"run_as": [ "clicks_watcher_1" ]
|
||||||
|
"cluster": [ "monitor" ],
|
||||||
|
"indices": [
|
||||||
|
{
|
||||||
|
"names": [ "events-*" ],
|
||||||
|
"privileges": [ "read" ],
|
||||||
|
"field_security" : {
|
||||||
|
"grant" : [ "category", "@timestamp", "message" ]
|
||||||
|
},
|
||||||
|
"query": "{\"match\": {\"category\": \"click\"}}"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
-----------
|
||||||
|
|
||||||
|
Based on the above definition, users owning the `clicks_admin` role can:
|
||||||
|
|
||||||
|
* Impersonate the `clicks_watcher_1` user and execute requests on its behalf.
|
||||||
|
* Monitor the {es} cluster
|
||||||
|
* Read data from all indices prefixed with `events-`
|
||||||
|
* Within these indices, only read the events of the `click` category
|
||||||
|
* Within these document, only read the `category`, `@timestamp` and `message`
|
||||||
|
fields.
|
||||||
|
|
||||||
|
TIP: For a complete list of available <<security-privileges, cluster and indices privileges>>
|
||||||
|
|
||||||
|
There are two available mechanisms to define roles: using the _Role Management APIs_
|
||||||
|
or in local files on the {es} nodes. {security} also supports implementing
|
||||||
|
custom roles providers. If you need to integrate with another system to retrieve
|
||||||
|
user roles, you can build a custom roles provider plugin. For more information,
|
||||||
|
see <<custom-roles-provider, Custom Roles Provider Extension>>.
|
||||||
|
|
||||||
|
[float]
|
||||||
|
[[roles-management-ui]]
|
||||||
|
=== Role management UI
|
||||||
|
|
||||||
|
{security} enables you to easily manage users and roles from within {kib}. To
|
||||||
|
manage roles, log in to {kib} and go to *Management / Elasticsearch / Roles*.
|
||||||
|
|
||||||
|
[float]
|
||||||
|
[[roles-management-api]]
|
||||||
|
=== Role management API
|
||||||
|
|
||||||
|
The _Role Management APIs_ enable you to add, update, remove and retrieve roles
|
||||||
|
dynamically. When you use the APIs to manage roles in the `native` realm, the
|
||||||
|
roles are stored in an internal {es} index. For more information and examples,
|
||||||
|
see {ref}/security-api-roles.html[Role Management APIs].
|
||||||
|
|
||||||
|
[float]
|
||||||
|
[[roles-management-file]]
|
||||||
|
=== File-based role management
|
||||||
|
|
||||||
|
Apart from the _Role Management APIs_, roles can also be defined in local
|
||||||
|
`roles.yml` file located in `CONFIG_DIR`. This is a YAML file where each
|
||||||
|
role definition is keyed by its name.
|
||||||
|
|
||||||
|
[IMPORTANT]
|
||||||
|
==============================
|
||||||
|
If the same role name is used in the `roles.yml` file and through the
|
||||||
|
_Role Management APIs_, the role found in the file will be used.
|
||||||
|
==============================
|
||||||
|
|
||||||
|
While the _Role Management APIs_ is the preferred mechanism to define roles,
|
||||||
|
using the `roles.yml` file becomes useful if you want to define fixed roles that
|
||||||
|
no one (beside an administrator having physical access to the {es} nodes)
|
||||||
|
would be able to change.
|
||||||
|
|
||||||
|
[IMPORTANT]
|
||||||
|
==============================
|
||||||
|
The `roles.yml` file is managed locally by the node and is not globally by the
|
||||||
|
cluster. This means that with a typical multi-node cluster, the exact same
|
||||||
|
changes need to be applied on each and every node in the cluster.
|
||||||
|
|
||||||
|
A safer approach would be to apply the change on one of the nodes and have the
|
||||||
|
`roles.yml` distributed/copied to all other nodes in the cluster (either
|
||||||
|
manually or using a configuration management system such as Puppet or Chef).
|
||||||
|
==============================
|
||||||
|
|
||||||
|
The following snippet shows an example of the `roles.yml` file configuration:
|
||||||
|
|
||||||
|
[source,yaml]
|
||||||
|
-----------------------------------
|
||||||
|
click_admins:
|
||||||
|
run_as: [ 'clicks_watcher_1' ]
|
||||||
|
cluster: [ 'monitor' ]
|
||||||
|
indices:
|
||||||
|
- names: [ 'events-*' ]
|
||||||
|
privileges: [ 'read' ]
|
||||||
|
field_security:
|
||||||
|
grant: ['category', '@timestamp', 'message' ]
|
||||||
|
query: '{"match": {"category": "click"}}'
|
||||||
|
-----------------------------------
|
||||||
|
|
||||||
|
{security} continuously monitors the `roles.yml` file and automatically picks
|
||||||
|
up and applies any changes to it.
|
||||||
|
|
@ -49,295 +49,11 @@ As an administrator, you will need to define the roles that you want to use,
|
||||||
then assign users to the roles. These can be assigned to users in a number of
|
then assign users to the roles. These can be assigned to users in a number of
|
||||||
ways depending on the realms by which the users are authenticated.
|
ways depending on the realms by which the users are authenticated.
|
||||||
|
|
||||||
[[built-in-roles]]
|
include::built-in-roles.asciidoc[]
|
||||||
=== Built-in roles
|
|
||||||
|
|
||||||
{security} applies a default role to all users, including
|
include::managing-roles.asciidoc[]
|
||||||
<<anonymous-access, anonymous users>>. The default role enables users to access
|
|
||||||
the authenticate endpoint, change their own passwords, and get information about
|
|
||||||
themselves.
|
|
||||||
|
|
||||||
{security} also provides a set of built-in roles you can explicitly assign
|
include::privileges.asciidoc[]
|
||||||
to users. These roles have a fixed set of privileges and cannot be updated.
|
|
||||||
|
|
||||||
[[built-in-roles-ingest-user]] `ingest_admin` ::
|
|
||||||
Grants access to manage *all* index templates and *all* ingest pipeline configurations.
|
|
||||||
+
|
|
||||||
NOTE: This role does *not* provide the ability to create indices; those privileges
|
|
||||||
must be defined in a separate role.
|
|
||||||
|
|
||||||
[[built-in-roles-kibana-dashboard]] `kibana_dashboard_only_user` ::
|
|
||||||
Grants access to the {kib} Dashboard and read-only permissions on the `.kibana`
|
|
||||||
index. This role does not have access to editing tools in {kib}. For more
|
|
||||||
information, see
|
|
||||||
{kibana-ref}/xpack-dashboard-only-mode.html[{kib} Dashboard Only Mode].
|
|
||||||
|
|
||||||
[[built-in-roles-kibana-system]] `kibana_system` ::
|
|
||||||
Grants access necessary for the {kib} system user to read from and write to the
|
|
||||||
{kib} indices, manage index templates, and check the availability of the {es} cluster.
|
|
||||||
This role grants read access to the `.monitoring-*` indices and read and write access
|
|
||||||
to the `.reporting-*` indices. For more information, see
|
|
||||||
{kibana-ref}/using-kibana-with-security.html[Configuring Security in {kib}].
|
|
||||||
+
|
|
||||||
NOTE: This role should not be assigned to users as the granted permissions may
|
|
||||||
change between releases.
|
|
||||||
|
|
||||||
[[built-in-roles-kibana-user]] `kibana_user`::
|
|
||||||
Grants the minimum privileges required for any user of {kib}. This role grants
|
|
||||||
access to the {kib} indices and grants monitoring privileges for the cluster.
|
|
||||||
|
|
||||||
[[built-in-roles-logstash-admin]] `logstash_admin` ::
|
|
||||||
Grants access to the `.logstash*` indices for managing configurations.
|
|
||||||
|
|
||||||
[[built-in-roles-logstash-system]] `logstash_system` ::
|
|
||||||
Grants access necessary for the Logstash system user to send system-level data
|
|
||||||
(such as monitoring) to {es}. For more information, see
|
|
||||||
{logstash-ref}/ls-security.html[Configuring Security in Logstash].
|
|
||||||
+
|
|
||||||
NOTE: This role should not be assigned to users as the granted permissions may
|
|
||||||
change between releases.
|
|
||||||
+
|
|
||||||
NOTE: This role does not provide access to the logstash indices and is not
|
|
||||||
suitable for use within a Logstash pipeline.
|
|
||||||
|
|
||||||
[[built-in-roles-beats-system]] `beats_system` ::
|
|
||||||
Grants access necessary for the Beats system user to send system-level data
|
|
||||||
(such as monitoring) to {es}.
|
|
||||||
+
|
|
||||||
NOTE: This role should not be assigned to users as the granted permissions may
|
|
||||||
change between releases.
|
|
||||||
+
|
|
||||||
NOTE: This role does not provide access to the beats indices and is not
|
|
||||||
suitable for writing beats output to {es}.
|
|
||||||
|
|
||||||
[[built-in-roles-ml-admin]] `machine_learning_admin`::
|
|
||||||
Grants `manage_ml` cluster privileges and read access to the `.ml-*` indices.
|
|
||||||
|
|
||||||
[[built-in-roles-ml-user]] `machine_learning_user`::
|
|
||||||
Grants the minimum privileges required to view {xpackml} configuration,
|
|
||||||
status, and results. This role grants `monitor_ml` cluster privileges and
|
|
||||||
read access to the `.ml-notifications` and `.ml-anomalies*` indices,
|
|
||||||
which store {ml} results.
|
|
||||||
|
|
||||||
[[built-in-roles-monitoring-user]] `monitoring_user`::
|
|
||||||
Grants the minimum privileges required for any user of {monitoring} other than those
|
|
||||||
required to use {kib}. This role grants access to the monitoring indices and grants
|
|
||||||
privileges necessary for reading basic cluster information. Monitoring users should
|
|
||||||
also be assigned the `kibana_user` role.
|
|
||||||
|
|
||||||
[[built-in-roles-remote-monitoring-agent]] `remote_monitoring_agent`::
|
|
||||||
Grants the minimum privileges required for a remote monitoring agent to write data
|
|
||||||
into this cluster.
|
|
||||||
|
|
||||||
[[built-in-roles-reporting-user]] `reporting_user`::
|
|
||||||
Grants the specific privileges required for users of {reporting} other than those
|
|
||||||
required to use {kib}. This role grants access to the reporting indices. Reporting
|
|
||||||
users should also be assigned the `kibana_user` role and a role that grants them
|
|
||||||
access to the data that will be used to generate reports with.
|
|
||||||
|
|
||||||
[[built-in-roles-superuser]] `superuser`::
|
|
||||||
Grants full access to the cluster, including all indices and data. A user with
|
|
||||||
the `superuser` role can also manage users and roles and
|
|
||||||
<<run-as-privilege, impersonate>> any other user in the system. Due to the
|
|
||||||
permissive nature of this role, take extra care when assigning it to a user.
|
|
||||||
|
|
||||||
[[built-in-roles-transport-client]] `transport_client`::
|
|
||||||
Grants the privileges required to access the cluster through the Java Transport
|
|
||||||
Client. The Java Transport Client fetches information about the nodes in the
|
|
||||||
cluster using the _Node Liveness API_ and the _Cluster State API_ (when
|
|
||||||
sniffing is enabled). Assign your users this role if they use the
|
|
||||||
Transport Client.
|
|
||||||
+
|
|
||||||
NOTE: Using the Transport Client effectively means the users are granted access
|
|
||||||
to the cluster state. This means users can view the metadata over all indices,
|
|
||||||
index templates, mappings, node and basically everything about the cluster.
|
|
||||||
However, this role does not grant permission to view the data in all indices.
|
|
||||||
|
|
||||||
[[built-in-roles-watcher-admin]] `watcher_admin`::
|
|
||||||
+
|
|
||||||
Grants write access to the `.watches` index, read access to the watch history and
|
|
||||||
the triggered watches index and allows to execute all watcher actions.
|
|
||||||
|
|
||||||
[[built-in-roles-watcher-user]] `watcher_user`::
|
|
||||||
+
|
|
||||||
Grants read access to the `.watches` index, the get watch action and the watcher
|
|
||||||
stats.
|
|
||||||
|
|
||||||
|
|
||||||
[[defining-roles]]
|
|
||||||
=== Defining roles
|
|
||||||
|
|
||||||
A role is defined by the following JSON structure:
|
|
||||||
|
|
||||||
[source,js]
|
|
||||||
-----
|
|
||||||
{
|
|
||||||
"run_as": [ ... ], <1>
|
|
||||||
"cluster": [ ... ], <2>
|
|
||||||
"indices": [ ... ] <3>
|
|
||||||
}
|
|
||||||
-----
|
|
||||||
<1> A list of usernames the owners of this role can <<run-as-privilege, impersonate>>.
|
|
||||||
<2> A list of cluster privileges. These privileges define the
|
|
||||||
cluster level actions users with this role are able to execute. This field
|
|
||||||
is optional (missing `cluster` privileges effectively mean no cluster level
|
|
||||||
permissions).
|
|
||||||
<3> A list of indices permissions entries. This field is optional (missing `indices`
|
|
||||||
privileges effectively mean no index level permissions).
|
|
||||||
|
|
||||||
[[valid-role-name]]
|
|
||||||
NOTE: Role names must be at least 1 and no more than 1024 characters. They can
|
|
||||||
contain alphanumeric characters (`a-z`, `A-Z`, `0-9`), spaces,
|
|
||||||
punctuation, and printable symbols in the https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)[Basic Latin (ASCII) block].
|
|
||||||
Leading or trailing whitespace is not allowed.
|
|
||||||
|
|
||||||
The following describes the structure of an indices permissions entry:
|
|
||||||
|
|
||||||
[source,js]
|
|
||||||
-------
|
|
||||||
{
|
|
||||||
"names": [ ... ], <1>
|
|
||||||
"privileges": [ ... ], <2>
|
|
||||||
"field_security" : { ... }, <3>
|
|
||||||
"query": "..." <4>
|
|
||||||
}
|
|
||||||
-------
|
|
||||||
<1> A list of indices (or index name patterns) to which the permissions in this
|
|
||||||
entry apply.
|
|
||||||
<2> The index level privileges the owners of the role have on the associated
|
|
||||||
indices (those indices that are specified in the `name` field)
|
|
||||||
<3> Specification for document fields the owners of the role have read access to.
|
|
||||||
See <<field-and-document-access-control>> for details.
|
|
||||||
<4> A search query that defines the documents the owners of the role have read
|
|
||||||
access to. A document within the associated indices must match this query
|
|
||||||
in order for it to be accessible by the owners of the role.
|
|
||||||
|
|
||||||
[TIP]
|
|
||||||
==============================================================================
|
|
||||||
When specifying index names, you can use indices and aliases with their full
|
|
||||||
names or regular expressions that refer to multiple indices.
|
|
||||||
|
|
||||||
* Wildcard (default) - simple wildcard matching where `*` is a placeholder
|
|
||||||
for zero or more characters, `?` is a placeholder for a single character
|
|
||||||
and `\` may be used as an escape character.
|
|
||||||
|
|
||||||
* Regular Expressions - A more powerful syntax for matching more complex
|
|
||||||
patterns. This regular expression is based on Lucene's regexp automaton
|
|
||||||
syntax. To enable this syntax, it must be wrapped within a pair of
|
|
||||||
forward slashes (`/`). Any pattern starting with `/` and not ending with
|
|
||||||
`/` is considered to be malformed.
|
|
||||||
|
|
||||||
.Example Regular Expressions
|
|
||||||
[source,yaml]
|
|
||||||
------------------------------------------------------------------------------
|
|
||||||
"foo-bar": # match the literal `foo-bar`
|
|
||||||
"foo-*": # match anything beginning with "foo-"
|
|
||||||
"logstash-201?-*": # ? matches any one character
|
|
||||||
"/.*-201[0-9]-.*/": # use a regex to match anything containing 2010-2019
|
|
||||||
"/foo": # syntax error - missing final /
|
|
||||||
------------------------------------------------------------------------------
|
|
||||||
==============================================================================
|
|
||||||
|
|
||||||
The following snippet shows an example definition of a `clicks_admin` role:
|
|
||||||
|
|
||||||
[source,js]
|
|
||||||
-----------
|
|
||||||
{
|
|
||||||
"run_as": [ "clicks_watcher_1" ]
|
|
||||||
"cluster": [ "monitor" ],
|
|
||||||
"indices": [
|
|
||||||
{
|
|
||||||
"names": [ "events-*" ],
|
|
||||||
"privileges": [ "read" ],
|
|
||||||
"field_security" : {
|
|
||||||
"grant" : [ "category", "@timestamp", "message" ]
|
|
||||||
},
|
|
||||||
"query": "{\"match\": {\"category\": \"click\"}}"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
-----------
|
|
||||||
|
|
||||||
Based on the above definition, users owning the `clicks_admin` role can:
|
|
||||||
|
|
||||||
* Impersonate the `clicks_watcher_1` user and execute requests on its behalf.
|
|
||||||
* Monitor the {es} cluster
|
|
||||||
* Read data from all indices prefixed with `events-`
|
|
||||||
* Within these indices, only read the events of the `click` category
|
|
||||||
* Within these document, only read the `category`, `@timestamp` and `message`
|
|
||||||
fields.
|
|
||||||
|
|
||||||
TIP: For a complete list of available <<security-privileges, cluster and indices privileges>>
|
|
||||||
|
|
||||||
There are two available mechanisms to define roles: using the _Role Management APIs_
|
|
||||||
or in local files on the {es} nodes. {security} also supports implementing
|
|
||||||
custom roles providers. If you need to integrate with another system to retrieve
|
|
||||||
user roles, you can build a custom roles provider plugin. For more information,
|
|
||||||
see <<custom-roles-provider, Custom Roles Provider Extension>>.
|
|
||||||
|
|
||||||
[float]
|
|
||||||
[[roles-management-ui]]
|
|
||||||
=== Role management UI
|
|
||||||
|
|
||||||
{security} enables you to easily manage users and roles from within {kib}. To
|
|
||||||
manage roles, log in to {kib} and go to *Management / Elasticsearch / Roles*.
|
|
||||||
|
|
||||||
[float]
|
|
||||||
[[roles-management-api]]
|
|
||||||
=== Role management API
|
|
||||||
|
|
||||||
The _Role Management APIs_ enable you to add, update, remove and retrieve roles
|
|
||||||
dynamically. When you use the APIs to manage roles in the `native` realm, the
|
|
||||||
roles are stored in an internal {es} index. For more information and examples,
|
|
||||||
see {ref}/security-api-roles.html[Role Management APIs].
|
|
||||||
|
|
||||||
[float]
|
|
||||||
[[roles-management-file]]
|
|
||||||
=== File-based role management
|
|
||||||
|
|
||||||
Apart from the _Role Management APIs_, roles can also be defined in local
|
|
||||||
`roles.yml` file located in `CONFIG_DIR`. This is a YAML file where each
|
|
||||||
role definition is keyed by its name.
|
|
||||||
|
|
||||||
[IMPORTANT]
|
|
||||||
==============================
|
|
||||||
If the same role name is used in the `roles.yml` file and through the
|
|
||||||
_Role Management APIs_, the role found in the file will be used.
|
|
||||||
==============================
|
|
||||||
|
|
||||||
While the _Role Management APIs_ is the preferred mechanism to define roles,
|
|
||||||
using the `roles.yml` file becomes useful if you want to define fixed roles that
|
|
||||||
no one (beside an administrator having physical access to the {es} nodes)
|
|
||||||
would be able to change.
|
|
||||||
|
|
||||||
[IMPORTANT]
|
|
||||||
==============================
|
|
||||||
The `roles.yml` file is managed locally by the node and is not globally by the
|
|
||||||
cluster. This means that with a typical multi-node cluster, the exact same
|
|
||||||
changes need to be applied on each and every node in the cluster.
|
|
||||||
|
|
||||||
A safer approach would be to apply the change on one of the nodes and have the
|
|
||||||
`roles.yml` distributed/copied to all other nodes in the cluster (either
|
|
||||||
manually or using a configuration management system such as Puppet or Chef).
|
|
||||||
==============================
|
|
||||||
|
|
||||||
The following snippet shows an example of the `roles.yml` file configuration:
|
|
||||||
|
|
||||||
[source,yaml]
|
|
||||||
-----------------------------------
|
|
||||||
click_admins:
|
|
||||||
run_as: [ 'clicks_watcher_1' ]
|
|
||||||
cluster: [ 'monitor' ]
|
|
||||||
indices:
|
|
||||||
- names: [ 'events-*' ]
|
|
||||||
privileges: [ 'read' ]
|
|
||||||
field_security:
|
|
||||||
grant: ['category', '@timestamp', 'message' ]
|
|
||||||
query: '{"match": {"category": "click"}}'
|
|
||||||
-----------------------------------
|
|
||||||
|
|
||||||
{security} continuously monitors the `roles.yml` file and automatically picks
|
|
||||||
up and applies any changes to it.
|
|
||||||
|
|
||||||
include::alias-privileges.asciidoc[]
|
include::alias-privileges.asciidoc[]
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,10 +1,11 @@
|
||||||
|
[role="xpack"]
|
||||||
[[security-privileges]]
|
[[security-privileges]]
|
||||||
=== Security Privileges
|
=== Security privileges
|
||||||
|
|
||||||
This section lists the privileges that you can assign to a role.
|
This section lists the privileges that you can assign to a role.
|
||||||
|
|
||||||
[[privileges-list-cluster]]
|
[[privileges-list-cluster]]
|
||||||
==== Cluster Privileges
|
==== Cluster privileges
|
||||||
|
|
||||||
[horizontal]
|
[horizontal]
|
||||||
`all`::
|
`all`::
|
||||||
|
|
@ -66,7 +67,7 @@ All privileges necessary for a transport client to connect. Required by the rem
|
||||||
cluster to enable <<cross-cluster-configuring,Cross Cluster Search>>.
|
cluster to enable <<cross-cluster-configuring,Cross Cluster Search>>.
|
||||||
|
|
||||||
[[privileges-list-indices]]
|
[[privileges-list-indices]]
|
||||||
==== Indices Privileges
|
==== Indices privileges
|
||||||
|
|
||||||
[horizontal]
|
[horizontal]
|
||||||
`all`::
|
`all`::
|
||||||
|
|
@ -125,7 +126,7 @@ Privilege to create an index. A create index request may contain aliases to be
|
||||||
added to the index once created. In that case the request requires the `manage`
|
added to the index once created. In that case the request requires the `manage`
|
||||||
privilege as well, on both the index and the aliases names.
|
privilege as well, on both the index and the aliases names.
|
||||||
|
|
||||||
==== Run As Privilege
|
==== Run as privilege
|
||||||
|
|
||||||
The `run_as` permission enables an authenticated user to submit requests on
|
The `run_as` permission enables an authenticated user to submit requests on
|
||||||
behalf of another user. The value can be a user name or a comma-separated list
|
behalf of another user. The value can be a user name or a comma-separated list
|
||||||
|
|
@ -7,6 +7,4 @@
|
||||||
* {ref}/security-api.html[Security API]
|
* {ref}/security-api.html[Security API]
|
||||||
* {ref}/xpack-commands.html[Security Commands]
|
* {ref}/xpack-commands.html[Security Commands]
|
||||||
|
|
||||||
include::reference/privileges.asciidoc[]
|
|
||||||
|
|
||||||
include::reference/files.asciidoc[]
|
include::reference/files.asciidoc[]
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue