Skip to content

Commit 445ce85

Browse files
lcawllcawl
committed
[DOCS] Reorganizes RBAC documentation
1 parent 3009376 commit 445ce85

File tree

5 files changed

+297
-293
lines changed

5 files changed

+297
-293
lines changed

‎x-pack/docs/en/security/authorization/built-in-roles.asciidoc‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
[role="xpack"]
2+
[[built-in-roles]]
3+
=== Built-in roles
4+
5+
{security} applies a default role to all users, including
6+
<<anonymous-access, anonymous users>>. The default role enables users to access
7+
the authenticate endpoint, change their own passwords, and get information about
8+
themselves.
9+
10+
{security} also provides a set of built-in roles you can explicitly assign
11+
to users. These roles have a fixed set of privileges and cannot be updated.
12+
13+
[[built-in-roles-ingest-user]] `ingest_admin` ::
14+
Grants access to manage *all* index templates and *all* ingest pipeline configurations.
15+
+
16+
NOTE: This role does *not* provide the ability to create indices; those privileges
17+
must be defined in a separate role.
18+
19+
[[built-in-roles-kibana-dashboard]] `kibana_dashboard_only_user` ::
20+
Grants access to the {kib} Dashboard and read-only permissions on the `.kibana`
21+
index. This role does not have access to editing tools in {kib}. For more
22+
information, see
23+
{kibana-ref}/xpack-dashboard-only-mode.html[{kib} Dashboard Only Mode].
24+
25+
[[built-in-roles-kibana-system]] `kibana_system` ::
26+
Grants access necessary for the {kib} system user to read from and write to the
27+
{kib} indices, manage index templates, and check the availability of the {es} cluster.
28+
This role grants read access to the `.monitoring-*` indices and read and write access
29+
to the `.reporting-*` indices. For more information, see
30+
{kibana-ref}/using-kibana-with-security.html[Configuring Security in {kib}].
31+
+
32+
NOTE: This role should not be assigned to users as the granted permissions may
33+
change between releases.
34+
35+
[[built-in-roles-kibana-user]] `kibana_user`::
36+
Grants the minimum privileges required for any user of {kib}. This role grants
37+
access to the {kib} indices and grants monitoring privileges for the cluster.
38+
39+
[[built-in-roles-logstash-admin]] `logstash_admin` ::
40+
Grants access to the `.logstash*` indices for managing configurations.
41+
42+
[[built-in-roles-logstash-system]] `logstash_system` ::
43+
Grants access necessary for the Logstash system user to send system-level data
44+
(such as monitoring) to {es}. For more information, see
45+
{logstash-ref}/ls-security.html[Configuring Security in Logstash].
46+
+
47+
NOTE: This role should not be assigned to users as the granted permissions may
48+
change between releases.
49+
+
50+
NOTE: This role does not provide access to the logstash indices and is not
51+
suitable for use within a Logstash pipeline.
52+
53+
[[built-in-roles-beats-system]] `beats_system` ::
54+
Grants access necessary for the Beats system user to send system-level data
55+
(such as monitoring) to {es}.
56+
+
57+
NOTE: This role should not be assigned to users as the granted permissions may
58+
change between releases.
59+
+
60+
NOTE: This role does not provide access to the beats indices and is not
61+
suitable for writing beats output to {es}.
62+
63+
[[built-in-roles-ml-admin]] `machine_learning_admin`::
64+
Grants `manage_ml` cluster privileges and read access to the `.ml-*` indices.
65+
66+
[[built-in-roles-ml-user]] `machine_learning_user`::
67+
Grants the minimum privileges required to view {xpackml} configuration,
68+
status, and results. This role grants `monitor_ml` cluster privileges and
69+
read access to the `.ml-notifications` and `.ml-anomalies*` indices,
70+
which store {ml} results.
71+
72+
[[built-in-roles-monitoring-user]] `monitoring_user`::
73+
Grants the minimum privileges required for any user of {monitoring} other than those
74+
required to use {kib}. This role grants access to the monitoring indices and grants
75+
privileges necessary for reading basic cluster information. Monitoring users should
76+
also be assigned the `kibana_user` role.
77+
78+
[[built-in-roles-remote-monitoring-agent]] `remote_monitoring_agent`::
79+
Grants the minimum privileges required for a remote monitoring agent to write data
80+
into this cluster.
81+
82+
[[built-in-roles-reporting-user]] `reporting_user`::
83+
Grants the specific privileges required for users of {reporting} other than those
84+
required to use {kib}. This role grants access to the reporting indices. Reporting
85+
users should also be assigned the `kibana_user` role and a role that grants them
86+
access to the data that will be used to generate reports with.
87+
88+
[[built-in-roles-superuser]] `superuser`::
89+
Grants full access to the cluster, including all indices and data. A user with
90+
the `superuser` role can also manage users and roles and
91+
<<run-as-privilege, impersonate>> any other user in the system. Due to the
92+
permissive nature of this role, take extra care when assigning it to a user.
93+
94+
[[built-in-roles-transport-client]] `transport_client`::
95+
Grants the privileges required to access the cluster through the Java Transport
96+
Client. The Java Transport Client fetches information about the nodes in the
97+
cluster using the _Node Liveness API_ and the _Cluster State API_ (when
98+
sniffing is enabled). Assign your users this role if they use the
99+
Transport Client.
100+
+
101+
NOTE: Using the Transport Client effectively means the users are granted access
102+
to the cluster state. This means users can view the metadata over all indices,
103+
index templates, mappings, node and basically everything about the cluster.
104+
However, this role does not grant permission to view the data in all indices.
105+
106+
[[built-in-roles-watcher-admin]] `watcher_admin`::
107+
+
108+
Grants write access to the `.watches` index, read access to the watch history and
109+
the triggered watches index and allows to execute all watcher actions.
110+
111+
[[built-in-roles-watcher-user]] `watcher_user`::
112+
+
113+
Grants read access to the `.watches` index, the get watch action and the watcher
114+
stats.

