[DOCS] Reorganizes RBAC documentation

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

@@ -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.

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

@@ -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.

x-pack/docs/en/security/authorization/overview.asciidoc

@@ -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
 ways depending on the realms by which the users are authenticated.
 
-[[built-in-roles]]
-=== Built-in roles
+include::built-in-roles.asciidoc[]
 
-{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.
+include::managing-roles.asciidoc[]
 
-{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.
-
-
-[[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::privileges.asciidoc[]
 
 include::alias-privileges.asciidoc[]
 

x-pack/docs/en/security/reference/privileges.asciidoc → x-pack/docs/en/security/authorization/privileges.asciidoc

@@ -1,10 +1,11 @@
+[role="xpack"]
 [[security-privileges]]
-=== Security Privileges
+=== Security privileges
 
 This section lists the privileges that you can assign to a role.
 
 [[privileges-list-cluster]]
-==== Cluster Privileges
+==== Cluster privileges
 
 [horizontal]
 `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>>.
 
 [[privileges-list-indices]]
-==== Indices Privileges
+==== Indices privileges
 
 [horizontal]
 `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`
 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
 behalf of another user. The value can be a user name or a comma-separated list

x-pack/docs/en/security/reference.asciidoc

@@ -7,6 +7,4 @@
 * {ref}/security-api.html[Security API]
 * {ref}/xpack-commands.html[Security Commands]
 
-include::reference/privileges.asciidoc[]
-
 include::reference/files.asciidoc[]