diff --git a/x-pack/docs/en/security/authorization/built-in-roles.asciidoc b/x-pack/docs/en/security/authorization/built-in-roles.asciidoc new file mode 100644 index 00000000000..f336393d81d --- /dev/null +++ b/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 +<>. 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 +<> 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. \ No newline at end of file diff --git a/x-pack/docs/en/security/authorization/managing-roles.asciidoc b/x-pack/docs/en/security/authorization/managing-roles.asciidoc new file mode 100644 index 00000000000..83edef1a67b --- /dev/null +++ b/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 <>. +<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 <> 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 <> + +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 <>. + +[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. diff --git a/x-pack/docs/en/security/authorization/overview.asciidoc b/x-pack/docs/en/security/authorization/overview.asciidoc index 9dc8185db4d..98a1ad8b786 100644 --- a/x-pack/docs/en/security/authorization/overview.asciidoc +++ b/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 -<>. 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 -<> 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 <>. -<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 <> 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 <> - -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 <>. - -[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[] diff --git a/x-pack/docs/en/security/reference/privileges.asciidoc b/x-pack/docs/en/security/authorization/privileges.asciidoc similarity index 97% rename from x-pack/docs/en/security/reference/privileges.asciidoc rename to x-pack/docs/en/security/authorization/privileges.asciidoc index b467b58283d..e5b22d3674a 100644 --- a/x-pack/docs/en/security/reference/privileges.asciidoc +++ b/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 <>. [[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 diff --git a/x-pack/docs/en/security/reference.asciidoc b/x-pack/docs/en/security/reference.asciidoc index 21138138cfb..9c65fd6479a 100644 --- a/x-pack/docs/en/security/reference.asciidoc +++ b/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[]