‎x-pack/docs/en/security/authorization/managing-roles.asciidoc‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
[role="xpack"]
2+
[[defining-roles]]
3+
=== Defining roles
4+
5+
A role is defined by the following JSON structure:
6+
7+
[source,js]
8+
-----
9+
{
10+
"run_as": [ ... ], <1>
11+
"cluster": [ ... ], <2>
12+
"indices": [ ... ] <3>
13+
}
14+
-----
15+
<1> A list of usernames the owners of this role can <<run-as-privilege, impersonate>>.
16+
<2> A list of cluster privileges. These privileges define the
17+
cluster level actions users with this role are able to execute. This field
18+
is optional (missing `cluster` privileges effectively mean no cluster level
19+
permissions).
20+
<3> A list of indices permissions entries. This field is optional (missing `indices`
21+
privileges effectively mean no index level permissions).
22+
23+
[[valid-role-name]]
24+
NOTE: Role names must be at least 1 and no more than 1024 characters. They can
25+
contain alphanumeric characters (`a-z`, `A-Z`, `0-9`), spaces,
26+
punctuation, and printable symbols in the https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)[Basic Latin (ASCII) block].
27+
Leading or trailing whitespace is not allowed.
28+
29+
The following describes the structure of an indices permissions entry:
30+
31+
[source,js]
32+
-------
33+
{
34+
"names": [ ... ], <1>
35+
"privileges": [ ... ], <2>
36+
"field_security" : { ... }, <3>
37+
"query": "..." <4>
38+
}
39+
-------
40+
<1> A list of indices (or index name patterns) to which the permissions in this
41+
entry apply.
42+
<2> The index level privileges the owners of the role have on the associated
43+
indices (those indices that are specified in the `name` field)
44+
<3> Specification for document fields the owners of the role have read access to.
45+
See <<field-and-document-access-control>> for details.
46+
<4> A search query that defines the documents the owners of the role have read
47+
access to. A document within the associated indices must match this query
48+
in order for it to be accessible by the owners of the role.
49+
50+
[TIP]
51+
==============================================================================
52+
When specifying index names, you can use indices and aliases with their full
53+
names or regular expressions that refer to multiple indices.
54+
55+
* Wildcard (default) - simple wildcard matching where `*` is a placeholder
56+
for zero or more characters, `?` is a placeholder for a single character
57+
and `\` may be used as an escape character.
58+
59+
* Regular Expressions - A more powerful syntax for matching more complex
60+
patterns. This regular expression is based on Lucene's regexp automaton
61+
syntax. To enable this syntax, it must be wrapped within a pair of
62+
forward slashes (`/`). Any pattern starting with `/` and not ending with
63+
`/` is considered to be malformed.
64+
65+
.Example Regular Expressions
66+
[source,yaml]
67+
------------------------------------------------------------------------------
68+
"foo-bar": # match the literal `foo-bar`
69+
"foo-*": # match anything beginning with "foo-"
70+
"logstash-201?-*": # ? matches any one character
71+
"/.*-201[0-9]-.*/": # use a regex to match anything containing 2010-2019
72+
"/foo": # syntax error - missing final /
73+
------------------------------------------------------------------------------
74+
==============================================================================
75+
76+
The following snippet shows an example definition of a `clicks_admin` role:
77+
78+
[source,js]
79+
-----------
80+
{
81+
"run_as": [ "clicks_watcher_1" ]
82+
"cluster": [ "monitor" ],
83+
"indices": [
84+
{
85+
"names": [ "events-*" ],
86+
"privileges": [ "read" ],
87+
"field_security" : {
88+
"grant" : [ "category", "@timestamp", "message" ]
89+
},
90+
"query": "{\"match\": {\"category\": \"click\"}}"
91+
}
92+
]
93+
}
94+
-----------
95+
96+
Based on the above definition, users owning the `clicks_admin` role can:
97+
98+
* Impersonate the `clicks_watcher_1` user and execute requests on its behalf.
99+
* Monitor the {es} cluster
100+
* Read data from all indices prefixed with `events-`
101+
* Within these indices, only read the events of the `click` category
102+
* Within these document, only read the `category`, `@timestamp` and `message`
103+
fields.
104+
105+
TIP: For a complete list of available <<security-privileges, cluster and indices privileges>>
106+
107+
There are two available mechanisms to define roles: using the _Role Management APIs_
108+
or in local files on the {es} nodes. {security} also supports implementing
109+
custom roles providers. If you need to integrate with another system to retrieve
110+
user roles, you can build a custom roles provider plugin. For more information,
111+
see <<custom-roles-provider, Custom Roles Provider Extension>>.
112+
113+
[float]
114+
[[roles-management-ui]]
115+
=== Role management UI
116+
117+
{security} enables you to easily manage users and roles from within {kib}. To
118+
manage roles, log in to {kib} and go to *Management / Elasticsearch / Roles*.
119+
120+
[float]
121+
[[roles-management-api]]
122+
=== Role management API
123+
124+
The _Role Management APIs_ enable you to add, update, remove and retrieve roles
125+
dynamically. When you use the APIs to manage roles in the `native` realm, the
126+
roles are stored in an internal {es} index. For more information and examples,
127+
see {ref}/security-api-roles.html[Role Management APIs].
128+
129+
[float]
130+
[[roles-management-file]]
131+
=== File-based role management
132+
133+
Apart from the _Role Management APIs_, roles can also be defined in local
134+
`roles.yml` file located in `CONFIG_DIR`. This is a YAML file where each
135+
role definition is keyed by its name.
136+
137+
[IMPORTANT]
138+
==============================
139+
If the same role name is used in the `roles.yml` file and through the
140+
_Role Management APIs_, the role found in the file will be used.
141+
==============================
142+
143+
While the _Role Management APIs_ is the preferred mechanism to define roles,
144+
using the `roles.yml` file becomes useful if you want to define fixed roles that
145+
no one (beside an administrator having physical access to the {es} nodes)
146+
would be able to change.
147+
148+
[IMPORTANT]
149+
==============================
150+
The `roles.yml` file is managed locally by the node and is not globally by the
151+
cluster. This means that with a typical multi-node cluster, the exact same
152+
changes need to be applied on each and every node in the cluster.
153+
154+
A safer approach would be to apply the change on one of the nodes and have the
155+
`roles.yml` distributed/copied to all other nodes in the cluster (either
156+
manually or using a configuration management system such as Puppet or Chef).
157+
==============================
158+
159+
The following snippet shows an example of the `roles.yml` file configuration:
160+
161+
[source,yaml]
162+
-----------------------------------
163+
click_admins:
164+
run_as: [ 'clicks_watcher_1' ]
165+
cluster: [ 'monitor' ]
166+
indices:
167+
- names: [ 'events-*' ]
168+
privileges: [ 'read' ]
169+
field_security:
170+
grant: ['category', '@timestamp', 'message' ]
171+
query: '{"match": {"category": "click"}}'
172+
-----------------------------------
173+
174+
{security} continuously monitors the `roles.yml` file and automatically picks
175+
up and applies any changes to it.

0 commit comments

Comments
 (0)