From 6a15dd2add23cb71e8254bfece34d6786d36e490 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Wed, 26 Feb 2025 00:44:53 -0500 Subject: [PATCH 01/19] halfway? --- .../api-keys/serverless-project-api-keys.md | 2 +- deploy-manage/security/secure-endpoints.md | 2 +- deploy-manage/toc.yml | 4 +- .../snapshot-and-restore/create-snapshots.md | 6 +- .../snapshot-and-restore/restore-snapshot.md | 4 +- .../snapshot-and-restore/self-managed.md | 4 +- .../built-in-roles.md | 163 +++++++- .../defining-roles.md | 365 ++++++++++++++++-- ...ing-privileges-for-data-streams-aliases.md | 10 +- .../kibana-privileges.md | 6 + .../kibana-role-management.md | 207 ++++++++++ .../role-restriction.md | 7 +- ...tting-requests-on-behalf-of-other-users.md | 2 +- .../user-authentication.md | 10 - .../cluster-or-deployment-auth/user-roles.md | 70 ++-- deploy-manage/users-roles/custom-roles.md | 4 +- .../cloud-on-k8s/k8s-users-and-roles.md | 51 --- .../elasticsearch-reference/built-in-roles.md | 147 ------- .../kibana/xpack-security-authorization.md | 6 - 19 files changed, 772 insertions(+), 298 deletions(-) create mode 100644 deploy-manage/users-roles/cluster-or-deployment-auth/kibana-role-management.md delete mode 100644 raw-migrated-files/cloud-on-k8s/cloud-on-k8s/k8s-users-and-roles.md delete mode 100644 raw-migrated-files/elasticsearch/elasticsearch-reference/built-in-roles.md delete mode 100644 raw-migrated-files/kibana/kibana/xpack-security-authorization.md diff --git a/deploy-manage/api-keys/serverless-project-api-keys.md b/deploy-manage/api-keys/serverless-project-api-keys.md index b88eed7e7d..4aa1b64d9e 100644 --- a/deploy-manage/api-keys/serverless-project-api-keys.md +++ b/deploy-manage/api-keys/serverless-project-api-keys.md @@ -70,7 +70,7 @@ For example, the following `role_descriptors` object defines a `books-read-only` } ``` -For the `role_descriptors` object schema, check out the [`/_security/api_key` endpoint](https://www.elastic.co/docs/api/doc/elasticsearch-serverless/operation/operation-security-create-api-key) docs. For supported privileges, check [Security privileges](../users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-indices). +For the `role_descriptors` object schema, check out the [`/_security/api_key` endpoint](https://www.elastic.co/docs/api/doc/elasticsearch-serverless/operation/operation-security-create-api-key) docs. For supported privileges, check [Security privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md#privileges-list-indices). ## Update an API key [api-keys-update-an-api-key] diff --git a/deploy-manage/security/secure-endpoints.md b/deploy-manage/security/secure-endpoints.md index 9db6054c0c..54e8ef20eb 100644 --- a/deploy-manage/security/secure-endpoints.md +++ b/deploy-manage/security/secure-endpoints.md @@ -27,5 +27,5 @@ While you absolutely shouldn’t expose {{es}} directly to the internet, you als ## Implement role based access control [security-create-appropriate-users] -[Define roles](../users-roles/cluster-or-deployment-auth/defining-roles.md) for your users and [assign appropriate privileges](../users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md) to ensure that users have access only to the resources that they need. This process determines whether the user behind an incoming request is allowed to run that request. +[Define roles](../users-roles/cluster-or-deployment-auth/defining-roles.md) for your users and [assign appropriate privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md) to ensure that users have access only to the resources that they need. This process determines whether the user behind an incoming request is allowed to run that request. diff --git a/deploy-manage/toc.yml b/deploy-manage/toc.yml index 3d70e5069a..066ee79120 100644 --- a/deploy-manage/toc.yml +++ b/deploy-manage/toc.yml @@ -646,12 +646,12 @@ toc: - file: users-roles/cluster-or-deployment-auth/manage-authentication-for-multiple-clusters.md - file: users-roles/cluster-or-deployment-auth/user-roles.md children: + - file: users-roles/cluster-or-deployment-auth/built-in-roles.md - file: users-roles/cluster-or-deployment-auth/defining-roles.md children: - file: users-roles/cluster-or-deployment-auth/granting-privileges-for-data-streams-aliases.md + - file: users-roles/cluster-or-deployment-auth/kibana-role-management.md - file: users-roles/cluster-or-deployment-auth/role-restriction.md - - file: users-roles/cluster-or-deployment-auth/built-in-roles.md - - file: users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md - file: users-roles/cluster-or-deployment-auth/kibana-privileges.md - file: users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md - file: users-roles/cluster-or-deployment-auth/authorization-delegation.md diff --git a/deploy-manage/tools/snapshot-and-restore/create-snapshots.md b/deploy-manage/tools/snapshot-and-restore/create-snapshots.md index 9696b86e67..1cffbf8034 100644 --- a/deploy-manage/tools/snapshot-and-restore/create-snapshots.md +++ b/deploy-manage/tools/snapshot-and-restore/create-snapshots.md @@ -26,8 +26,8 @@ The guide also provides tips for creating dedicated cluster state snapshots and * To use {{kib}}'s **Snapshot and Restore** feature, you must have the following permissions: - * [Cluster privileges](../../users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-cluster): `monitor`, `manage_slm`, `cluster:admin/snapshot`, and `cluster:admin/repository` - * [Index privilege](../../users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-indices): `all` on the `monitor` index + * [Cluster privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md#privileges-list-cluster): `monitor`, `manage_slm`, `cluster:admin/snapshot`, and `cluster:admin/repository` + * [Index privilege](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md#privileges-list-indices): `all` on the `monitor` index * You can only take a snapshot from a running cluster with an elected [master node](../../distributed-architecture/clusters-nodes-shards/node-roles.md#master-node-role). * A snapshot repository must be [registered](self-managed.md) and available to the cluster. @@ -59,7 +59,7 @@ Elastic Cloud Hosted deployments automatically include the `cloud-snapshot-polic ### {{slm-init}} security [slm-security] -The following [cluster privileges](../../users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-cluster) control access to the {{slm-init}} actions when {{es}} {{security-features}} are enabled: +The following [cluster privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md#privileges-list-cluster) control access to the {{slm-init}} actions when {{es}} {{security-features}} are enabled: `manage_slm` : Allows a user to perform all {{slm-init}} actions, including creating and updating policies and starting and stopping {{slm-init}}. diff --git a/deploy-manage/tools/snapshot-and-restore/restore-snapshot.md b/deploy-manage/tools/snapshot-and-restore/restore-snapshot.md index e306dcf705..7dbbf0c29d 100644 --- a/deploy-manage/tools/snapshot-and-restore/restore-snapshot.md +++ b/deploy-manage/tools/snapshot-and-restore/restore-snapshot.md @@ -24,8 +24,8 @@ This guide also provides tips for [restoring to another cluster](#restore-differ ## Prerequisites - To use Kibana’s Snapshot and Restore feature, you must have the following permissions: - - [Cluster privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-cluster): `monitor`, `manage_slm`, `cluster:admin/snapshot`, and `cluster:admin/repository` - - [Index privilege](/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-indices): `all` on the monitor index + - [Cluster privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md#privileges-list-cluster): `monitor`, `manage_slm`, `cluster:admin/snapshot`, and `cluster:admin/repository` + - [Index privilege](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md#privileges-list-indices): `all` on the monitor index - You can only restore a snapshot to a running cluster with an elected [master node](/deploy-manage/distributed-architecture/clusters-nodes-shards/node-roles.md#master-node-role). The snapshot’s repository must be registered and available to the cluster. - The snapshot and cluster versions must be compatible. See [Snapshot compatibility](/deploy-manage/tools/snapshot-and-restore.md#snapshot-compatibility). - To restore a snapshot, the cluster’s global metadata must be writable. Ensure there aren’t any cluster blocks that prevent writes. The restore operation ignores index blocks. diff --git a/deploy-manage/tools/snapshot-and-restore/self-managed.md b/deploy-manage/tools/snapshot-and-restore/self-managed.md index e2afe2f795..8fc06f7c7d 100644 --- a/deploy-manage/tools/snapshot-and-restore/self-managed.md +++ b/deploy-manage/tools/snapshot-and-restore/self-managed.md @@ -20,8 +20,8 @@ In this guide, you’ll learn how to: * To use {{kib}}'s **Snapshot and Restore** feature, you must have the following permissions: - * [Cluster privileges](../../users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-cluster): `monitor`, `manage_slm`, `cluster:admin/snapshot`, and `cluster:admin/repository` - * [Index privilege](../../users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-indices): `all` on the `monitor` index + * [Cluster privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md#privileges-list-cluster): `monitor`, `manage_slm`, `cluster:admin/snapshot`, and `cluster:admin/repository` + * [Index privilege](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md#privileges-list-indices): `all` on the `monitor` index * To register a snapshot repository, the cluster’s global metadata must be writeable. Ensure there aren’t any [cluster blocks](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/configuration-reference/miscellaneous-cluster-settings.md#cluster-read-only) that prevent write access. diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md b/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md index 5b34f970e3..a5766ec530 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md @@ -2,26 +2,165 @@ mapped_urls: - https://www.elastic.co/guide/en/elasticsearch/reference/current/built-in-roles.html - https://www.elastic.co/guide/en/kibana/current/xpack-security-authorization.html +applies_to: + deployment: + ece: + eck: + ess: + self: --- -# Built-in roles +# Built-in roles [built-in-roles] -% What needs to be done: Lift-and-shift +The {{stack-security-features}} apply a default role to all users, including [anonymous users](../../../deploy-manage/users-roles/cluster-or-deployment-auth/anonymous-access.md). The default role enables users to access the authenticate endpoint, change their own passwords, and get information about themselves. -% Use migrated content from existing pages that map to this page: +There is also a set of built-in roles you can explicitly assign to users. These roles have a fixed set of privileges and cannot be updated. -% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/built-in-roles.md -% - [ ] ./raw-migrated-files/kibana/kibana/xpack-security-authorization.md +When you assign a user multiple roles, the user receives a union of the roles’ privileges. -% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): +If the built-in roles do not address your use case, then you can create additional [custom roles](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md). -$$$built-in-roles$$$ +[Learn how to assign roles to users](/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles.md#assign-roles-to-users). -$$$built-in-roles-kibana-admin$$$ +## Roles -$$$built-in-roles-remote-monitoring-agent$$$ +$$$built-in-roles-apm-system$$$ `apm_system` +: Grants access necessary for the APM system user to send system-level data (such as monitoring) to {{es}}. -**This page is a work in progress.** The documentation team is working to combine content pulled from the following pages: +$$$built-in-roles-beats-admin$$$ `beats_admin` +: Grants access to the `.management-beats` index, which contains configuration information for the Beats. -* [/raw-migrated-files/elasticsearch/elasticsearch-reference/built-in-roles.md](/raw-migrated-files/elasticsearch/elasticsearch-reference/built-in-roles.md) -* [/raw-migrated-files/kibana/kibana/xpack-security-authorization.md](/raw-migrated-files/kibana/kibana/xpack-security-authorization.md) \ No newline at end of file +$$$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. + * This role does not provide access to the beats indices and is not suitable for writing beats output to {{es}}. + :::: + + +$$$built-in-roles-editor$$$ `editor` +: Grants full access to all features in {{kib}} (including Solutions) and read-only access to data indices. + + ::::{note} + * This role provides read access to any index that is not prefixed with a dot. + * This role automatically grants full access to new {{kib}} features as soon as they are released. + * Some {{kib}} features may also require creation or write access to data indices. {{ml-cap}} {{dfanalytics-jobs}} is an example. For such features those privileges must be defined in a separate role. + + :::: + + +$$$built-in-roles-enrich-user$$$ `enrich_user` +: Grants access to manage **all** enrich indices (`.enrich-*`) and **all** operations on ingest pipelines. + +$$$built-in-roles-inference-admin$$$ `inference_admin` +: Provides all of the privileges of the `inference_user` role and the full use of the Inference APIs. Grants the `manage_inference` cluster privilege. + +$$$built-in-roles-inference-user$$$ `inference_user` +: Provides the minimum privileges required to view Inference configurations and perform inference. Grants the `monintor_inference` cluster privilege. + +$$$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` +: (This role is deprecated, please use [{{kib}} feature privileges](../../../deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md#kibana-feature-privileges) instead). Grants read-only access to the {{kib}} Dashboard in every [space in {{kib}}](../../../deploy-manage/manage-spaces.md). This role does not have access to editing tools in {{kib}}. + +$$$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 tokens, and check the availability of the {{es}} cluster. It also permits activating, searching, and retrieving user profiles, as well as updating user profile data for the `kibana-*` namespace. This role grants read access to the `.monitoring-*` indices and read and write access to the `.reporting-*` indices. For more information, see [Configuring Security in {{kib}}](../../../deploy-manage/security.md). + + ::::{note} + This role should not be assigned to users as the granted permissions may change between releases. + :::: + + +$$$built-in-roles-kibana-admin$$$ `kibana_admin` +: Grants access to all {{kib}} features in all spaces. For more information on {{kib}} authorization, see [{{kib}} authorization](../../../deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md). + +$$$built-in-roles-kibana-user$$$ `kibana_user` +: This role is deprecated, please use the [`kibana_admin`](../../../deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md#built-in-roles-kibana-admin) role instead. Grants access to all features in {{kib}}.. + +$$$built-in-roles-logstash-admin$$$ `logstash_admin` +: Grants access to the `.logstash*` indices for managing configurations, and grants necessary access for logstash-specific APIs exposed by the logstash x-pack plugin. + +$$$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 [Configuring Security in Logstash](asciidocalypse://docs/logstash/docs/reference/secure-connection.md). + + ::::{note} + * This role should not be assigned to users as the granted permissions may change between releases. + * This role does not provide access to the logstash indices and is not suitable for use within a Logstash pipeline. + + :::: + + +$$$built-in-roles-ml-admin$$$ `machine_learning_admin` +: Provides all of the privileges of the `machine_learning_user` role plus the full use of the {{ml}} APIs. Grants `manage_ml` cluster privileges, read access to `.ml-anomalies*`, `.ml-notifications*`, `.ml-state*`, `.ml-meta*` indices and write access to `.ml-annotations*` indices. {{ml-cap}} administrators also need index privileges for source and destination indices and roles that grant access to {{kib}}. See [{{ml-cap}} security privileges](../../../explore-analyze/machine-learning/setting-up-machine-learning.md#setup-privileges). + +$$$built-in-roles-ml-user$$$ `machine_learning_user` +: Grants the minimum privileges required to view {{ml}} configuration, status, and work with results. This role grants `monitor_ml` cluster privileges, read access to the `.ml-notifications` and `.ml-anomalies*` indices (which store {{ml}} results), and write access to `.ml-annotations*` indices. {{ml-cap}} users also need index privileges for source and destination indices and roles that grant access to {{kib}}. See [{{ml-cap}} security privileges](../../../explore-analyze/machine-learning/setting-up-machine-learning.md#setup-privileges). + +$$$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. This role also includes all [Kibana privileges](../../../deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md) for the {{stack-monitor-features}}. Monitoring users should also be assigned the `kibana_admin` role, or another role with [access to the {{kib}} instance](../../../deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md). + +$$$built-in-roles-remote-monitoring-agent$$$ `remote_monitoring_agent` +: Grants the minimum privileges required to write data into the monitoring indices (`.monitoring-*`). This role also has the privileges necessary to create {{metricbeat}} indices (`metricbeat-*`) and write data into them. + +$$$built-in-roles-remote-monitoring-collector$$$ `remote_monitoring_collector` +: Grants the minimum privileges required to collect monitoring data for the {{stack}}. + +$$$built-in-roles-reporting-user$$$ `reporting_user` +: Grants the necessary privileges required to use {{reporting}} features in {{kib}}, including generating and downloading reports. This role implicitly grants access to all Kibana reporting features, with each user having access only to their own reports. Note that reporting users should also be assigned additional roles that grant read access to the [indices](../../../deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md#roles-indices-priv) that will be used to generate reports. + +$$$built-in-roles-rollup-admin$$$ `rollup_admin` +: Grants `manage_rollup` cluster privileges, which enable you to manage and execute all rollup actions. + +$$$built-in-roles-rollup-user$$$ `rollup_user` +: Grants `monitor_rollup` cluster privileges, which enable you to perform read-only operations related to rollups. + +$$$built-in-roles-snapshot-user$$$ `snapshot_user` +: Grants the necessary privileges to create snapshots of **all** the indices and to view their metadata. This role enables users to view the configuration of existing snapshot repositories and snapshot details. It does not grant authority to remove or add repositories or to restore snapshots. It also does not enable to change index settings or to read or update data stream or index data. + +$$$built-in-roles-superuser$$$ `superuser` +: Grants full access to cluster management and data indices. This role also grants direct read-only access to restricted indices like `.security`. A user with the `superuser` role can [impersonate](../../../deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md) any other user in the system. + + On {{ecloud}}, all standard users, including those with the `superuser` role are restricted from performing [operator-only](../../../deploy-manage/users-roles/cluster-or-deployment-auth/operator-only-functionality.md) actions. + + ::::{important} + This role can manage security and create roles with unlimited privileges. Take extra care when assigning it to a user. + :::: + + +$$$built-in-roles-transform-admin$$$ `transform_admin` +: Grants `manage_transform` cluster privileges, which enable you to manage {{transforms}}. This role also includes all [{{kib}} privileges](../../../deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md) for the {{ml-features}}. + +$$$built-in-roles-transform-user$$$ `transform_user` +: Grants `monitor_transform` cluster privileges, which enable you to perform read-only operations related to {{transforms}}. This role also includes all [{{kib}} privileges](../../../deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md) for the {{ml-features}}. + +$$$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-viewer$$$ `viewer` +: Grants read-only access to all features in {{kib}} (including Solutions) and to data indices. + + ::::{note} + * This role provides read access to any index that is not prefixed with a dot. + * This role automatically grants read-only access to new {{kib}} features as soon as they are available. + + :::: + + +$$$built-in-roles-watcher-admin$$$ `watcher_admin` +: Allows users to create and execute all {{watcher}} actions. Grants read access to the `.watches` index. Also grants read access to the watch history and the triggered watches index. + + +$$$built-in-roles-watcher-user$$$ `watcher_user` +: Grants read access to the `.watches` index, the get watch action and the watcher stats. diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md b/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md index 5974166390..249cdfddda 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md @@ -5,45 +5,360 @@ mapped_urls: - https://www.elastic.co/guide/en/elasticsearch/reference/current/defining-roles.html - https://www.elastic.co/guide/en/kibana/current/tutorial-secure-access-to-kibana.html - https://www.elastic.co/guide/en/kibana/current/kibana-role-management.html +applies_to: + deployment: + ece: + ess: + eck: + self: --- -# Defining roles +# Defining roles [defining-roles] -% What needs to be done: Refine +If [built-in roles](built-in-roles.md) do not address your use case, then you can create additional custom roles. -% GitHub issue: https://github.com/elastic/docs-projects/issues/347 +In this page, you'll learn about the [data structure of a role](#role-structure), and about the [methods for defining and managing custom roles](#managing-custom-roles). -% Use migrated content from existing pages that map to this page: +The data structure described in [Role structure](#role-structure) must be used when defining a role using the API or in a file. You can also define roles using the Role management UI, which does not require knowledge of a role's data structure. -% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/defining-roles.md -% Notes: custom roles -% - [ ] ./raw-migrated-files/cloud-on-k8s/cloud-on-k8s/k8s-users-and-roles.md -% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/defining-roles.md -% - [ ] ./raw-migrated-files/kibana/kibana/tutorial-secure-access-to-kibana.md -% - [ ] ./raw-migrated-files/kibana/kibana/kibana-role-management.md +You can also implement 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 [](/deploy-manage/users-roles/cluster-or-deployment-auth/authorization-plugins.md). -% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): +After you create your custom roles, you can [learn how to assign them to users](/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles.md#assign-roles-to-users). -$$$roles-remote-indices-priv$$$ +## Role structure -$$$roles-remote-cluster-priv$$$ +A role is defined by the following JSON structure: -$$$adding_kibana_privileges$$$ +```js +{ + "run_as": [ ... ], <1> + "cluster": [ ... ], <2> + "global": { ... }, <3> + "indices": [ ... ], <4> + "applications": [ ... ], <5> + "remote_indices": [ ... ], <6> + "remote_cluster": [ ... ], <7> + "metadata": { ... }, <8> + "description": "..." <9> +} +``` -$$$adding_index_privileges$$$ +1. A list of usernames the owners of this role can [impersonate](/deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md). +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. An object defining global privileges. A global privilege is a form of cluster privilege that is request sensitive. A standard cluster privilege makes authorization decisions based solely on the action being executed. A global privilege also considers the parameters included in the request. Support for global privileges is currently limited to the management of application privileges. This field is optional. +4. A list of indices permissions entries. + + This field is optional (missing `indices` privileges effectively mean no index level permissions). +5. A list of application privilege entries. This field is optional. +6. A list of indices permissions entries for [remote clusters configured with the API key based model](/deploy-manage/remote-clusters/remote-clusters-api-key.md). + + This field is optional (missing `remote_indices` privileges effectively mean no index level permissions for any API key based remote clusters). +7. A list of cluster permissions entries for [remote clusters configured with the API key based model](/deploy-manage/remote-clusters/remote-clusters-api-key.md). + + This field is optional (missing `remote_cluster` privileges effectively means no additional cluster permissions for any API key based remote clusters). +8. Metadata field associated with the role, such as `metadata.app_tag`. Metadata is internally indexed as a [flattened](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/mapping-reference/flattened.md) field type. This means that all sub-fields act like `keyword` fields when querying and sorting. Metadata values can be simple values, but also lists and maps. This field is optional. +9. A string value with the description text of the role. The maximum length of it is `1000` chars. The field is internally indexed as a [text](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/mapping-reference/text.md#text-field-type) field type (with default values for all parameters). This field is optional. -$$$roles-management-file$$$ -$$$roles-indices-priv$$$ +::::{note} +:name: valid-role-name -$$$roles-management-ui$$$ +Role names must be at least 1 and no more than 507 characters. They can contain alphanumeric characters (`a-z`, `A-Z`, `0-9`), spaces, punctuation, and printable symbols in the [Basic Latin (ASCII) block](https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)). Leading or trailing whitespace is not allowed. +:::: -$$$roles-management-api$$$ -**This page is a work in progress.** The documentation team is working to combine content pulled from the following pages: +### Indices privileges [roles-indices-priv] -* [/raw-migrated-files/elasticsearch/elasticsearch-reference/defining-roles.md](/raw-migrated-files/elasticsearch/elasticsearch-reference/defining-roles.md) -* [/raw-migrated-files/cloud-on-k8s/cloud-on-k8s/k8s-users-and-roles.md](/raw-migrated-files/cloud-on-k8s/cloud-on-k8s/k8s-users-and-roles.md) -* [/raw-migrated-files/elasticsearch/elasticsearch-reference/defining-roles.md](/raw-migrated-files/elasticsearch/elasticsearch-reference/defining-roles.md) -* [/raw-migrated-files/kibana/kibana/tutorial-secure-access-to-kibana.md](/raw-migrated-files/kibana/kibana/tutorial-secure-access-to-kibana.md) -* [/raw-migrated-files/kibana/kibana/kibana-role-management.md](/raw-migrated-files/kibana/kibana/kibana-role-management.md) \ No newline at end of file +The following describes the structure of an indices permissions entry: + +```js +{ + "names": [ ... ], <1> + "privileges": [ ... ], <2> + "field_security" : { ... }, <3> + "query": "...", <4> + "allow_restricted_indices": false <5> +} +``` + +1. A list of data streams, indices, and aliases to which the permissions in this entry apply. Supports wildcards (`*`). +2. The index level privileges the owners of the role have on the associated data streams and indices specified in the `names` argument. +3. Specification for document fields the owners of the role have read access to. See [Setting up field and document level security](/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md) for details. +4. A search query that defines the documents the owners of the role have read access to. A document within the associated data streams and indices must match this query in order for it to be accessible by the owners of the role. +5. Restricted indices are a special category of indices that are used internally to store configuration data and should not be directly accessed. Only internal system roles should normally grant privileges over the restricted indices. **Toggling this flag is very strongly discouraged because it could effectively grant unrestricted operations on critical data, making the entire system unstable or leaking sensitive information.** If however, for administrative purposes, you need to create a role with privileges covering restricted indices, you must set this field to `true` (default is `false`), and then the `names` field will cover the restricted indices as well. + + +::::{admonition} Using wildcards and regex +The `names` parameter accepts wildcard and regular expressions that may refer to multiple data streams, indices, and aliases. + +* 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. + +```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 / +``` + +:::: + + + +### Global privileges [roles-global-priv] + +The following describes the structure of the global privileges entry: + +```js +{ + "application": { + "manage": { <1> + "applications": [ ... ] <2> + } + }, + "profile": { + "write": { <3> + "applications": [ ... ] <4> + } + } +} +``` + +1. The privilege for the ability to manage application privileges +2. The list of application names that may be managed. This list supports wildcards (e.g. `"myapp-*"`) and regular expressions (e.g. `"/app[0-9]*/"`) +3. The privilege for the ability to write the `access` and `data` of any user profile +4. The list of names, wildcards and regular expressions to which the write privilege is restricted to + + + +### Application privileges [roles-application-priv] + +The following describes the structure of an application privileges entry: + +```js +{ + "application": "my_app", <1> + "privileges": [ ... ], <2> + "resources": [ ... ] <3> +} +``` + +1. The name of the application. +2. The list of the names of the application privileges to grant to this role. +3. The resources to which those privileges apply. These are handled in the same way as index name pattern in `indices` permissions. These resources do not have any special meaning to the {{es}} {{security-features}}. + + +For details about the validation rules for these fields, see the [add application privileges API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-put-privileges). + +A role may refer to application privileges that do not exist - that is, they have not yet been defined through the add application privileges API (or they were defined, but have since been deleted). In this case, the privilege has no effect, and will not grant any actions in the [has privileges API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-has-privileges). + + +### Remote indices privileges [roles-remote-indices-priv] + +For [remote clusters configured with the API key based model](/deploy-manage/remote-clusters/remote-clusters-api-key.md), remote indices privileges can be used to specify desired indices privileges for matching remote clusters. The final effective index privileges will be an intersection of the remote indices privileges and the [cross-cluster API key](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-cross-cluster-api-key)'s indices privileges. + +::::{note} +Remote indices are effective for remote clusters configured with the API key based model. They have no effect for remote clusters configured with the certificate based model. +:::: + + +The remote indices privileges entry has an extra mandatory `clusters` field compared to an [indices privileges entry](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md#roles-indices-priv). Otherwise the two have identical structure. The following describes the structure of a remote indices permissions entry: + +```js +{ + "clusters": [ ... ], <1> + "names": [ ... ], <2> + "privileges": [ ... ], <3> + "field_security" : { ... }, <4> + "query": "...", <5> + "allow_restricted_indices": false <6> +} +``` + +1. A list of remote cluster aliases. It supports literal strings as well as [wildcards](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/rest-apis/api-conventions.md#api-multi-index) and [regular expressions](asciidocalypse://docs/elasticsearch/docs/reference/query-languages/regexp-syntax.md). This field is required. +2. A list of data streams, indices, and aliases to which the permissions in this entry apply. Supports wildcards (`*`). +3. The index level privileges the owners of the role have on the associated data streams and indices specified in the `names` argument. +4. Specification for document fields the owners of the role have read access to. See [Setting up field and document level security](/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md) for details. +5. A search query that defines the documents the owners of the role have read access to. A document within the associated data streams and indices must match this query in order for it to be accessible by the owners of the role. +6. Restricted indices are a special category of indices that are used internally to store configuration data and should not be directly accessed. Only internal system roles should normally grant privileges over the restricted indices. **Toggling this flag is very strongly discouraged because it could effectively grant unrestricted operations on critical data, making the entire system unstable or leaking sensitive information.** If however, for administrative purposes, you need to create a role with privileges covering restricted indices, you must set this field to `true` (default is `false`), and then the `names` field will cover the restricted indices as well. + + + +### Remote cluster privileges [roles-remote-cluster-priv] + +For [remote clusters configured with the API key based model](/deploy-manage/remote-clusters/remote-clusters-api-key.md), remote cluster privileges can be used to specify additional cluster privileges for matching remote clusters. + +::::{note} +Remote cluster privileges are only effective for remote clusters configured with the API key based model. They have no effect on remote clusters configured with the certificate based model. +:::: + + +The following describes the structure of a remote cluster permissions entry: + +```js +{ + "clusters": [ ... ], <1> + "privileges": [ ... ] <2> +} +``` + +1. A list of remote cluster aliases. It supports literal strings as well as [wildcards](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/rest-apis/api-conventions.md#api-multi-index) and [regular expressions](asciidocalypse://docs/elasticsearch/docs/reference/query-languages/regexp-syntax.md). This field is required. +2. The cluster level privileges for the remote cluster. The allowed values here are a subset of the [cluster privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md#privileges-list-cluster). The [builtin privileges API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-get-builtin-privileges) can be used to determine which privileges are allowed here. This field is required. + + + +### Example [_example_9] + +The following snippet shows an example definition of a `clicks_admin` role: + +```console +POST /_security/role/clicks_admin +{ + "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} +View a complete list of available [cluster and indices privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md). +:::: + + +## Managing custom roles + +You can manage custom roles using the following methods: + +* Using the {{kib}} [role management UI](#roles-management-ui) +* Using [role management APIs](#roles-management-api) +* Using [local files](#roles-management-file). + +When you use the UI or APIs to manage roles, the roles are stored in an internal {{es}} index. When you use local files, the roles are only stored in those files. + +### Role management UI [roles-management-ui] + +You can manage users and roles easily in {{kib}}. + +To manage roles, log in to {{kib}} and go to **Management > Security > Roles**. + +[Learn more about using the role management UI]. + +### Role management API [roles-management-api] + +The Role Management APIs enable you to add, update, remove and retrieve roles dynamically. For more information and examples, see [Roles](https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-security). + + +### File-based role management [roles-management-file] + +```{applies_to} +deployment: + self: + eck: +``` + +Roles can also be defined in local `roles.yml` file. 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 role management APIs, the role found in the file will be used. + +:::: + + +While role management APIs and the role management UI are 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 access to the {{es}} nodes or Kubernetes cluster, would be able to change. However, the `roles.yml` file is provided as a minimal administrative function and is not intended to cover and be used to define roles for all use cases. + +::::{important} +You can't view, edit, or remove any roles that are defined in `roles.yml` by using the role management UI or the role management APIs. +:::: + +The following snippet shows an example of the `roles.yml` file configuration, specifying one role named `click_admins`: + +```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"}}' +``` + +To configure file-based role management: + +::::{tab-set} +:::{tab-item} Self hosted + +Place the `roles.yml` file in `ES_PATH_CONF`. {{es}} continuously monitors the `roles.yml` file and automatically picks up and applies any changes to it. + +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). +::: +:::{tab-item} ECK + +You can set up file-based role management in {{eck}} by referencing Kubernetes secrets containing the roles specification. + +```yaml +apiVersion: elasticsearch.k8s.elastic.co/v1 +kind: Elasticsearch +metadata: + name: elasticsearch-sample +spec: + version: 8.16.1 + auth: + roles: + - secretName: my-roles-secret-1 + - secretName: my-roles-secret-2 + nodeSets: + - name: default + count: 1 +``` + +Several secrets can be referenced in the {{es}} specification. ECK aggregates their content into a single secret, mounted in every {{es}} Pod. + +Each secret must have a `roles.yml` entry, containing the roles definition. + +If you specify multiple roles with the same name in more than one secret, the last one takes precedence. + +The following Secret applies the same `roles.yml` configuration, specifying one role named `click_admins`: + +```yaml +kind: Secret +apiVersion: v1 +metadata: + name: my-roles-secret +stringData: + roles.yml: |- + click_admins: + run_as: [ 'clicks_watcher_1' ] + cluster: [ 'monitor' ] + indices: + - names: [ 'events-*' ] + privileges: [ 'read' ] + field_security: + grant: ['category', '@timestamp', 'message' ] + query: '{"match": {"category": "click"}}' +``` +::: +:::: \ No newline at end of file diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/granting-privileges-for-data-streams-aliases.md b/deploy-manage/users-roles/cluster-or-deployment-auth/granting-privileges-for-data-streams-aliases.md index b070116187..3bdc5e8a4e 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/granting-privileges-for-data-streams-aliases.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/granting-privileges-for-data-streams-aliases.md @@ -1,6 +1,12 @@ --- mapped_pages: - https://www.elastic.co/guide/en/elasticsearch/reference/current/securing-aliases.html +navigation_title: "For data streams and aliases" +applies_to: + ece: + eck: + ess: + self: --- # Granting privileges for data streams and aliases [securing-aliases] @@ -9,7 +15,7 @@ mapped_pages: ## Data stream privileges [data-stream-privileges] -Use [index privileges](elasticsearch-privileges.md#privileges-list-indices) to control access to a data stream. Granting privileges on a data stream grants the same privileges on its backing indices. +Use [index privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md#privileges-list-indices) to control access to a data stream. Granting privileges on a data stream grants the same privileges on its backing indices. For example, `my-data-stream` consists of two backing indices: `.ds-my-data-stream-2099.03.07-000001` and `.ds-my-data-stream-2099.03.08-000002`. @@ -37,7 +43,7 @@ GET .ds-my-data-stream-2099.03.09-000003/_doc/2 ## Alias privileges [index-alias-privileges] -Use [index privileges](elasticsearch-privileges.md#privileges-list-indices) to control access to an [alias](../../../manage-data/data-store/aliases.md). Privileges on an index or data stream do not grant privileges on its aliases. For information about managing aliases, see [*Aliases*](../../../manage-data/data-store/aliases.md). +Use [index privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md#privileges-list-indices) to control access to an [alias](../../../manage-data/data-store/aliases.md). Privileges on an index or data stream do not grant privileges on its aliases. For information about managing aliases, see [*Aliases*](../../../manage-data/data-store/aliases.md). ::::{important} Don’t use [filtered aliases](../../../manage-data/data-store/aliases.md#filter-alias) in place of [document level security](controlling-access-at-document-field-level.md). {{es}} doesn’t always apply alias filters. diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md b/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md index bc27c1b1df..41842f504c 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md @@ -1,6 +1,12 @@ --- mapped_pages: - https://www.elastic.co/guide/en/kibana/current/kibana-privileges.html +applies_to: + deployment: + ece: + ess: + eck: + self: --- # Kibana privileges [kibana-privileges] diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-role-management.md b/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-role-management.md new file mode 100644 index 0000000000..b1454936dc --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-role-management.md @@ -0,0 +1,207 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/kibana/current/kibana-role-management.html +applies_to: + deployment: + ece: + ess: + eck: + self: +navigation_title: Using Kibana +--- + +# {{kib}} role management [kibana-role-management] + +Roles are a collection of privileges that allow you to perform actions in {{kib}} and {{es}}. Users are not directly granted privileges, but are instead assigned one or more roles that describe the desired level of access. When you assign a user multiple roles, the user receives a union of the roles’ privileges. This means that you cannot reduce the privileges of a user by assigning them an additional role. You must instead remove or edit one of their existing roles. + +To create a role, open the menu, then click **Stack Management > Roles** and click **Create role**. + +## Required permissions [_required_permissions_7] + +The `manage_security` [cluster privilege](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md#privileges-list-cluster) is required to access role management. + +## Cluster privileges [adding_cluster_privileges] + +Cluster privileges grant access to monitoring and management features in {{es}}. They also enable [Stack Management](/deploy-manage/index.md) capabilities in {{kib}}. + +Refer to [cluster privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md#privileges-list-cluster) for a complete description of available options. + + +## Index privileges [adding_index_privileges] + +Each role can grant access to multiple data indices, and each index can have a different set of privileges. We recommend granting the `read` and `view_index_metadata` privileges to each index that you expect your users to work with in {{kib}}. + +Refer to [index privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md#privileges-list-indices) for a complete description of available options. + +Document-level and field-level security affords you even more granularity when it comes to granting access to your data. With document-level security (DLS), you can write an {{es}} query to describe which documents this role grants access to. With field-level security (FLS), you can instruct {{es}} to grant or deny access to specific fields within each document. + +### Example: Grant access to indices that match the `filebeat-*` pattern [index_privilege_example_1] + +1. Go to **Stack Management > Roles**, and then click **Create role**. +2. In **Index privileges**, enter: + + 1. `filebeat-*` in the **Index** field. + 2. `read` and `view_index_metadata` in the **Privileges** field. + +
+:::{image} ../../../images/kibana-create-role-index-example.png +:alt: Create role with index privileges +:class: screenshot +::: + +### Example: Grant read access to specific documents in indices that match the `filebeat-*` pattern [index_privilege_dls_example] + +[Document-level security](/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md) is a [subscription feature](https://www.elastic.co/subscriptions). + +1. Go to **Stack Management > Roles**, and then click **Create role**. +2. In **Index privileges**, enter: + + 1. `filebeat-*` in the **Indices** field. + 2. `read` and `view_index_metadata` in the **Privileges** field. + +3. Select **Grant read privileges to specific documents**. +4. Enter an {{es}} query that matches the documents your users should access. This example writes a query that allows access to documents that have a `category` field equal to `click`: + + ```sh + { + "match": { + "category": "click" + } + } + ``` + + ::::{note} + {{kib}} automatically surrounds your DLS query with a `query` block, so you don’t have to provide your own. + :::: + +
+:::{image} ../../../images/kibana-create-role-dls-example.png +:alt: Create role with DLS index privileges +:class: screenshot +::: + + + +## Remote index privileges [adding_remote_index_privileges] + +If you have at least a platinum license, you can manage access to indices in remote clusters. + +You can assign the same privileges, document-level, and field-level as for [local index privileges](/deploy-manage/index.md#adding_index_privileges). + +### Example: Grant access to indices in remote clusters [remote_index_privilege_example_1] + +1. Go to **Stack Management > Roles**, and then click **Create role**. +2. In **Remote index privileges**, enter: + + 1. The name of your remote cluster in the **Remote clusters** field. + 2. The name of the index in your remote cluster in the **Remote indices** field. + 3. The allowed actions in the **Privileges** field. (e.g. `read` and `view_index_metadata`) + +
+:::{image} ../../../images/kibana-create-role-remote-index-example.png +:alt: Create role with remote index privileges +:class: screenshot +::: + +## {{kib}} privileges [adding_kibana_privileges] + +To assign {{kib}} privileges to the role, click **Add {{kib}} privilege** in the {{kib}} section. + +
+:::{image} ../../../images/kibana-spaces-roles.png +:alt: Add {{kib}} privileges +:class: screenshot +:width: 650px +::: + +Open the **Spaces** selection control to specify whether to grant the role access to all spaces **All Spaces** or one or more individual spaces. If you select **All Spaces**, you can’t select individual spaces until you clear your selection. + +Use the **Privilege** menu to grant access to features. The default is **Custom**, which you can use to grant access to individual features. Otherwise, you can grant read and write access to all current and future features by selecting **All**, or grant read access to all current and future features by selecting **Read**. + +When using the **Customize by feature** option, you can choose either **All**, **Read** or **None** for access to each feature. As new features are added to {{kib}}, roles that use the custom option do not automatically get access to the new features. You must manually update the roles. + +::::{note} +**{{stack-monitor-app}}** relies on built-in roles to grant access. When a user is assigned the appropriate roles, the **{{stack-monitor-app}}** application is available; otherwise, it is not visible. +:::: + + +To apply your changes, click **Add {{kib}} privilege**. The privilege shows up under the {{kib}} privileges section of the role. + +
+:::{image} ../../../images/kibana-create-space-privilege.png +:alt: Add {{kib}} privilege +:class: screenshot +::: + + +## Feature availability [_feature_availability] + +Features are available to users when their roles grant access to the features, **and** those features are visible in their current space. The following matrix explains when features are available to users when controlling access via [spaces](/deploy-manage/manage-spaces.md#spaces-managing) and role-based access control: + +| **Spaces config** | **Role config** | **Result** | +| --- | --- | --- | +| Feature hidden | Feature disabled | Feature not available | +| Feature hidden | Feature enabled | Feature not available | +| Feature visible | Feature disabled | Feature not available | +| Feature visible | Feature enabled | **Feature available** | + + +## Assigning different privileges to different spaces [_assigning_different_privileges_to_different_spaces] + +Using the same role, it’s possible to assign different privileges to different spaces. After you’ve added privileges, click **Add {{kib}} privilege**. If you’ve already added privileges for either **All Spaces** or an individual space, you will not be able to select these in the **Spaces** selection control. + +Additionally, if you’ve already assigned privileges at **All Spaces**, you are only able to assign additional privileges to individual spaces. Similar to the behavior of multiple roles granting the union of all privileges, {{kib}} privileges are also a union. If you’ve already granted the user the **All** privilege at **All Spaces**, you’re not able to restrict the role to only the **Read** privilege at an individual space. + + +## Privilege summary [_privilege_summary] + +To view a summary of the privileges granted, click **View privilege summary**. + +## Example 1: Grant all access to Dashboard at an individual space [_example_1_grant_all_access_to_dashboard_at_an_individual_space] + +1. Click **Add {{kib}} privilege**. +2. For **Spaces**, select an individual space. +3. For **Privilege**, leave the default selection of **Custom**. +4. For the Dashboard feature, select **All** +5. Click **Add {{kib}} privilege**. + +
+:::{image} ../../../images/kibana-privilege-example-1.png +:alt: Privilege example 1 +:class: screenshot +:width: 650px +::: + + +## Example 2: Grant all access to one space and read access to another [_example_2_grant_all_access_to_one_space_and_read_access_to_another] + +1. Click **Add {{kib}} privilege**. +2. For **Spaces**, select the first space. +3. For **Privilege**, select **All**. +4. Click **Add {{kib}} privilege**. +5. For **Spaces**, select the second space. +6. For **Privilege**, select **Read**. +7. Click **Add {{kib}} privilege**. + +
+:::{image} ../../../images/kibana-privilege-example-2.png +:alt: Privilege example 2 +:class: screenshot +::: + + +## Example 3: Grant read access to all spaces and write access to an individual space [_example_3_grant_read_access_to_all_spaces_and_write_access_to_an_individual_space] + +1. Click **Add {{kib}} privilege**. +2. For **Spaces**, select **All Spaces**. +3. For **Privilege**, select **Read**. +4. Click **Add {{kib}} privilege**. +5. For **Spaces**, select the individual space. +6. For **Privilege**, select **All**. +7. Click **Add {{kib}} privilege**. + +
+:::{image} ../../../images/kibana-privilege-example-3.png +:alt: Privilege example 3 +:class: screenshot +::: diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/role-restriction.md b/deploy-manage/users-roles/cluster-or-deployment-auth/role-restriction.md index 0afaed671a..c927415495 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/role-restriction.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/role-restriction.md @@ -1,15 +1,18 @@ --- mapped_pages: - https://www.elastic.co/guide/en/elasticsearch/reference/current/role-restriction.html +applies_to: + ece: + eck: + ess: + self: --- # Role restriction [role-restriction] Role restriction can be used to specify conditions under which a role should be effective. When conditions are not met, the role will be disabled, which will result in access being denied. Not specifying restriction means the role is not restricted and thus always effective. This is the default behaviour. -::::{note} Currently, the role restriction is only supported for [API keys](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-api-key), with limitation that the API key can only have a single role descriptor. -:::: ## Workflows [workflows-restriction] diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md b/deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md index 266582d35d..1a91d6925f 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md @@ -63,7 +63,7 @@ After a user successfully authenticates to {{es}}, an authorization process dete Consider an admin role and an analyst role. The admin role has higher privileges, but might also want to submit requests as another user to test and verify their permissions. -First, we’ll create an admin role named `my_admin_role`. This role has `manage` [privileges](elasticsearch-privileges.md) on the entire cluster, and on a subset of indices. This role also contains the `run_as` privilege, which enables any user with this role to submit requests on behalf of the specified `analyst_user`. +First, we’ll create an admin role named `my_admin_role`. This role has `manage` [privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md) on the entire cluster, and on a subset of indices. This role also contains the `run_as` privilege, which enables any user with this role to submit requests on behalf of the specified `analyst_user`. ```console POST /_security/role/my_admin_role?refresh=true diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/user-authentication.md b/deploy-manage/users-roles/cluster-or-deployment-auth/user-authentication.md index 8f70dd022b..0b52b8640f 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/user-authentication.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/user-authentication.md @@ -12,16 +12,6 @@ applies_to: # User authentication -% What needs to be done: Refine - -% GitHub issue: https://github.com/elastic/docs-projects/issues/347 - -% Scope notes: reference ECE SSO, cloud SSO - -% Use migrated content from existing pages that map to this page: - -% - [ ] ./raw-migrated-files/kibana/kibana/kibana-authentication.md - Authentication identifies an individual. To gain access to restricted resources, a user must prove their identity, using passwords, credentials, or some other means (typically referred to as authentication tokens). The {{stack}} authenticates users by identifying the users behind the requests that hit the cluster and verifying that they are who they claim to be. The authentication process is handled by one or more authentication services called [*realms*](/deploy-manage/users-roles/cluster-or-deployment-auth/authentication-realms.md). diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles.md b/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles.md index c598373417..4f0704a468 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles.md @@ -12,37 +12,20 @@ applies_to: # User roles [authorization] -After a user is authenticated, use role-based access control to determine whether the user behind an incoming request is allowed to execute the request. The primary method of authorization in a cluster is role-based access control (RBAC). Review the following topics to learn about authorization in your Elasticsearch cluster. +After a user is [authenticated](user-authentication.md), {{stack}} needs to determine whether the user behind an incoming request is allowed to execute the request. The primary method of authorization in a cluster is [role-based access control](#roles) (RBAC), although {{stack}} also supports [Attribute-based access control](#attributes) (ABAC). -### Set up user authorization +:::{tip} +If you use {{ece}} or {{ech}}, then you can also implement RBAC at the level of your [{{ece}} orchestrator](/deploy-manage/users-roles/cloud-enterprise-orchestrator.md) or [{{ecloud}} organization](/deploy-manage/users-roles/cloud-organization.md). -* [Define roles](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md) -* Learn about [built-in roles](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md) -* Learn about the [Elasticsearch](/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md) and [Kibana](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md) privileges you can assign to roles -* Creating [mappings of users and groups to roles](/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md) for external authentication providers -* Learn how to [control access at the document and field level](/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md) - -### Advanced topics - -* Learn how to [delegate authorization to another realm](/deploy-manage/users-roles/cluster-or-deployment-auth/authorization-delegation.md) -* Learn how to [build a custom authorization plugin](/deploy-manage/users-roles/cluster-or-deployment-auth/authorization-plugins.md) for unsupported systems or advanced applications -* Learn how to [submit requests on behalf of other users](/deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md) -* Learn about [attribute-based access control](/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles.md#attributes) - -::::{tip} -User roles are also used to control access to [{{kib}} spaces](/deploy-manage/manage-spaces.md). -:::: - - - -The {{stack-security-features}} add *authorization*, which is the process of determining whether the user behind an incoming request is allowed to execute the request. - -This process takes place after the user is successfully identified and [authenticated](user-authentication.md). +If you use {{serverless-full}}, then you can only manage RBAC at the [{{ecloud}} organization level](/deploy-manage/users-roles/cloud-organization.md). +You must authenticate users at the same level where you implement RBAC. For example, if you want to use organization-level roles, than you must authenticate your users at the organization level. +::: -## Role-based access control [roles] +## How role-based access control works [roles] -The {{security-features}} provide a role-based access control (RBAC) mechanism, which enables you to authorize users by assigning privileges to roles and assigning roles to users or groups. +Role-based access control (RBAC) enables you to authorize users by assigning privileges to roles and assigning roles to users or groups. This is the primary way of controlling access to resources in {{stack}}. +
:::{image} ../../../images/elasticsearch-reference-authorization.png :alt: This image illustrates role-based access control @@ -54,7 +37,7 @@ The authorization process revolves around the following constructs: : A resource to which access is restricted. Indices, aliases, documents, fields, users, and the {{es}} cluster itself are all examples of secured objects. *Privilege* -: A named group of one or more actions that a user may execute against a secured resource. Each secured resource has its own sets of available privileges. For example, `read` is an index privilege that represents all actions that enable reading the indexed/stored data. For a complete list of available privileges see [Security privileges](elasticsearch-privileges.md). +: A named group of one or more actions that a user may execute against a secured resource. Each secured resource has its own sets of available privileges. For example, `read` is an index privilege that represents all actions that enable reading the indexed/stored data. For a complete list of available privileges, see [Elasticsearch privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md). *Permissions* : A set of one or more privileges against a secured resource. Permissions can easily be described in words, here are few examples: @@ -77,12 +60,41 @@ The authorization process revolves around the following constructs: A role has a unique name and identifies a set of permissions that translate to privileges on resources. You can associate a user or group with an arbitrary number of roles. When you map roles to groups, the roles of a user in that group are the combination of the roles assigned to that group and the roles assigned to that user. Likewise, the total set of permissions that a user has is defined by the union of the permissions in all its roles. -The method for assigning roles to users varies depending on which realms you use to authenticate users. For more information, see [Mapping users and groups to roles](mapping-users-groups-to-roles.md). +## Set up user authorization using RBAC +Review these topics to learn how to configure RBAC in your cluster or deployment: + +* Learn about [built-in roles](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md) +* [Define your own roles](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md) +* Learn about the [Elasticsearch](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md) and [Kibana](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md) privileges you can assign to roles +* Learn how to [control access at the document and field level](/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md) + +### Assign roles to users + +The way that you assign roles to users depends on your authentication realm: + +* [Native realm](/deploy-manage/users-roles/cluster-or-deployment-auth/native.md): + * Using {{es}} API [`_security` endpoints](https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-security) + * [In {{kib}}](/deploy-manage/users-roles/cluster-or-deployment-auth/native#managing-native-users), using the **Stack Management > Security > Users** page +* [File realm](/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md): + * Using a [`user_roles` file](/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md#k8s-basic) + * In ECK: As part of a [basic authentication secret](/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md#k8s-basic) +* [External realms](/deploy-manage/users-roles/cluster-or-deployment-auth/external-authentication): By [mapping users and groups to roles](/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md) + +### Advanced topics + +* Learn how to [delegate authorization to another realm](/deploy-manage/users-roles/cluster-or-deployment-auth/authorization-delegation.md) +* Learn how to [build a custom authorization plugin](/deploy-manage/users-roles/cluster-or-deployment-auth/authorization-plugins.md) for unsupported systems or advanced applications +* Learn how to [submit requests on behalf of other users](/deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md) +* Learn about [attribute-based access control](/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles.md#attributes) + +::::{tip} +User roles are also used to control access to [{{kib}} spaces](/deploy-manage/manage-spaces.md). +:::: ## Attribute-based access control [attributes] -The {{security-features}} also provide an attribute-based access control (ABAC) mechanism, which enables you to use attributes to restrict access to documents in search queries and aggregations. For example, you can assign attributes to users and documents, then implement an access policy in a role definition. Users with that role can read a specific document only if they have all the required attributes. +Attribute-based access control (ABAC) enables you to use attributes to restrict access to documents in search queries and aggregations. For example, you can assign attributes to users and documents, then implement an access policy in a role definition. Users with that role can read a specific document only if they have all the required attributes. For more information, see [Document-level attribute-based access control with {{es}}](https://www.elastic.co/blog/attribute-based-access-control-elasticsearch). diff --git a/deploy-manage/users-roles/custom-roles.md b/deploy-manage/users-roles/custom-roles.md index 8aec4afc63..1f8218fa6f 100644 --- a/deploy-manage/users-roles/custom-roles.md +++ b/deploy-manage/users-roles/custom-roles.md @@ -20,7 +20,7 @@ Roles are a collection of privileges that enable users to access project feature On this page, you'll learn about how to [manage custom roles in your project](#manage-custom-roles), the types of privileges you can assign, and how to [assign the roles](#assign-custom-roles) that you create. ::::{note} -You cannot assign [run as privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#_run_as_privilege) in {{serverless-full}} custom roles. +You cannot assign [run as privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md#_run_as_privilege) in {{serverless-full}} custom roles. :::: @@ -37,7 +37,7 @@ Cluster privileges grant access to monitoring and management features in {{es}}. :class: screenshot ::: -Refer to [cluster privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-cluster) for a complete description of available options. +Refer to [cluster privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md#privileges-list-cluster) for a complete description of available options. ## {{es}} index privileges [custom-roles-es-index-privileges] diff --git a/raw-migrated-files/cloud-on-k8s/cloud-on-k8s/k8s-users-and-roles.md b/raw-migrated-files/cloud-on-k8s/cloud-on-k8s/k8s-users-and-roles.md deleted file mode 100644 index b0e98338c5..0000000000 --- a/raw-migrated-files/cloud-on-k8s/cloud-on-k8s/k8s-users-and-roles.md +++ /dev/null @@ -1,51 +0,0 @@ -# Users and roles [k8s-users-and-roles] - -## Creating custom roles [k8s_creating_custom_roles] - -[Roles](https://www.elastic.co/guide/en/elasticsearch/reference/current/defining-roles.html) can be specified using the [Role management API](https://www.elastic.co/guide/en/elasticsearch/reference/current/defining-roles.html#roles-management-api), or the [Role management UI in Kibana](https://www.elastic.co/guide/en/elasticsearch/reference/current/defining-roles.html#roles-management-ui). - -Additionally, [file-based role management](https://www.elastic.co/guide/en/elasticsearch/reference/current/defining-roles.html#roles-management-file) can be achieved by referencing Kubernetes secrets containing the roles specification. - -```yaml -apiVersion: elasticsearch.k8s.elastic.co/v1 -kind: Elasticsearch -metadata: - name: elasticsearch-sample -spec: - version: 8.16.1 - auth: - roles: - - secretName: my-roles-secret-1 - - secretName: my-roles-secret-2 - nodeSets: - - name: default - count: 1 -``` - -Several secrets can be referenced in the Elasticsearch specification. ECK aggregates their content into a single secret, mounted in every Elasticsearch Pod. - -Each secret must have a `roles.yml` entry, containing the [roles definition](https://www.elastic.co/guide/en/elasticsearch/reference/current/defining-roles.html#roles-management-file). - -If you specify multiple roles with the same name in more than one secret, the last one takes precedence. - -The following Secret specifies one role named `click_admins`: - -```yaml -kind: Secret -apiVersion: v1 -metadata: - name: my-roles-secret -stringData: - roles.yml: |- - click_admins: - run_as: [ 'clicks_watcher_1' ] - cluster: [ 'monitor' ] - indices: - - names: [ 'events-*' ] - privileges: [ 'read' ] - field_security: - grant: ['category', '@timestamp', 'message' ] - query: '{"match": {"category": "click"}}' -``` - - diff --git a/raw-migrated-files/elasticsearch/elasticsearch-reference/built-in-roles.md b/raw-migrated-files/elasticsearch/elasticsearch-reference/built-in-roles.md deleted file mode 100644 index 45314d59c9..0000000000 --- a/raw-migrated-files/elasticsearch/elasticsearch-reference/built-in-roles.md +++ /dev/null @@ -1,147 +0,0 @@ -# Built-in roles [built-in-roles] - -The {{stack-security-features}} apply a default role to all users, including [anonymous users](../../../deploy-manage/users-roles/cluster-or-deployment-auth/anonymous-access.md). The default role enables users to access the authenticate endpoint, change their own passwords, and get information about themselves. - -There is also 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-apm-system$$$ `apm_system` -: Grants access necessary for the APM system user to send system-level data (such as monitoring) to {{es}}. - -$$$built-in-roles-beats-admin$$$ `beats_admin` -: Grants access to the `.management-beats` index, which contains configuration information for the Beats. - -$$$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. - * This role does not provide access to the beats indices and is not suitable for writing beats output to {{es}}. - - :::: - - -$$$built-in-roles-editor$$$ `editor` -: Grants full access to all features in {{kib}} (including Solutions) and read-only access to data indices. - - ::::{note} - * This role provides read access to any index that is not prefixed with a dot. - * This role automatically grants full access to new {{kib}} features as soon as they are released. - * Some {{kib}} features may also require creation or write access to data indices. {{ml-cap}} {{dfanalytics-jobs}} is an example. For such features those privileges must be defined in a separate role. - - :::: - - -$$$built-in-roles-enrich-user$$$ `enrich_user` -: Grants access to manage **all** enrich indices (`.enrich-*`) and **all** operations on ingest pipelines. - -$$$built-in-roles-inference-admin$$$ `inference_admin` -: Provides all of the privileges of the `inference_user` role and the full use of the Inference APIs. Grants the `manage_inference` cluster privilege. - -$$$built-in-roles-inference-user$$$ `inference_user` -: Provides the minimum privileges required to view Inference configurations and perform inference. Grants the `monintor_inference` cluster privilege. - -$$$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` -: (This role is deprecated, please use [{{kib}} feature privileges](../../../deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md#kibana-feature-privileges) instead). Grants read-only access to the {{kib}} Dashboard in every [space in {{kib}}](../../../deploy-manage/manage-spaces.md). This role does not have access to editing tools in {{kib}}. - -$$$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 tokens, and check the availability of the {{es}} cluster. It also permits activating, searching, and retrieving user profiles, as well as updating user profile data for the `kibana-*` namespace. This role grants read access to the `.monitoring-*` indices and read and write access to the `.reporting-*` indices. For more information, see [Configuring Security in {{kib}}](../../../deploy-manage/security.md). - - ::::{note} - This role should not be assigned to users as the granted permissions may change between releases. - :::: - - -$$$built-in-roles-kibana-admin$$$ `kibana_admin` -: Grants access to all features in {{kib}}. For more information on {{kib}} authorization, see [Kibana authorization](../../../deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md). - -$$$built-in-roles-kibana-user$$$ `kibana_user` -: (This role is deprecated, please use the [`kibana_admin`](../../../deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md#built-in-roles-kibana-admin) role instead.) Grants access to all features in {{kib}}. For more information on {{kib}} authorization, see [Kibana authorization](../../../deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md). - -$$$built-in-roles-logstash-admin$$$ `logstash_admin` -: Grants access to the `.logstash*` indices for managing configurations, and grants necessary access for logstash-specific APIs exposed by the logstash x-pack plugin. - -$$$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 [Configuring Security in Logstash](asciidocalypse://docs/logstash/docs/reference/secure-connection.md). - - ::::{note} - * This role should not be assigned to users as the granted permissions may change between releases. - * This role does not provide access to the logstash indices and is not suitable for use within a Logstash pipeline. - - :::: - - -$$$built-in-roles-ml-admin$$$ `machine_learning_admin` -: Provides all of the privileges of the `machine_learning_user` role plus the full use of the {{ml}} APIs. Grants `manage_ml` cluster privileges, read access to `.ml-anomalies*`, `.ml-notifications*`, `.ml-state*`, `.ml-meta*` indices and write access to `.ml-annotations*` indices. {{ml-cap}} administrators also need index privileges for source and destination indices and roles that grant access to {{kib}}. See [{{ml-cap}} security privileges](../../../explore-analyze/machine-learning/setting-up-machine-learning.md#setup-privileges). - -$$$built-in-roles-ml-user$$$ `machine_learning_user` -: Grants the minimum privileges required to view {{ml}} configuration, status, and work with results. This role grants `monitor_ml` cluster privileges, read access to the `.ml-notifications` and `.ml-anomalies*` indices (which store {{ml}} results), and write access to `.ml-annotations*` indices. {{ml-cap}} users also need index privileges for source and destination indices and roles that grant access to {{kib}}. See [{{ml-cap}} security privileges](../../../explore-analyze/machine-learning/setting-up-machine-learning.md#setup-privileges). - -$$$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. This role also includes all [Kibana privileges](../../../deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md) for the {{stack-monitor-features}}. Monitoring users should also be assigned the `kibana_admin` role, or another role with [access to the {{kib}} instance](../../../deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md). - -$$$built-in-roles-remote-monitoring-agent$$$ `remote_monitoring_agent` -: Grants the minimum privileges required to write data into the monitoring indices (`.monitoring-*`). This role also has the privileges necessary to create {{metricbeat}} indices (`metricbeat-*`) and write data into them. - -$$$built-in-roles-remote-monitoring-collector$$$ `remote_monitoring_collector` -: Grants the minimum privileges required to collect monitoring data for the {{stack}}. - -$$$built-in-roles-reporting-user$$$ `reporting_user` -: Grants the necessary privileges required to use {{reporting}} features in {{kib}}, including generating and downloading reports. This role implicitly grants access to all Kibana reporting features, with each user having access only to their own reports. Note that reporting users should also be assigned additional roles that grant read access to the [indices](../../../deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md#roles-indices-priv) that will be used to generate reports. - -$$$built-in-roles-rollup-admin$$$ `rollup_admin` -: Grants `manage_rollup` cluster privileges, which enable you to manage and execute all rollup actions. - -$$$built-in-roles-rollup-user$$$ `rollup_user` -: Grants `monitor_rollup` cluster privileges, which enable you to perform read-only operations related to rollups. - -$$$built-in-roles-snapshot-user$$$ `snapshot_user` -: Grants the necessary privileges to create snapshots of **all** the indices and to view their metadata. This role enables users to view the configuration of existing snapshot repositories and snapshot details. It does not grant authority to remove or add repositories or to restore snapshots. It also does not enable to change index settings or to read or update data stream or index data. - -$$$built-in-roles-superuser$$$ `superuser` -: Grants full access to cluster management and data indices. This role also grants direct read-only access to restricted indices like `.security`. A user with the `superuser` role can [impersonate](../../../deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md) any other user in the system. - - On {{ecloud}}, all standard users, including those with the `superuser` role are restricted from performing [operator-only](../../../deploy-manage/users-roles/cluster-or-deployment-auth/operator-only-functionality.md) actions. - - ::::{important} - This role can manage security and create roles with unlimited privileges. Take extra care when assigning it to a user. - :::: - - -$$$built-in-roles-transform-admin$$$ `transform_admin` -: Grants `manage_transform` cluster privileges, which enable you to manage {{transforms}}. This role also includes all [Kibana privileges](../../../deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md) for the {{ml-features}}. - -$$$built-in-roles-transform-user$$$ `transform_user` -: Grants `monitor_transform` cluster privileges, which enable you to perform read-only operations related to {{transforms}}. This role also includes all [Kibana privileges](../../../deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md) for the {{ml-features}}. - -$$$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-viewer$$$ `viewer` -: Grants read-only access to all features in {{kib}} (including Solutions) and to data indices. - - ::::{note} - * This role provides read access to any index that is not prefixed with a dot. - * This role automatically grants read-only access to new {{kib}} features as soon as they are available. - - :::: - - -$$$built-in-roles-watcher-admin$$$ `watcher_admin` -: Allows users to create and execute all {{watcher}} actions. Grants read access to the `.watches` index. Also grants read access to the watch history and the triggered watches index. - - -$$$built-in-roles-watcher-user$$$ `watcher_user` -: Grants read access to the `.watches` index, the get watch action and the watcher stats. diff --git a/raw-migrated-files/kibana/kibana/xpack-security-authorization.md b/raw-migrated-files/kibana/kibana/xpack-security-authorization.md deleted file mode 100644 index e2003b638f..0000000000 --- a/raw-migrated-files/kibana/kibana/xpack-security-authorization.md +++ /dev/null @@ -1,6 +0,0 @@ -# Granting access to {{kib}} [xpack-security-authorization] - -The Elastic Stack comes with the `kibana_admin` [built-in role](../../../deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md), which you can use to grant access to all {{kib}} features in all spaces. To grant users access to a subset of spaces or features, you can create a custom role that grants the desired {{kib}} privileges. - -When you assign a user multiple roles, the user receives a union of the roles’ privileges. Therefore, assigning the `kibana_admin` role in addition to a custom role that grants {{kib}} privileges is ineffective because `kibana_admin` has access to all the features in all spaces. - From 92134cce3a8d8e100aa9cbaa2a7fea72a0a3f17a Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Wed, 26 Feb 2025 00:49:45 -0500 Subject: [PATCH 02/19] cleanup --- .../defining-roles.md | 21 ++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md b/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md index 249cdfddda..08952748ce 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md @@ -96,18 +96,25 @@ The `names` parameter accepts wildcard and regular expressions that may refer to * 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. -```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 / +```js +"foo-bar": <1> +"foo-*": <2> +"logstash-201?-*": <3> +"/.*-201[0-9]-.*/": <4> +"/foo": <5> ``` - +1. Match the literal `foo-bar` +2. Match anything beginning with "foo-" +3. `?` matches any one character +4. Use a regex to match anything containing 2010-2019 +5. syntax error - missing final `/` :::: + + + ### Global privileges [roles-global-priv] The following describes the structure of the global privileges entry: From 5565be77b2aa632d7c097d553c24d12b3d1a4a08 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Wed, 26 Feb 2025 13:10:17 -0500 Subject: [PATCH 03/19] mapping topic!! --- .../defining-roles.md | 2 +- .../cluster-or-deployment-auth/file-based.md | 2 +- .../kibana-role-management.md | 3 +- .../mapping-users-groups-to-roles.md | 207 ++++++++++++++++-- .../elasticsearch-reference/mapping-roles.md | 142 ------------ .../role-mapping-resources.md | 2 +- .../kibana/kibana/role-mappings.md | 47 ---- 7 files changed, 195 insertions(+), 210 deletions(-) delete mode 100644 raw-migrated-files/elasticsearch/elasticsearch-reference/mapping-roles.md delete mode 100644 raw-migrated-files/kibana/kibana/role-mappings.md diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md b/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md index 08952748ce..34bf7ded1e 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md @@ -268,7 +268,7 @@ You can manage users and roles easily in {{kib}}. To manage roles, log in to {{kib}} and go to **Management > Security > Roles**. -[Learn more about using the role management UI]. +[Learn more about using the role management UI](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-role-management.md). ### Role management API [roles-management-api] diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md b/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md index 63b7a747ba..036fe8046c 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md @@ -42,7 +42,7 @@ You don’t need to explicitly configure a `file` realm. The `file` and `native` 2. If you're using a self-managed {{es}} cluster, optionally change how often the `users` and `users_roles` files are checked. - By default, {{es}} checks these files for changes every 5 seconds. You can change this default behavior by changing the `resource.reload.interval.high` setting in the `elasticsearch.yml` file + By default, {{es}} checks these files for changes every 5 seconds. You can change this default behavior by changing the `resource.reload.interval.high` setting in the `elasticsearch.yml` file. :::{{warning}} Because `resource.reload.interval.high` is a common setting in {{es}}, changing its value may effect other schedules in the system. diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-role-management.md b/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-role-management.md index b1454936dc..794cd4875c 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-role-management.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-role-management.md @@ -10,7 +10,7 @@ applies_to: navigation_title: Using Kibana --- -# {{kib}} role management [kibana-role-management] +# Role management using {{kib}} [kibana-role-management] Roles are a collection of privileges that allow you to perform actions in {{kib}} and {{es}}. Users are not directly granted privileges, but are instead assigned one or more roles that describe the desired level of access. When you assign a user multiple roles, the user receives a union of the roles’ privileges. This means that you cannot reduce the privileges of a user by assigning them an additional role. You must instead remove or edit one of their existing roles. @@ -26,7 +26,6 @@ Cluster privileges grant access to monitoring and management features in {{es}}. Refer to [cluster privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md#privileges-list-cluster) for a complete description of available options. - ## Index privileges [adding_index_privileges] Each role can grant access to multiple data indices, and each index can have a different set of privileges. We recommend granting the `read` and `view_index_metadata` privileges to each index that you expect your users to work with in {{kib}}. diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md b/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md index ca07abc28f..4f7d2a7f10 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md @@ -5,30 +5,205 @@ mapped_urls: - https://www.elastic.co/guide/en/elasticsearch/reference/current/role-mapping-resources.html --- -# Map external users and groups to roles +# Map external users and groups to roles [mapping-roles] -% What needs to be done: Refine +Role mapping is the process of applying roles to users based on their attributes or context. It is supported by all [external realms](/deploy-manage/users-roles/cluster-or-deployment-auth/external-authentication.md) (realms other than `native` and `file`). -% GitHub issue: https://github.com/elastic/docs-projects/issues/347 +To use role mapping, you create roles and role mapping rules. Role mapping rules can be based on realm name, realm type, username, groups, other user metadata, or combinations of those values. -% Use migrated content from existing pages that map to this page: +Users with no roles assigned will be unauthorized for any action. In other words, they may be able to authenticate, but they will have no roles. No roles means no privileges, and no privileges means no authorizations to make requests. -% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/mapping-roles.md -% - [ ] ./raw-migrated-files/kibana/kibana/role-mappings.md -% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/role-mapping-resources.md +You can map external users and groups to roles in the following ways: -% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): +* Using the [{{kib}} Role mapping UI](#role-mapping-ui), which leverages the Role mapping API +* Using the [Role mapping API](#mapping-roles-api) +* Using [role mapping files](#mapping-roles-file) (PKI, LDAP, AD realms only) -$$$mapping-roles-file$$$ +::::{note} +When [anonymous access](/deploy-manage/users-roles/cluster-or-deployment-auth/anonymous-access.md) is enabled, the roles of the anonymous user are assigned to all the other users as well. +:::: -$$$ldap-role-mapping$$$ +All external realms also support [delegated authorization](/deploy-manage/users-roles/cluster-or-deployment-auth/realm-chains.md#authorization_realms). You can either map roles for a realm or use delegated authorization; you cannot use both simultaneously. -$$$mapping-roles-api$$$ +:::{{tip}} +The native and file realms assign roles directly to users. Native realms use [user management APIs](/deploy-manage/users-roles/cluster-or-deployment-auth/native.md#managing-native-users). File realms use [File-based role management](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md#roles-management-file). +::: -$$$mapping-roles-rule-field$$$ +## Role sources -**This page is a work in progress.** The documentation team is working to combine content pulled from the following pages: +Before you use role mappings to assign roles to users, the roles must exist. You can assign [built-in roles](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md), or [custom roles](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md) defined through [the UI](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-role-management.md), [the API](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md#roles-management-api), or [a roles file](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md#roles-management-file). + +Any role mapping method can use any role management method. For example, when you use the role mapping API, you are able to map users to both API-managed roles (added using the UI or directly using the API) and file-managed roles. The same applies to file-based role-mappings. -* [/raw-migrated-files/elasticsearch/elasticsearch-reference/mapping-roles.md](/raw-migrated-files/elasticsearch/elasticsearch-reference/mapping-roles.md) -* [/raw-migrated-files/kibana/kibana/role-mappings.md](/raw-migrated-files/kibana/kibana/role-mappings.md) -* [/raw-migrated-files/elasticsearch/elasticsearch-reference/role-mapping-resources.md](/raw-migrated-files/elasticsearch/elasticsearch-reference/role-mapping-resources.md) \ No newline at end of file +## Using multiple role mapping methods + +You can use a combination of methods to map roles to users. If you create role mapping rules created through the API (and related UI), and create additional rules using a role mapping file, the rules are combined. + +It’s possible for a single user to have some roles that were mapped through the UI or API, and others assigned based on the role mapping file. + +## Using the role mapping API [mapping-roles-api] + +You can define and manage role mappings through the [add role mapping API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-put-role-mapping). + + +## The role mapping UI [role-mapping-ui] + +You can find the **Role mappings** management page using the navigation menu or the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md). + +With **Role mappings**, you can: + +* View your configured role mappings +* Create, edit, or delete role mappings + +![Role mappings](../../../images/kibana-role-mappings-grid.png "") + +### Required permissions [_required_permissions_8] + +The `manage_security` cluster privilege is required to manage role mappings. + +### Create a role mapping [_create_a_role_mapping] + +1. Go to the **Role mappings** management page using the navigation menu or the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md). +2. Click **Create role mapping**. +3. Give your role mapping a unique name, and choose which roles you want to assign to your users. + + If you need more flexibility, you can use [role templates](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-put-role-mapping) instead. + +4. Define the rules describing which users should receive the roles you defined. Rules can optionally grouped and nested, allowing for sophisticated logic to suite complex requirements. +5. View the [role mapping resources for an overview of the allowed rule types](/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md). + +### Example [_example_2] + +Let’s create a `sales-users` role mapping, which assigns a `sales` role to users whose username starts with `sls_`, **or** belongs to the `executive` group. + +1. Give the role mapping a name, and assign the `sales` role: + + ![Create role mapping, step 1](../../../images/kibana-role-mappings-create-step-1.png "") + +2. Define the two rules, making sure to set the group to **Any are true**: + + ![Create role mapping, step 2](../../../images/kibana-role-mappings-create-step-2.gif "") + +1. When you're finished defining rules, click **Save role mapping**. + +## Using role mapping files [mapping-roles-file] + +While the role mapping API and UI are the preferred way to manage role mappings, using the `role_mapping.yml` file is useful in a few specific cases: + +1. If you want to define fixed role mappings that no one (besides an administrator with access to the {{es}} nodes or {{eck}} cluster) would be able to change. +2. If cluster administration depends on users from external realms, and these users need to have their roles mapped to them even when the cluster is RED. For instance, in the case of an administrator that authenticates using LDAP or PKI and gets assigned an administrator role so that they can perform corrective actions. + +However, the `role_mapping.yml` file is provided as a minimal administrative function and is not intended to cover and be used to define roles for all use cases. + +::::{important} +You can't view, edit, or remove any roles that are defined in the role mapping files by using role mapping APIs or the role mapping UI. +:::: + +### Add a role mapping file + +To use file based role mappings, you must configure the mappings in a YAML file. + +:::{tip} +If you're using {{ece}} or {{ech}}, then you must [upload this file as a custom bundle](/deploy-manage/deploy/elastic-cloud/upload-custom-plugins-bundles.md) before it can be referenced. + +If you're using {{eck}}, then install the file as a [custom configuration file](/deploy-manage/deploy/cloud-on-k8s/custom-configuration-files-plugins.md#use-a-volume-and-volume-mount-together-with-a-configmap-or-secret). + +If you're using a self-managed cluster, then the file must be present on each node. Tools like Puppet or Chef can help with this. +::: + +By default, role mappings are stored in `ES_PATH_CONF/role_mapping.yml`. In self-managed clusters, `ES_PATH_CONF` is `ES_HOME/config` (zip/tar installations) or `/etc/elasticsearch` (package installations). + +To specify a different location, you configure the `files.role_mapping` setting in the [Active Directory](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/configuration-reference/security-settings.md#ref-ad-settings), [LDAP](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/configuration-reference/security-settings.md#ref-ldap-settings), and [PKI](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/configuration-reference/security-settings.md#ref-pki-settings) realm settings in `elasticsearch.yml`. + +Within the role mapping file, the security roles are keys and groups and users are values. The mappings can have a many-to-many relationship. When you map roles to groups, the roles of a user in that group are the combination of the roles assigned to that group and the roles assigned to that user. + +By default, {{es}} checks role mapping files for changes every 5 seconds. If you're using a self-managed {{es}} cluster, you can change this default behavior by changing the `resource.reload.interval.high` setting in the `elasticsearch.yml` file. Because this is a common setting in {{es}}, changing its value might effect other schedules in the system. + +## Realm specific details [_realm_specific_details] + +Review the following examples to learn how to set up role mapping using the API and using role mapping files for a few common external realms. + +### Active Directory and LDAP realms [ldap-role-mapping] + +To specify users and groups in the role mappings, you use their *Distinguished Names* (DNs). A DN is a string that uniquely identifies the user or group, for example `"cn=John Doe,cn=contractors,dc=example,dc=com"`. + +For example, the following examples map the `admins` group to the `monitoring` role and map the `John Doe` user, the `users` group, and the `admins` group to the `user` role. + +::::{note} +The {{es}} {{security-features}} support only Active Directory security groups. You can't map distribution groups to roles. +:::: + +::::{{tab-set}} +:::{{tab-item}} API +```console +PUT /_security/role_mapping/admins +{ + "roles" : [ "monitoring", "user" ], + "rules" : { "field" : { "groups" : "cn=admins,dc=example,dc=com" } }, + "enabled": true +} +``` + +```console +PUT /_security/role_mapping/basic_users +{ + "roles" : [ "user" ], + "rules" : { "any" : [ + { "field" : { "dn" : "cn=John Doe,cn=contractors,dc=example,dc=com" } }, + { "field" : { "groups" : "cn=users,dc=example,dc=com" } } + ] }, + "enabled": true +} +``` +::: +:::{{tab-item}} Role mapping file +```yaml +monitoring: <1> + - "cn=admins,dc=example,dc=com" <2> +user: + - "cn=John Doe,cn=contractors,dc=example,dc=com" <3> + - "cn=users,dc=example,dc=com" + - "cn=admins,dc=example,dc=com" +``` + +1. The name of a role. +2. The distinguished name of an LDAP group or an Active Directory security group. +3. The distinguished name of an LDAP or Active Directory user. +::: +:::: + +### PKI realms [pki-role-mapping] + +PKI realms support mapping users to roles, but you can't map groups as the PKI realm has no concept of a group. + +For example, the following examples map the `Admin` user to the `monitoring` role and map the `John Doe` user to the `user` role. + +::::{{tab-set}} +:::{{tab-item}} API +```console +PUT /_security/role_mapping/admin_user +{ + "roles" : [ "monitoring" ], + "rules" : { "field" : { "dn" : "cn=Admin,ou=example,o=com" } }, + "enabled": true +} +``` + +```console +PUT /_security/role_mapping/basic_user +{ + "roles" : [ "user" ], + "rules" : { "field" : { "dn" : "cn=John Doe,ou=example,o=com" } }, + "enabled": true +} +``` +::: +:::{{tab-item}} Role mapping file +```yaml +monitoring: + - "cn=Admin,ou=example,o=com" +user: + - "cn=John Doe,ou=example,o=com" +``` +::: +:::: \ No newline at end of file diff --git a/raw-migrated-files/elasticsearch/elasticsearch-reference/mapping-roles.md b/raw-migrated-files/elasticsearch/elasticsearch-reference/mapping-roles.md deleted file mode 100644 index 51ea20963b..0000000000 --- a/raw-migrated-files/elasticsearch/elasticsearch-reference/mapping-roles.md +++ /dev/null @@ -1,142 +0,0 @@ -# Mapping users and groups to roles [mapping-roles] - -Role mapping is supported by all realms except `native` and `file`. - -The native and file realms assign roles directly to users. Native realms use [user management APIs](../../../deploy-manage/users-roles/cluster-or-deployment-auth/native.md#managing-native-users). File realms use [File-based role management](../../../deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md#roles-management-file). - -You can map roles through the [Role mapping API](../../../deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md#mapping-roles-api) (recommended) or a [Role mapping file](../../../deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md#mapping-roles-file). - -The PKI, LDAP, AD, Kerberos, OpenID Connect, JWT, and SAML realms support the [Role mapping API](../../../deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md#mapping-roles-api). Only PKI, LDAP, and AD realms support [Role mapping files](../../../deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md#mapping-roles-file). - -The PKI, LDAP, AD, Kerberos, OpenID Connect, JWT, and SAML realms also support [delegated authorization](../../../deploy-manage/users-roles/cluster-or-deployment-auth/realm-chains.md#authorization_realms). You can either map roles for a realm or use delegated authorization; you cannot use both simultaneously. - -To use role mapping, you create roles and role mapping rules. Role mapping rules can be based on realm name, realm type, username, groups, other user metadata, or combinations of those values. - -::::{note} -When [anonymous access](../../../deploy-manage/users-roles/cluster-or-deployment-auth/anonymous-access.md) is enabled, the roles of the anonymous user are assigned to all the other users as well. -:::: - - -If there are role-mapping rules created through the API as well as a role mapping file, the rules are combined. It’s possible for a single user to have some roles that were mapped through the API, and others assigned based on the role mapping file. You can define role-mappings via an [API](../../../deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md#mapping-roles-api) or manage them through [files](../../../deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md#mapping-roles-file). These two sources of role-mapping are combined inside of the {{es}} {{security-features}}, so it is possible for a single user to have some roles that have been mapped through the API, and other roles that are mapped through files. - -::::{note} -Users with no roles assigned will be unauthorized for any action. In other words, they may be able to authenticate, but they will have no roles. No roles means no privileges, and no privileges means no authorizations to make requests. -:::: - - -When you use role mappings to assign roles to users, the roles must exist. There are two sources of roles. The available roles should either be added using the [role management APIs](https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-security) or defined in the [roles file](../../../deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md#roles-management-file). Either role-mapping method can use either role management method. For example, when you use the role mapping API, you are able to map users to both API-managed roles and file-managed roles (and likewise for file-based role-mappings). - -## Using the role mapping API [mapping-roles-api] - -You can define role-mappings through the [add role mapping API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-put-role-mapping). - - -## Using role mapping files [mapping-roles-file] - -To use file based role-mappings, you must configure the mappings in a YAML file and copy it to each node in the cluster. Tools like Puppet or Chef can help with this. - -By default, role mappings are stored in `ES_PATH_CONF/role_mapping.yml`, where `ES_PATH_CONF` is `ES_HOME/config` (zip/tar installations) or `/etc/elasticsearch` (package installations). To specify a different location, you configure the `files.role_mapping` setting in the [Active Directory](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/configuration-reference/security-settings.md#ref-ad-settings), [LDAP](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/configuration-reference/security-settings.md#ref-ldap-settings), and [PKI](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/configuration-reference/security-settings.md#ref-pki-settings) realm settings in `elasticsearch.yml`. - -Within the role mapping file, the security roles are keys and groups and users are values. The mappings can have a many-to-many relationship. When you map roles to groups, the roles of a user in that group are the combination of the roles assigned to that group and the roles assigned to that user. - -By default, {{es}} checks role mapping files for changes every 5 seconds. You can change this default behavior by changing the `resource.reload.interval.high` setting in the `elasticsearch.yml` file. Since this is a common setting in Elasticsearch, changing its value might effect other schedules in the system. - -While the *role mapping APIs* is the preferred way to manage role mappings, using the `role_mapping.yml` file becomes useful in a couple of use cases: - -1. If you want to define fixed role mappings that no one (besides an administrator with physical access to the {{es}} nodes) would be able to change. -2. If cluster administration depends on users from external realms and these users need to have their roles mapped to them even when the cluster is RED. For instance an administrator that authenticates via LDAP or PKI and gets assigned an administrator role so that they can perform corrective actions. - -Please note however, that the `role_mapping.yml` file is provided as a minimal administrative function and is not intended to cover and be used to define roles for all use cases. - -::::{important} -You cannot view, edit, or remove any roles that are defined in the role mapping files by using the role mapping APIs. -:::: - - - -## Realm specific details [_realm_specific_details] - - -#### Active Directory and LDAP realms [ldap-role-mapping] - -To specify users and groups in the role mappings, you use their *Distinguished Names* (DNs). A DN is a string that uniquely identifies the user or group, for example `"cn=John Doe,cn=contractors,dc=example,dc=com"`. - -::::{note} -The {{es}} {{security-features}} support only Active Directory security groups. You cannot map distribution groups to roles. -:::: - - -For example, the following snippet uses the file-based method to map the `admins` group to the `monitoring` role and map the `John Doe` user, the `users` group, and the `admins` group to the `user` role. - -```yaml -monitoring: <1> - - "cn=admins,dc=example,dc=com" <2> -user: - - "cn=John Doe,cn=contractors,dc=example,dc=com" <3> - - "cn=users,dc=example,dc=com" - - "cn=admins,dc=example,dc=com" -``` - -1. The name of a role. -2. The distinguished name of an LDAP group or an Active Directory security group. -3. The distinguished name of an LDAP or Active Directory user. - - -You can use the role-mapping API to define equivalent mappings as follows: - -```console -PUT /_security/role_mapping/admins -{ - "roles" : [ "monitoring", "user" ], - "rules" : { "field" : { "groups" : "cn=admins,dc=example,dc=com" } }, - "enabled": true -} -``` - -```console -PUT /_security/role_mapping/basic_users -{ - "roles" : [ "user" ], - "rules" : { "any" : [ - { "field" : { "dn" : "cn=John Doe,cn=contractors,dc=example,dc=com" } }, - { "field" : { "groups" : "cn=users,dc=example,dc=com" } } - ] }, - "enabled": true -} -``` - - -#### PKI realms [pki-role-mapping] - -PKI realms support mapping users to roles, but you cannot map groups as the PKI realm has no notion of a group. - -This is an example using a file-based mapping: - -```yaml -monitoring: - - "cn=Admin,ou=example,o=com" -user: - - "cn=John Doe,ou=example,o=com" -``` - -The following example creates equivalent mappings using the API: - -```console -PUT /_security/role_mapping/admin_user -{ - "roles" : [ "monitoring" ], - "rules" : { "field" : { "dn" : "cn=Admin,ou=example,o=com" } }, - "enabled": true -} -``` - -```console -PUT /_security/role_mapping/basic_user -{ - "roles" : [ "user" ], - "rules" : { "field" : { "dn" : "cn=John Doe,ou=example,o=com" } }, - "enabled": true -} -``` - - diff --git a/raw-migrated-files/elasticsearch/elasticsearch-reference/role-mapping-resources.md b/raw-migrated-files/elasticsearch/elasticsearch-reference/role-mapping-resources.md index d5c13e1d66..2bcd736911 100644 --- a/raw-migrated-files/elasticsearch/elasticsearch-reference/role-mapping-resources.md +++ b/raw-migrated-files/elasticsearch/elasticsearch-reference/role-mapping-resources.md @@ -21,7 +21,7 @@ A role mapping resource has the following properties: : (array of rules) If **all** of its children are true, it evaluates to `true`. `field` - : (object) See [Field rules](../../../deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md#mapping-roles-rule-field). + : (object) See [Field rules](#mapping-roles-rule-field). `except` : (object) A single rule as an object. Only valid as a child of an `all` rule. If its child is `false`, the `except` is `true`. diff --git a/raw-migrated-files/kibana/kibana/role-mappings.md b/raw-migrated-files/kibana/kibana/role-mappings.md deleted file mode 100644 index 90f1cb502a..0000000000 --- a/raw-migrated-files/kibana/kibana/role-mappings.md +++ /dev/null @@ -1,47 +0,0 @@ -# Role mappings [role-mappings] - -Role mappings are part of single sign-on (SSO), a [subscription feature](https://www.elastic.co/subscriptions). This feature allows you to describe which roles to assign to your users using a set of rules. - -Role mappings are required when authenticating via an external identity provider, such as Active Directory, Kerberos, PKI, OIDC, or SAML. Role mappings have no effect for users inside the `native` or `file` realms. - -You can find the **Role mappings** management page using the navigation menu or the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md). - -With **Role mappings**, you can: - -* View your configured role mappings -* Create/Edit/Delete role mappings - -![Role mappings](../../../images/kibana-role-mappings-grid.png "") - - -### Required permissions [_required_permissions_8] - -The `manage_security` cluster privilege is required to manage Role Mappings. - - -## Create a role mapping [_create_a_role_mapping] - -1. Go to the **Role mappings** management page using the navigation menu or the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md). -2. Click **Create role mapping**. -3. Give your role mapping a unique name, and choose which roles you wish to assign to your users. - - If you need more flexibility, you can use [role templates](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-put-role-mapping) instead. - -4. Define the rules describing which users should receive the roles you defined. Rules can optionally grouped and nested, allowing for sophisticated logic to suite complex requirements. -5. View the [role mapping resources for an overview of the allowed rule types](../../../deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md). - - -## Example [_example_2] - -Let’s create a `sales-users` role mapping, which assigns a `sales` role to users whose username starts with `sls_`, **or** belongs to the `executive` group. - -First, we give the role mapping a name, and assign the `sales` role: - -![Create role mapping, step 1](../../../images/kibana-role-mappings-create-step-1.png "") - -Next, we define the two rules, making sure to set the group to **Any are true**: - -![Create role mapping, step 2](../../../images/kibana-role-mappings-create-step-2.gif "") - -Click **Save role mapping** once you’re finished. - From 73ada530ca38f00731d3c278ce5c9ebcee8c68e4 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Wed, 26 Feb 2025 13:21:51 -0500 Subject: [PATCH 04/19] more --- deploy-manage/toc.yml | 2 + .../mapping-users-groups-to-roles.md | 14 +++- .../role-mapping-resources.md | 82 +++++++++++++++++++ .../role-mapping-resources.md | 3 - 4 files changed, 97 insertions(+), 4 deletions(-) create mode 100644 deploy-manage/users-roles/cluster-or-deployment-auth/role-mapping-resources.md diff --git a/deploy-manage/toc.yml b/deploy-manage/toc.yml index edb86ea956..b26f1591bc 100644 --- a/deploy-manage/toc.yml +++ b/deploy-manage/toc.yml @@ -654,6 +654,8 @@ toc: - file: users-roles/cluster-or-deployment-auth/role-restriction.md - file: users-roles/cluster-or-deployment-auth/kibana-privileges.md - file: users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md + children: + - file: users-roles/cluster-or-deployment-auth/role-mapping-resources.md - file: users-roles/cluster-or-deployment-auth/authorization-delegation.md - file: users-roles/cluster-or-deployment-auth/authorization-plugins.md - file: users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md b/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md index 4f7d2a7f10..13c5bbc129 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md @@ -2,7 +2,12 @@ mapped_urls: - https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-roles.html - https://www.elastic.co/guide/en/kibana/current/role-mappings.html - - https://www.elastic.co/guide/en/elasticsearch/reference/current/role-mapping-resources.html +applies_to: + deployment: + ece: + eck: + ess: + self: --- # Map external users and groups to roles [mapping-roles] @@ -45,6 +50,9 @@ It’s possible for a single user to have some roles that were mapped through th You can define and manage role mappings through the [add role mapping API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-put-role-mapping). +To learn about the properties that you can include in a role mapping resource, refer to [](/deploy-manage/users-roles/cluster-or-deployment-auth/role-mapping-resources.md). + +Refer to [Realm-specific details](#_realm_specific_details) for examples of mapping roles using the API. ## The role mapping UI [role-mapping-ui] @@ -103,6 +111,10 @@ You can't view, edit, or remove any roles that are defined in the role mapping f To use file based role mappings, you must configure the mappings in a YAML file. +To learn about the properties that you can include in a role mapping resource, refer to [](/deploy-manage/users-roles/cluster-or-deployment-auth/role-mapping-resources.md). + +Refer to [Realm-specific details](#_realm_specific_details) for examples of mapping roles using the role mapping file. + :::{tip} If you're using {{ece}} or {{ech}}, then you must [upload this file as a custom bundle](/deploy-manage/deploy/elastic-cloud/upload-custom-plugins-bundles.md) before it can be referenced. diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/role-mapping-resources.md b/deploy-manage/users-roles/cluster-or-deployment-auth/role-mapping-resources.md new file mode 100644 index 0000000000..69b8c9272b --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/role-mapping-resources.md @@ -0,0 +1,82 @@ +--- +mapped_urls: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/role-mapping-resources.html +navigation_title: "Role mapping properties" +applies_to: + deployment: + ece: + eck: + ess: + self: +--- + +# Role mapping resource properties [role-mapping-resources] + +A role mapping resource has the following properties: + +`enabled` +: (Boolean) Mappings that have `enabled` set to `false` are ignored when role mapping is performed. + +`metadata` +: (object) Additional metadata that helps define which roles are assigned to each user. Within the `metadata` object, keys beginning with `_` are reserved for system usage. + +`roles` +: (list) A list of roles that are granted to the users that match the role mapping rules. + +`rules` +: (object) The rules that determine which users should be matched by the mapping. A rule is a logical condition that is expressed by using a JSON DSL. The DSL supports the following rule types: + + `any` + : (array of rules) If **any** of its children are true, it evaluates to `true`. + + `all` + : (array of rules) If **all** of its children are true, it evaluates to `true`. + + `field` + : (object) See [Field rules](#mapping-roles-rule-field). + + `except` + : (object) A single rule as an object. Only valid as a child of an `all` rule. If its child is `false`, the `except` is `true`. + +## Field rules [mapping-roles-rule-field] + +The `field` rule is the primary building block for a role mapping expression. It takes a single object as its value and that object must contain a single member with key *F* and value *V*. The field rule looks up the value of *F* within the user object and then tests whether the user value *matches* the provided value *V*. + +The value specified in the field rule can be one of the following types: + +| Type | Description | Example | +| --- | --- | --- | +| Simple String | Exactly matches the provided value. | `"esadmin"` | +| Wildcard String | Matches the provided value using a wildcard. | `"*,dc=example,dc=com"` | +| Regular Expression | Matches the provided value using a [Lucene regexp](asciidocalypse://docs/elasticsearch/docs/reference/query-languages/regexp-syntax.md). | `"/.*-admin[0-9]*/"` | +| Number | Matches an equivalent numerical value. | `7` | +| Null | Matches a null or missing value. | `null` | +| Array | Tests each element in the array in accordance with the above definitions. If *any* of elements match, the match is successful. | `["admin", "operator"]` | + +### User fields [_user_fields] + +The *user object* against which rules are evaluated has the following fields: + +`username` +: (string) The username by which the {{es}} {{security-features}} knows this user. For example, `"username": "jsmith"`. + +`dn` +: (string) The *Distinguished Name* of the user. For example, `"dn": "cn=jsmith,ou=users,dc=example,dc=com",`. + +`groups` +: (array of strings) The groups to which the user belongs. For example, `"groups" : [ "cn=admin,ou=groups,dc=example,dc=com","cn=esusers,ou=groups,dc=example,dc=com ]`. + +`metadata` +: (object) Additional metadata for the user. This can include a variety of key-value pairs. When referencing metadata fields in role mapping rules, use the dot notation to specify the key within the metadata object. If the key contains special characters such as parentheses, dots, or spaces, you must escape these characters using backslashes (`\`). For example, `"metadata": { "cn": "John Smith" }`. + +`realm` +: (object) The realm that authenticated the user. The only field in this object is the realm name. For example, `"realm": { "name": "ldap1" }`. + +The `groups` field is multi-valued; a user can belong to many groups. When a `field` rule is applied against a multi-valued field, it is considered to match if *at least one* of the member values matches. For example, the following rule matches any user who is a member of the `admin` group, regardless of any other groups they belong to: + +```js +{ "field" : { "groups" : "admin" } } +``` + +For additional realm-specific details, see [Active Directory and LDAP realms](../../../deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md#ldap-role-mapping). + diff --git a/raw-migrated-files/elasticsearch/elasticsearch-reference/role-mapping-resources.md b/raw-migrated-files/elasticsearch/elasticsearch-reference/role-mapping-resources.md index 2bcd736911..1d61c67765 100644 --- a/raw-migrated-files/elasticsearch/elasticsearch-reference/role-mapping-resources.md +++ b/raw-migrated-files/elasticsearch/elasticsearch-reference/role-mapping-resources.md @@ -26,8 +26,6 @@ A role mapping resource has the following properties: `except` : (object) A single rule as an object. Only valid as a child of an `all` rule. If its child is `false`, the `except` is `true`. - - ## Field rules [mapping-roles-rule-field] The `field` rule is the primary building block for a role mapping expression. It takes a single object as its value and that object must contain a single member with key *F* and value *V*. The field rule looks up the value of *F* within the user object and then tests whether the user value *matches* the provided value *V*. @@ -43,7 +41,6 @@ The value specified in the field rule can be one of the following types: | Null | Matches a null or missing value. | `null` | | Array | Tests each element in the array in accordance with the above definitions. If *any* of elements match, the match is successful. | `["admin", "operator"]` | - ### User fields [_user_fields] The *user object* against which rules are evaluated has the following fields: From 9d362a2ed2ea08884a824c297c14f66d055d8e8f Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Wed, 26 Feb 2025 16:37:43 -0500 Subject: [PATCH 05/19] stuff --- .../_snippets/field-doc-sec-limitations.md | 44 ++ .../authorization-delegation.md | 24 +- .../authorization-plugins.md | 61 +-- ...trolling-access-at-document-field-level.md | 412 +++++++++++++++++- .../mapping-users-groups-to-roles.md | 1 + .../role-mapping-resources.md | 70 --- .../security-limitations.md | 41 +- 7 files changed, 494 insertions(+), 159 deletions(-) create mode 100644 deploy-manage/_snippets/field-doc-sec-limitations.md delete mode 100644 raw-migrated-files/elasticsearch/elasticsearch-reference/role-mapping-resources.md diff --git a/deploy-manage/_snippets/field-doc-sec-limitations.md b/deploy-manage/_snippets/field-doc-sec-limitations.md new file mode 100644 index 0000000000..a29a81fd05 --- /dev/null +++ b/deploy-manage/_snippets/field-doc-sec-limitations.md @@ -0,0 +1,44 @@ +Field and document security is subject to the following limitations: + +### Document level security limitations + +When a user’s role enables [document level security](/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md) for a data stream or index: + +* Document level security doesn’t affect global index statistics that relevancy scoring uses. This means that scores are computed without taking the role query into account. Documents that don’t match the role query are never returned. +* The `has_child` and `has_parent` queries aren’t supported as query parameters in the role definition. The `has_child` and `has_parent` queries can be used in the search API with document level security enabled. +* [Date math](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/rest-apis/common-options.md#date-math) expressions cannot contain `now` in [range queries with date fields](asciidocalypse://docs/elasticsearch/docs/reference/query-languages/query-dsl-range-query.md#ranges-on-dates) +* Any query that makes remote calls to fetch query data isn’t supported, including the following queries: + + * `terms` query with terms lookup + * `geo_shape` query with indexed shapes + * `percolate` query + +* If suggesters are specified and document level security is enabled, the specified suggesters are ignored. +* A search request cannot be profiled if document level security is enabled. +* The [terms enum API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-terms-enum) does not return terms if document level security is enabled. +* The [`multi_match`](asciidocalypse://docs/elasticsearch/docs/reference/query-languages/query-dsl-multi-match-query.md) query does not support specifying fields using wildcards. + +:::{note} +While document-level security prevents users from viewing restricted documents, it’s still possible to write search requests that return aggregate information about the entire index. A user whose access is restricted to specific documents in an index could still learn about field names and terms that only exist in inaccessible documents, and count how many inaccessible documents contain a given term. +::: + +### Field level security limitations + +When a user’s role enables document or [field level security](/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md) for a data stream or index: + +* The user cannot perform write operations: + + * The update API isn’t supported. + * Update requests included in bulk requests aren’t supported. + +* The user cannot perform operations that effectively make contents accessible under another name, including actions from the following APIs: + + * [Clone index API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-clone) + * [Shrink index API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-shrink) + * [Split index API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-split) + * [Aliases API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-update-aliases) + +* The request cache is disabled for search requests if either of the following are true: + + * The role query that defines document level security is [templated](/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md#templating-role-query) using a [stored script](../../../explore-analyze/scripting/modules-scripting-using.md#script-stored-scripts). + * The target indices are a mix of local and remote indices. diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/authorization-delegation.md b/deploy-manage/users-roles/cluster-or-deployment-auth/authorization-delegation.md index 78d7a2f5cd..4f618ffc8b 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/authorization-delegation.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/authorization-delegation.md @@ -1,17 +1,23 @@ --- mapped_pages: - https://www.elastic.co/guide/en/elasticsearch/reference/current/configuring-authorization-delegation.html +applies_to: + deployment: + ece: + eck: + ess: + self: --- # Authorization delegation [configuring-authorization-delegation] In some cases, after the user has been authenticated by a realm, we may want to delegate user lookup and assignment of roles to another realm. Any realm that supports [user lookup](looking-up-users-without-authentication.md) (without needing the user’s credentials) can be used as an authorization realm. -For example, a user that is authenticated by the Kerberos realm can be looked up in the LDAP realm. The LDAP realm takes on responsibility for searching the user in LDAP and determining the role. In this case, the LDAP realm acts as an *authorization realm*. +For example, a user that is authenticated by the Kerberos or PKI realm can be looked up in the LDAP realm. The LDAP realm takes on responsibility for searching the user in LDAP and determining the role. In this case, the LDAP realm acts as an *authorization realm*. ## LDAP realm as an authorization realm [_ldap_realm_as_an_authorization_realm] -Following is an example configuration for the LDAP realm that can be used as an *authorization realm*. This LDAP realm is configured in user search mode with a specified filter. +The following is an example configuration for the LDAP realm that can be used as an *authorization realm*. This LDAP realm is configured in user search mode with a specified filter. For more information on configuring LDAP realms see [LDAP user authentication](ldap.md). @@ -36,11 +42,11 @@ xpack: 1. Here, we explicitly allow the LDAP realm to be used for authentication (that is, users can authenticate using their LDAP username and password). If we wanted this LDAP realm to be used for authorization only, then we would set this to `false`. - - ## Kerberos realm configured to delegate authorization [_kerberos_realm_configured_to_delegate_authorization] -Following is an example configuration where the Kerberos realm authenticates a user and then delegates authorization to the LDAP realm. The Kerberos realm authenticates the user and extracts user principal name (usually of format `user@REALM`). In this example, we enable the `remove_realm_name` setting to remove the `@REALM` part from the user principal name to get the username. This username is used to do a user lookup by the configured authorization realms (in this case the LDAP realm). +The following is an example configuration where the Kerberos realm authenticates a user and then delegates authorization to the LDAP realm. The Kerberos realm authenticates the user and extracts user principal name (usually of format `user@REALM`). + +In this example, we enable the `remove_realm_name` setting to remove the `@REALM` part from the user principal name to get the username. This username is used to do a user lookup by the configured authorization realms (in this case the LDAP realm). For more information on Kerberos realm see [Kerberos authentication](kerberos.md). @@ -60,7 +66,9 @@ xpack: ## PKI realm configured to delegate authorization [_pki_realm_configured_to_delegate_authorization] -We can similarly configure PKI realm to delegate authorization to LDAP realm. The user is authenticated by the PKI realm and the authorization is delegated to the LDAP realm. In this example, the username is the common name (CN) extracted from the DN of the client certificate. The LDAP realm uses this username to lookup user and assign the role. +is an example configuration where the PKI realm authenticates a user and then delegates authorization to the LDAP realm. + +In this example, the username is the common name (CN) extracted from the DN of the client certificate. The LDAP realm uses this username to lookup user and assign the role. For more information on PKI realms see [PKI user authentication](pki.md). @@ -74,7 +82,3 @@ xpack: order: 2 authorization_realms: ldap1 ``` - -Similar to the above examples, we can configure realms to delegate authorization to authorization realms (which have the capability to lookup users by the username and assign roles). - - diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/authorization-plugins.md b/deploy-manage/users-roles/cluster-or-deployment-auth/authorization-plugins.md index 4d1d7c2c6c..02489805be 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/authorization-plugins.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/authorization-plugins.md @@ -1,6 +1,12 @@ --- mapped_pages: - https://www.elastic.co/guide/en/elasticsearch/reference/current/custom-roles-authorization.html +applies_to: + deployment: + ece: + eck: + ess: + self: --- # Authorization plugins [custom-roles-authorization] @@ -9,34 +15,37 @@ If you need to retrieve user roles from a system not supported out-of-the-box or ## Implementing a custom roles provider [implementing-custom-roles-provider] -To create a custom roles provider: +To create a custom roles provider, you need to implement the interface `BiConsumer, ActionListener>>`. The implementation consists of one method that takes a set of strings, which are the role names to resolve, and an `ActionListener`, on which the set of resolved role descriptors are passed on as the response. -1. Implement the interface `BiConsumer, ActionListener>>`. That is to say, the implementation consists of one method that takes a set of strings, which are the role names to resolve, and an ActionListener, on which the set of resolved role descriptors are passed on as the response. -2. The custom roles provider implementation must take special care to not block on any I/O operations. It is the responsibility of the implementation to ensure asynchronous behavior and non-blocking calls, which is made easier by the fact that the `ActionListener` is provided on which to send the response when the roles have been resolved and the response is ready. +Do not block on any I/O operations. It is the responsibility of the implementation to ensure asynchronous behavior and non-blocking calls, which is made easier by the fact that the `ActionListener` is provided on which to send the response when the roles have been resolved and the response is ready. -To package your custom roles provider as a plugin: +### Package a custom roles provider as a plugin [packaage-custom-roles-provider] -1. Implement an extension class for your roles provider that implements `org.elasticsearch.xpack.core.security.SecurityExtension`. There you need to override one or more of the following methods: +To package your custom roles provider as a plugin, implement an extension class for your roles provider that implements `org.elasticsearch.xpack.core.security.SecurityExtension`. There, you need to override one or more of the following methods: - ```java - @Override - public List, ActionListener>>> - getRolesProviders(Settings settings, ResourceWatcherService resourceWatcherService) { - ... - } - ``` +```java +@Override +public List, ActionListener>>> +getRolesProviders(Settings settings, ResourceWatcherService resourceWatcherService) { + ... +} +``` - The `getRolesProviders` method is used to provide a list of custom roles providers that will be used to resolve role names, if the role names could not be resolved by the reserved roles or native roles stores. The list should be returned in the order that the custom role providers should be invoked to resolve roles. For example, if `getRolesProviders` returns two instances of roles providers, and both of them are able to resolve role `A`, then the resolved role descriptor that will be used for role `A` will be the one resolved by the first roles provider in the list. +The `getRolesProviders` method is used to provide a list of custom roles providers that will be used to resolve role names, if the role names could not be resolved by the reserved roles or native roles stores. The list should be returned in the order that the custom role providers should be invoked to resolve roles. For example, if `getRolesProviders` returns two instances of roles providers, and both of them are able to resolve role `A`, then the resolved role descriptor that will be used for role `A` will be the one resolved by the first roles provider in the list. ## Implementing an authorization engine [implementing-authorization-engine] -To create an authorization engine, you need to: +Sample code that illustrates the structure and implementation of a custom authorization engine is provided in the [elasticsearch](https://github.com/elastic/elasticsearch/tree/master/plugins/examples/security-authorization-engine) repository on GitHub. You can use this code as a starting point for creating your own authorization engine. + +To create an authorization engine, you need to do the following: 1. Implement the `org.elasticsearch.xpack.core.security.authz.AuthorizationEngine` interface in a class with the desired authorization behavior. 2. Implement the `org.elasticsearch.xpack.core.security.authz.Authorization.AuthorizationInfo` interface in a class that contains the necessary information to authorize the request. +### Package an authorization engine as a plugin [packaage-auth-engine] + To package your authorization engine as a plugin: 1. Implement an extension class for your authorization engine that extends `org.elasticsearch.xpack.core.security.SecurityExtension`. There you need to override the following method: @@ -51,12 +60,9 @@ To package your authorization engine as a plugin: The `getAuthorizationEngine` method is used to provide the authorization engine implementation. -Sample code that illustrates the structure and implementation of a custom authorization engine is provided in the [elasticsearch](https://github.com/elastic/elasticsearch/tree/master/plugins/examples/security-authorization-engine) repository on GitHub. You can use this code as a starting point for creating your own authorization engine. - - -## Implement an elasticsearch plugin [packing-extension-plugin] +## Implement an {{es}} plugin [packing-extension-plugin] -In order to register the security extension for your custom roles provider or authorization engine, you need to also implement an elasticsearch plugin that contains the extension: +To register the security extension for your custom roles provider or authorization engine, you need to also implement an {{es}} plugin that contains the extension: 1. Implement a plugin class that extends `org.elasticsearch.plugins.Plugin` 2. Create a build configuration file for the plugin; Gradle is our recommendation. @@ -64,16 +70,21 @@ In order to register the security extension for your custom roles provider or au 4. Create a `META-INF/services/org.elasticsearch.xpack.core.security.SecurityExtension` descriptor file for the extension that contains the fully qualified class name of your `org.elasticsearch.xpack.core.security.SecurityExtension` implementation 5. Bundle all in a single zip file. - ## Using the security extension [using-security-extension] To use a security extension: -1. Install the plugin with the extension on each node in the cluster. You run `bin/elasticsearch-plugin` with the `install` sub-command and specify the URL pointing to the zip file that contains the extension. For example: +1. Install the plugin with the extension on each node in the cluster. + + * If you're using a self-managed cluster, then run `bin/elasticsearch-plugin` with the `install` sub-command and specify the URL pointing to the zip file that contains the extension. For example: - ```shell - bin/elasticsearch-plugin install file:////my-extension-plugin-1.0.zip - ``` + ```shell + bin/elasticsearch-plugin install file:////my-extension-plugin-1.0.zip + ``` + + * If you're using {{ech}}, then refer to [](/deploy-manage/deploy/elastic-cloud/upload-custom-plugins-bundles.md). + * If you're using {{ece}}, then refer to [](/deploy-manage/deploy/cloud-enterprise/add-custom-bundles-plugins.md). + * If you're using {{eck}}, then refer to [](/deploy-manage/deploy/cloud-on-k8s/custom-configuration-files-plugins.md). 2. Add any configuration parameters for implementations in the extension to the `elasticsearch.yml` file. The settings are not namespaced and you have access to any settings when constructing the extensions, although it is recommended to have a namespacing convention for extensions to keep your `elasticsearch.yml` configuration easy to understand. @@ -88,6 +99,6 @@ To use a security extension: These settings are passed as arguments to the methods in the `SecurityExtension` interface. -3. Restart Elasticsearch. +3. Restart {{es}}. diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md b/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md index 52cdbd034b..d2d25ee5c9 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md @@ -3,28 +3,412 @@ mapped_urls: - https://www.elastic.co/guide/en/elasticsearch/reference/current/document-level-security.html - https://www.elastic.co/guide/en/elasticsearch/reference/current/field-level-security.html - https://www.elastic.co/guide/en/elasticsearch/reference/current/field-and-document-access-control.html +applies_to: + deployment: + ece: + eck: + ess: + self: --- -# Controlling access at the document and field level +# Controlling access at the document and field level [field-and-document-access-control] -% What needs to be done: Refine +You can control access to data within a data stream or index by adding field and document level security permissions to a role. -% GitHub issue: https://github.com/elastic/docs-projects/issues/347 +**Field level security** restricts the fields that users have read access to. In particular, it restricts which fields can be accessed from document-based read APIs. -% Use migrated content from existing pages that map to this page: +**Document level security** restricts the documents that users have read access to. In particular, it restricts which documents can be accessed from document-based read APIs. -% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/document-level-security.md -% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/field-level-security.md -% - [ ] ./raw-migrated-files/elasticsearch/elasticsearch-reference/field-and-document-access-control.md +::::{note} +Document and field level security is currently meant to operate with read-only privileged accounts. Users with document and field level security enabled for a data stream or index should not perform write operations. +:::: -% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc): +A role can define both field and document level permissions on a per-index basis. A role that doesn’t specify field level permissions grants access to ALL fields. Similarly, a role that doesn’t specify document level permissions grants access to ALL documents in the index. -$$$multiple-roles-dls-fls$$$ +On this page, you'll learn how to implement [document level security](#document-level-security) and [field level security](#field-level-security-field-level-security). -$$$templating-role-query$$$ +You'll also learn the following: +* How [multiple roles with document and field level security](#multiple-roles-dls-fls) interact +* Considerations for using document and field level security when [searching across clusters using cross-cluster API keys](#ccx-apikeys-dls-fls). -**This page is a work in progress.** The documentation team is working to combine content pulled from the following pages: -* [/raw-migrated-files/elasticsearch/elasticsearch-reference/document-level-security.md](/raw-migrated-files/elasticsearch/elasticsearch-reference/document-level-security.md) -* [/raw-migrated-files/elasticsearch/elasticsearch-reference/field-level-security.md](/raw-migrated-files/elasticsearch/elasticsearch-reference/field-level-security.md) -* [/raw-migrated-files/elasticsearch/elasticsearch-reference/field-and-document-access-control.md](/raw-migrated-files/elasticsearch/elasticsearch-reference/field-and-document-access-control.md) \ No newline at end of file +:::{{tip}} +This topic explains how to apply document and field level security in {{stack}}. You can also apply document and field level security in {{serverless-full}} projects. [Learn more](/deploy-manage/users-roles/custom-roles.md#document-level-and-field-level-security). +::: + +## Implementing document level security [document-level-security] + +You can use a query to specify the documents that each role can access. The document query is associated with a particular data stream, index, or wildcard (`*`) pattern and operates in conjunction with the privileges specified for the data streams and indices. + +The specified document query: + +* Expects the same format as if it was defined in the search request +* Supports [templating a role query](#templating-role-query) that can access the details of the currently authenticated user +* Accepts queries written as either string values or nested JSON +* Supports the majority of the {{es}} [Query DSL](/explore-analyze/query-filter/languages/querydsl.md), with [some limitations](../../../deploy-manage/security.md#field-document-limitations) for field and document level security + +::::{important} +Omitting the `query` parameter entirely disables document level security for the respective indices permission entry. +:::: + +### Basic examples + +The following role definition grants read access only to documents that belong to the `click` category within all the `events-*` data streams and indices: + +```console +POST /_security/role/click_role +{ + "indices": [ + { + "names": [ "events-*" ], + "privileges": [ "read" ], + "query": "{\"match\": {\"category\": \"click\"}}" + } + ] +} +``` + +You can write this same query using nested JSON syntax: + +```console +POST _security/role/click_role +{ + "indices": [ + { + "names": [ "events-*" ], + "privileges": [ "read" ], + "query": { + "match": { + "category": "click" + } + } + } + ] +} +``` + +The following role grants read access only to the documents whose `department_id` equals `12`: + +```console +POST /_security/role/dept_role +{ + "indices" : [ + { + "names" : [ "*" ], + "privileges" : [ "read" ], + "query" : { + "term" : { "department_id" : 12 } + } + } + ] +} +``` + +### Templating a role query [templating-role-query] + +When you create a role, you can specify a query that defines the [document level security permissions](../../../deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md). You can optionally use Mustache templates in the role query to insert the username of the current authenticated user into the role. Like other places in {{es}} that support templating or scripting, you can specify inline, stored, or file-based templates and define custom parameters. You access the details for the current authenticated user through the `_user` parameter. + +For example, the following role query uses a template to insert the username of the current authenticated user: + +```console +POST /_security/role/example1 +{ + "indices" : [ + { + "names" : [ "my-index-000001" ], + "privileges" : [ "read" ], + "query" : { + "template" : { + "source" : { + "term" : { "acl.username" : "{{_user.username}}" } + } + } + } + } + ] +} +``` + +You can access the following information through the `_user` variable: + +| Property | Description | +| --- | --- | +| `_user.username` | The username of the current authenticated user. | +| `_user.full_name` | If specified, the full name of the current authenticated user. | +| `_user.email` | If specified, the email of the current authenticated user. | +| `_user.roles` | If associated, a list of the role names of the current authenticated user. | +| `_user.metadata` | If specified, a hash holding custom metadata of the current authenticated user. | + +You can also access custom user metadata. For example, if you maintain a `group_id` in your user metadata, you can apply document level security based on the `group.id` field in your documents: + +```console +POST /_security/role/example2 +{ + "indices" : [ + { + "names" : [ "my-index-000001" ], + "privileges" : [ "read" ], + "query" : { + "template" : { + "source" : { + "term" : { "group.id" : "{{_user.metadata.group_id}}" } + } + } + } + } + ] +} +``` + +If your metadata field contains an object or array, you can access it using the `{{#toJson}}parameter{{/toJson}}` function. + +```console +POST /_security/role/example3 +{ + "indices" : [ + { + "names" : [ "my-index-000001" ], + "privileges" : [ "read" ], + "query" : { + "template" : { + "source" : "{ \"terms\": { \"group.statuses\": {{#toJson}}_user.metadata.statuses{{/toJson}} }}" + } + } + } + ] +} +``` + +### Pre-processing documents to add security details [set-security-user-processor] + +To guarantee that a user reads only their own documents, it makes sense to set up document level security. In this scenario, each document must have the username or role name associated with it, so that this information can be used by the role query for document level security. This is a situation where the [set security user processor](asciidocalypse://docs/elasticsearch/docs/reference/ingestion-tools/enrich-processor/ingest-node-set-security-user-processor.md) ingest processor can help. + +::::{note} +Document level security doesn’t apply to write APIs. You must use unique ids for each user that uses the same data stream or index, otherwise they might overwrite other users' documents. The ingest processor just adds properties for the current authenticated user to the documents that are being indexed. +:::: + +The [set security user processor](asciidocalypse://docs/elasticsearch/docs/reference/ingestion-tools/enrich-processor/ingest-node-set-security-user-processor.md) attaches user-related details (such as `username`, `roles`, `email`, `full_name` and `metadata` ) from the current authenticated user to the current document by pre-processing the ingest. When you index data with an ingest pipeline, user details are automatically attached to the document. If the authenticating credential is an API key, the API key `id`, `name` and `metadata` (if it exists and is non-empty) are also attached to the document. + +For more information, see [Ingest pipelines](/manage-data/ingest/transform-enrich/ingest-pipelines.md) and [Set security user](asciidocalypse://docs/elasticsearch/docs/reference/ingestion-tools/enrich-processor/ingest-node-set-security-user-processor.md). + + +# Field level security [field-level-security] + +To enable field level security, specify the fields that each role can access as part of the indices permissions in a role definition. Field level security is thus bound to a well-defined set of data streams or indices (and potentially a set of [documents](../../../deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md)). + +The following role definition grants read access only to the `category`, `@timestamp`, and `message` fields in all the `events-*` data streams and indices. + +```console +POST /_security/role/test_role1 +{ + "indices": [ + { + "names": [ "events-*" ], + "privileges": [ "read" ], + "field_security" : { + "grant" : [ "category", "@timestamp", "message" ] + } + } + ] +} +``` + +Access to the following metadata fields is always allowed: `_id`, `_type`, `_parent`, `_routing`, `_timestamp`, `_ttl`, `_size` and `_index`. If you specify an empty list of fields, only these metadata fields are accessible. + +::::{note} +Omitting the fields entry entirely disables field level security. +:::: + + +You can also specify field expressions. For example, the following example grants read access to all fields that start with an `event_` prefix: + +```console +POST /_security/role/test_role2 +{ + "indices" : [ + { + "names" : [ "*" ], + "privileges" : [ "read" ], + "field_security" : { + "grant" : [ "event_*" ] + } + } + ] +} +``` + +Use the dot notations to refer to nested fields in more complex documents. For example, assuming the following document: + +```js +{ + "customer": { + "handle": "Jim", + "email": "jim@mycompany.com", + "phone": "555-555-5555" + } +} +``` + +The following role definition enables only read access to the customer `handle` field: + +```console +POST /_security/role/test_role3 +{ + "indices" : [ + { + "names" : [ "*" ], + "privileges" : [ "read" ], + "field_security" : { + "grant" : [ "customer.handle" ] + } + } + ] +} +``` + +This is where wildcard support shines. For example, use `customer.*` to enable only read access to the `customer` data: + +```console +POST /_security/role/test_role4 +{ + "indices" : [ + { + "names" : [ "*" ], + "privileges" : [ "read" ], + "field_security" : { + "grant" : [ "customer.*" ] + } + } + ] +} +``` + +You can deny permission to access fields with the following syntax: + +```console +POST /_security/role/test_role5 +{ + "indices" : [ + { + "names" : [ "*" ], + "privileges" : [ "read" ], + "field_security" : { + "grant" : [ "*"], + "except": [ "customer.handle" ] + } + } + ] +} +``` + +The following rules apply: + +* The absence of `field_security` in a role is equivalent to * access. +* If permission has been granted explicitly to some fields, you can specify denied fields. The denied fields must be a subset of the fields to which permissions were granted. +* Defining denied and granted fields implies access to all granted fields except those which match the pattern in the denied fields. + +For example: + +```console +POST /_security/role/test_role6 +{ + "indices" : [ + { + "names" : [ "*" ], + "privileges" : [ "read" ], + "field_security" : { + "except": [ "customer.handle" ], + "grant" : [ "customer.*" ] + } + } + ] +} +``` + +In the above example, users can read all fields with the prefix "customer." except for "customer.handle". + +An empty array for `grant` (for example, `"grant" : []`) means that access has not been granted to any fields. + +When a user has several roles that specify field level permissions, the resulting field level permissions per data stream or index are the union of the individual role permissions. For example, if these two roles are merged: + +```console +POST /_security/role/test_role7 +{ + "indices" : [ + { + "names" : [ "*" ], + "privileges" : [ "read" ], + "field_security" : { + "grant": [ "a.*" ], + "except" : [ "a.b*" ] + } + } + ] +} + +POST /_security/role/test_role8 +{ + "indices" : [ + { + "names" : [ "*" ], + "privileges" : [ "read" ], + "field_security" : { + "grant": [ "a.b*" ], + "except" : [ "a.b.c*" ] + } + } + ] +} +``` + +The resulting permission is equal to: + +```js +{ + // role 1 + role 2 + ... + "indices" : [ + { + "names" : [ "*" ], + "privileges" : [ "read" ], + "field_security" : { + "grant": [ "a.*" ], + "except" : [ "a.b.c*" ] + } + } + ] +} +``` + +::::{note} +Field-level security should not be set on [`alias`](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/mapping-reference/field-alias.md) fields. To secure a concrete field, its field name must be used directly. +:::: + +## Multiple roles with document and field level security [multiple-roles-dls-fls] + +A user can have many roles and each role can define different permissions on the same data stream or index. When assigning users multiple roles, be careful that you don’t inadvertently grant wider access than intended. + +**Document level security** takes into account each role held by the user and combines each document level security query for a given data stream or index with an "OR". This means that only one of the role queries must match for a document to be returned. For example, if a role grants access to an index without document level security and another grants access with document level security, document level security is not applied; the user with both roles has access to all of the documents in the index. + +**Field level security** takes into account each role the user has and combines all of the fields listed into a single set for each data stream or index. For example, if a role grants access to an index without field level security and another grants access with field level security, field level security is not be applied for that index; the user with both roles has access to all of the fields in the index. + +For example, let’s say `role_a` grants access to only the `address` field of the documents in `index1`; it doesn’t specify any document restrictions. Conversely, `role_b` limits access to a subset of the documents in `index1`; it doesn’t specify any field restrictions. If you assign a user both roles, `role_a` gives the user access to all documents and `role_b` gives the user access to all fields. + +::::{important} +If you need to restrict access to both documents and fields, consider splitting documents by index instead. +:::: + +## Field and document level security with Cross-cluster API keys [ccx-apikeys-dls-fls] + +[Cross-cluster API keys](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-cross-cluster-api-key) can be used to authenticate requests to a remote cluster. The `search` parameter defines permissions for cross-cluster search. The `replication` parameter defines permissions for cross-cluster replication. + +`replication` does not support any field or document level security. `search` supports field and document level security. + +For reasons similar to those described in [Multiple roles with document and field level security](../../../deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md#multiple-roles-dls-fls), you can’t create a single cross-cluster API key with both the `search` and `replication` parameters if the `search` parameter has document or field level security defined. + +If you need to use both of these parameters, and you need to define document or field level security for the `search` parameter, create two separate cross-cluster API keys, one using the `search` parameter, and one using the `replication` parameter. You will also need to set up two different remote connections to the same cluster, with each named connection using the appropriate cross-cluster API key. + +## Limitations + +::::{include} /deploy-manage/_snippets/field-doc-sec-limitations.md +:::: diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md b/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md index 13c5bbc129..6edfa92cd0 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md @@ -8,6 +8,7 @@ applies_to: eck: ess: self: +navigation_title: Map users and groups to roles --- # Map external users and groups to roles [mapping-roles] diff --git a/raw-migrated-files/elasticsearch/elasticsearch-reference/role-mapping-resources.md b/raw-migrated-files/elasticsearch/elasticsearch-reference/role-mapping-resources.md deleted file mode 100644 index 1d61c67765..0000000000 --- a/raw-migrated-files/elasticsearch/elasticsearch-reference/role-mapping-resources.md +++ /dev/null @@ -1,70 +0,0 @@ -# Role mapping resources [role-mapping-resources] - -A role mapping resource has the following properties: - -`enabled` -: (Boolean) Mappings that have `enabled` set to `false` are ignored when role mapping is performed. - -`metadata` -: (object) Additional metadata that helps define which roles are assigned to each user. Within the `metadata` object, keys beginning with `_` are reserved for system usage. - -`roles` -: (list) A list of roles that are granted to the users that match the role mapping rules. - -`rules` -: (object) The rules that determine which users should be matched by the mapping. A rule is a logical condition that is expressed by using a JSON DSL. The DSL supports the following rule types: - - `any` - : (array of rules) If **any** of its children are true, it evaluates to `true`. - - `all` - : (array of rules) If **all** of its children are true, it evaluates to `true`. - - `field` - : (object) See [Field rules](#mapping-roles-rule-field). - - `except` - : (object) A single rule as an object. Only valid as a child of an `all` rule. If its child is `false`, the `except` is `true`. - -## Field rules [mapping-roles-rule-field] - -The `field` rule is the primary building block for a role mapping expression. It takes a single object as its value and that object must contain a single member with key *F* and value *V*. The field rule looks up the value of *F* within the user object and then tests whether the user value *matches* the provided value *V*. - -The value specified in the field rule can be one of the following types: - -| Type | Description | Example | -| --- | --- | --- | -| Simple String | Exactly matches the provided value. | `"esadmin"` | -| Wildcard String | Matches the provided value using a wildcard. | `"*,dc=example,dc=com"` | -| Regular Expression | Matches the provided value using a [Lucene regexp](asciidocalypse://docs/elasticsearch/docs/reference/query-languages/regexp-syntax.md). | `"/.*-admin[0-9]*/"` | -| Number | Matches an equivalent numerical value. | `7` | -| Null | Matches a null or missing value. | `null` | -| Array | Tests each element in the array in accordance with the above definitions. If *any* of elements match, the match is successful. | `["admin", "operator"]` | - -### User fields [_user_fields] - -The *user object* against which rules are evaluated has the following fields: - -`username` -: (string) The username by which the {{es}} {{security-features}} knows this user. For example, `"username": "jsmith"`. - -`dn` -: (string) The *Distinguished Name* of the user. For example, `"dn": "cn=jsmith,ou=users,dc=example,dc=com",`. - -`groups` -: (array of strings) The groups to which the user belongs. For example, `"groups" : [ "cn=admin,ou=groups,dc=example,dc=com","cn=esusers,ou=groups,dc=example,dc=com ]`. - -`metadata` -: (object) Additional metadata for the user. This can include a variety of key-value pairs. When referencing metadata fields in role mapping rules, use the dot notation to specify the key within the metadata object. If the key contains special characters such as parentheses, dots, or spaces, you must escape these characters using backslashes (`\`). For example, `"metadata": { "cn": "John Smith" }`. - -`realm` -: (object) The realm that authenticated the user. The only field in this object is the realm name. For example, `"realm": { "name": "ldap1" }`. - -The `groups` field is multi-valued; a user can belong to many groups. When a `field` rule is applied against a multi-valued field, it is considered to match if *at least one* of the member values matches. For example, the following rule matches any user who is a member of the `admin` group, regardless of any other groups they belong to: - -```js -{ "field" : { "groups" : "admin" } } -``` - -For additional realm-specific details, see [Active Directory and LDAP realms](../../../deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md#ldap-role-mapping). - diff --git a/raw-migrated-files/elasticsearch/elasticsearch-reference/security-limitations.md b/raw-migrated-files/elasticsearch/elasticsearch-reference/security-limitations.md index e4cd12b40c..424a908ecd 100644 --- a/raw-migrated-files/elasticsearch/elasticsearch-reference/security-limitations.md +++ b/raw-migrated-files/elasticsearch/elasticsearch-reference/security-limitations.md @@ -28,48 +28,9 @@ Aliases containing filters are not a secure way to restrict access to individual ## Field and document level security limitations [field-document-limitations] -When a user’s role enables document or [field level security](../../../deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md) for a data stream or index: - -* The user cannot perform write operations: - - * The update API isn’t supported. - * Update requests included in bulk requests aren’t supported. - -* The user cannot perform operations that effectively make contents accessible under another name, including actions from the following APIs: - - * [Clone index API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-clone) - * [Shrink index API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-shrink) - * [Split index API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-split) - * [Aliases API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-update-aliases) - -* The request cache is disabled for search requests if either of the following are true: - - * The role query that defines document level security is [templated](../../../deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md#templating-role-query) using a [stored script](../../../explore-analyze/scripting/modules-scripting-using.md#script-stored-scripts). - * The target indices are a mix of local and remote indices. - - -When a user’s role enables [document level security](../../../deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md) for a data stream or index: - -* Document level security doesn’t affect global index statistics that relevancy scoring uses. This means that scores are computed without taking the role query into account. Documents that don’t match the role query are never returned. -* The `has_child` and `has_parent` queries aren’t supported as query parameters in the role definition. The `has_child` and `has_parent` queries can be used in the search API with document level security enabled. -* [Date math](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/rest-apis/common-options.md#date-math) expressions cannot contain `now` in [range queries with date fields](asciidocalypse://docs/elasticsearch/docs/reference/query-languages/query-dsl-range-query.md#ranges-on-dates) -* Any query that makes remote calls to fetch query data isn’t supported, including the following queries: - - * `terms` query with terms lookup - * `geo_shape` query with indexed shapes - * `percolate` query - -* If suggesters are specified and document level security is enabled, the specified suggesters are ignored. -* A search request cannot be profiled if document level security is enabled. -* The [terms enum API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-terms-enum) does not return terms if document level security is enabled. -* The [`multi_match`](asciidocalypse://docs/elasticsearch/docs/reference/query-languages/query-dsl-multi-match-query.md) query does not support specifying fields using wildcards. - -::::{note} -While document-level security prevents users from viewing restricted documents, it’s still possible to write search requests that return aggregate information about the entire index. A user whose access is restricted to specific documents in an index could still learn about field names and terms that only exist in inaccessible documents, and count how many inaccessible documents contain a given term. +::::{include} /deploy-manage/_snippets/field-doc-sec-limitations.md :::: - - ## Index and field names can be leaked when using aliases [alias-limitations] Calling certain {{es}} APIs on an alias can potentially leak information about indices that the user isn’t authorized to access. For example, when you get the mappings for an alias with the `_mapping` API, the response includes the index name and mappings for each index that the alias applies to. From 135692c5b886543a47616931718981d939ef9ac8 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Wed, 26 Feb 2025 19:00:21 -0500 Subject: [PATCH 06/19] it's cute now --- .../_snippets/field-doc-sec-limitations.md | 2 +- deploy-manage/toc.yml | 2 +- ...trolling-access-at-document-field-level.md | 16 ++++++---- ...om-roles.md => serverless-custom-roles.md} | 30 +++++++++++++++---- 4 files changed, 37 insertions(+), 13 deletions(-) rename deploy-manage/users-roles/{custom-roles.md => serverless-custom-roles.md} (83%) diff --git a/deploy-manage/_snippets/field-doc-sec-limitations.md b/deploy-manage/_snippets/field-doc-sec-limitations.md index a29a81fd05..956a20a27c 100644 --- a/deploy-manage/_snippets/field-doc-sec-limitations.md +++ b/deploy-manage/_snippets/field-doc-sec-limitations.md @@ -6,7 +6,7 @@ When a user’s role enables [document level security](/deploy-manage/users-role * Document level security doesn’t affect global index statistics that relevancy scoring uses. This means that scores are computed without taking the role query into account. Documents that don’t match the role query are never returned. * The `has_child` and `has_parent` queries aren’t supported as query parameters in the role definition. The `has_child` and `has_parent` queries can be used in the search API with document level security enabled. -* [Date math](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/rest-apis/common-options.md#date-math) expressions cannot contain `now` in [range queries with date fields](asciidocalypse://docs/elasticsearch/docs/reference/query-languages/query-dsl-range-query.md#ranges-on-dates) +* [Date math](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/rest-apis/common-options.md#date-math) expressions cannot contain `now` in [range queries with date fields](asciidocalypse://docs/elasticsearch/docs/reference/query-languages/query-dsl-range-query.md#ranges-on-dates). * Any query that makes remote calls to fetch query data isn’t supported, including the following queries: * `terms` query with terms lookup diff --git a/deploy-manage/toc.yml b/deploy-manage/toc.yml index b26f1591bc..0f703f39d2 100644 --- a/deploy-manage/toc.yml +++ b/deploy-manage/toc.yml @@ -594,7 +594,7 @@ toc: - file: users-roles/cloud-enterprise-orchestrator/ldap.md - file: users-roles/cloud-enterprise-orchestrator/saml.md - file: users-roles/cloud-enterprise-orchestrator/configure-sso-for-deployments.md - - file: users-roles/custom-roles.md + - file: users-roles/serverless-custom-roles.md - file: users-roles/cluster-or-deployment-auth.md children: - file: users-roles/cluster-or-deployment-auth/quickstart.md diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md b/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md index d2d25ee5c9..c809360f1e 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md @@ -25,18 +25,24 @@ Document and field level security is currently meant to operate with read-only p A role can define both field and document level permissions on a per-index basis. A role that doesn’t specify field level permissions grants access to ALL fields. Similarly, a role that doesn’t specify document level permissions grants access to ALL documents in the index. -On this page, you'll learn how to implement [document level security](#document-level-security) and [field level security](#field-level-security-field-level-security). +On this page, you'll learn how to implement [document level security](#document-level-security) and [field level security](#field-level-security-field-level-security). You'll also learn the following: * How [multiple roles with document and field level security](#multiple-roles-dls-fls) interact * Considerations for using document and field level security when [searching across clusters using cross-cluster API keys](#ccx-apikeys-dls-fls). +The examples on this page use the [Role management API](https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-security). However, you can add document and field level security [anywhere you manage custom roles](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md#managing-custom-roles). -:::{{tip}} -This topic explains how to apply document and field level security in {{stack}}. You can also apply document and field level security in {{serverless-full}} projects. [Learn more](/deploy-manage/users-roles/custom-roles.md#document-level-and-field-level-security). + +:::{{admonition}} Document and field level security in {{serverless-full}} +This topic explains how to apply document and field level security in {{stack}}. You can also apply document and field level security in {{serverless-full}} projects. + +In {{serverless-full}}, you can only manage document and field level security using the {{ecloud}} console. However, document level security is still managed using queries, and you can use the queries on this page as a guideline. + +[Learn more](/deploy-manage/users-roles/serverless-custom-roles.md#document-level-and-field-level-security). ::: -## Implementing document level security [document-level-security] +## Document level security [document-level-security] You can use a query to specify the documents that each role can access. The document query is associated with a particular data stream, index, or wildcard (`*`) pattern and operates in conjunction with the privileges specified for the data streams and indices. @@ -192,7 +198,7 @@ The [set security user processor](asciidocalypse://docs/elasticsearch/docs/refer For more information, see [Ingest pipelines](/manage-data/ingest/transform-enrich/ingest-pipelines.md) and [Set security user](asciidocalypse://docs/elasticsearch/docs/reference/ingestion-tools/enrich-processor/ingest-node-set-security-user-processor.md). -# Field level security [field-level-security] +## Field level security [field-level-security] To enable field level security, specify the fields that each role can access as part of the indices permissions in a role definition. Field level security is thus bound to a well-defined set of data streams or indices (and potentially a set of [documents](../../../deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md)). diff --git a/deploy-manage/users-roles/custom-roles.md b/deploy-manage/users-roles/serverless-custom-roles.md similarity index 83% rename from deploy-manage/users-roles/custom-roles.md rename to deploy-manage/users-roles/serverless-custom-roles.md index 1f8218fa6f..fb021ab73f 100644 --- a/deploy-manage/users-roles/custom-roles.md +++ b/deploy-manage/users-roles/serverless-custom-roles.md @@ -2,11 +2,11 @@ mapped_urls: - https://www.elastic.co/guide/en/serverless/current/custom-roles.html applies_to: - serverless: all + serverless: + elasticsearch: + security: --- -This content applies to: [![Elasticsearch](../../images/serverless-es-badge.svg "")](../../solutions/search.md) [![Security](../../images/serverless-sec-badge.svg "")](../../solutions/security/elastic-security-serverless.md) - # Serverless project custom roles [custom-roles] Built-in [organization-level roles](/deploy-manage/users-roles/cloud-organization/user-roles.md#ec_organization_level_roles) and [instance access roles](/deploy-manage/users-roles/cloud-organization/user-roles.md#ec_instance_access_roles) are great for getting started with {{serverless-full}}, and for system administrators who do not need more restrictive access. @@ -21,9 +21,14 @@ On this page, you'll learn about how to [manage custom roles in your project](#m ::::{note} You cannot assign [run as privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md#_run_as_privilege) in {{serverless-full}} custom roles. - :::: +:::{{admonition}} Custom roles in {{stack}} +This topic explains how to create custom roles in {{serverless-full}}. You can also create custom roles for {{stack}} clusters and deployments. + +[Learn more](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md). +::: + ## Manage custom roles You can manage custom roles from within your project, in **{{project-settings}} > {{manage-app}} > {{custom-roles-app}}**. To create a new custom role, click the **Create role** button. To clone, delete, or edit a role, open the actions menu `⋯`. @@ -51,13 +56,26 @@ Each role can grant access to multiple data indices, and each index can have a d Refer to [index privileges](asciidocalypse://reference/elasticsearch/security-privileges.md#privileges-list-indices) for a complete description of available options. -### Document-level and field-level security +### Document level and field level security Document-level and field-level security affords you even more granularity when it comes to granting access to your data: -* With document-level security (DLS), you can write an {{es}} query to describe which documents this role grants access to. Add your query in the **Granted documents query** field. +* With document-level security (DLS), you can write an {{es}} query to describe which documents this role grants access to. Add your query in the **Granted documents query** field using [QueryDSL](/explore-analyze/query-filter/languages/querydsl.md) syntax. + + For example, the following query grants read access only to the documents whose `department_id` equals `12`: + + ```json + { + "term" : { "department_id" : 12 } + } + ``` + * With field-level security (FLS), you can instruct {{es}} to grant or deny access to specific fields within each document. List these fields in the **Granted fields** field. +:::{{tip}} +{{serverless-full}} and {{stack}} both use queries to specify the documents that a role can access. For additional query examples, refer to [Controlling access at the document and field level](/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level#document-level-security). +::: + ## {{kib}} privileges [custom-roles-kib-privileges] From 4fd489e300830eba3700d64f2b9a495b792fd046 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Wed, 26 Feb 2025 19:21:42 -0500 Subject: [PATCH 07/19] nearly there --- ...trolling-access-at-document-field-level.md | 1 + ...tting-requests-on-behalf-of-other-users.md | 196 ++++++++++-------- 2 files changed, 107 insertions(+), 90 deletions(-) diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md b/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md index c809360f1e..0bf238104b 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md @@ -9,6 +9,7 @@ applies_to: eck: ess: self: +navigation_title: Control access at the document and field level --- # Controlling access at the document and field level [field-and-document-access-control] diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md b/deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md index 1a91d6925f..6951e79e6b 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md @@ -1,6 +1,13 @@ --- mapped_pages: - https://www.elastic.co/guide/en/elasticsearch/reference/current/run-as-privilege.html +applies_to: + deployment: + ece: + eck: + ess: + self: +navigation_title: Submit requests on behalf of other users --- # Submitting requests on behalf of other users [run-as-privilege] @@ -11,12 +18,14 @@ To "run as" (impersonate) another user, the first user (the authenticating user) The `run_as` privilege essentially operates like a secondary form of [delegated authorization](realm-chains.md#authorization_realms). Delegated authorization applies to the authenticating user, and the `run_as` privilege applies to the user who is being impersonated. -true -For the authenticating user, the following realms (plus API keys) all support `run_as` delegation: `native`, `file`, Active Directory, JWT, Kerberos, LDAP and PKI. +## Authenticating user -Service tokens, the {{es}} Token Service, SAML 2.0, and OIDC 1.0 do not support `run_as` delegation. +For the authenticating user, the following realms (plus API keys) all support `run_as` delegation: [native](/deploy-manage/users-roles/cluster-or-deployment-auth/native.md), [file](/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md), [Active Directory](/deploy-manage/users-roles/cluster-or-deployment-auth/active-directory.md), [JWT](/deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md), [Kerberos](/deploy-manage/users-roles/cluster-or-deployment-auth/kerberos.md), [LDAP](/deploy-manage/users-roles/cluster-or-deployment-auth/ldap.md), and [PKI](/deploy-manage/users-roles/cluster-or-deployment-auth/pki.md). + +Service tokens, the {{es}} token service, SAML, and OIDC do not support `run_as` delegation. + +## `run_as` user -true {{es}} supports `run_as` for any realm that supports user lookup. Not all realms support user lookup. Refer to the list of [supported realms](looking-up-users-without-authentication.md) and ensure that the realm you wish to use is configured in a manner that supports user lookup. The `run_as` user must be retrieved from a [realm](authentication-realms.md) - it is not possible to run as a [service account](service-accounts.md), [API key](token-based-authentication-services.md#token-authentication-api-key) or [access token](token-based-authentication-services.md#token-authentication-access-token). @@ -52,107 +61,114 @@ For example, JWT realms can authenticate external users specified in JWTs, and e ## Apply the `run_as` privilege to roles [run-as-privilege-apply] -You can apply the `run_as` privilege when creating roles with the [create or update roles API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-put-role). Users who are assigned a role that contains the `run_as` privilege inherit all privileges from their role, and can also submit requests on behalf of the indicated users. +You can apply the `run_as` privilege when creating roles with the [role management API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-put-role), or using the [role management UI](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-role-management.md) in {{kib}}. Users who are assigned a role that contains the `run_as` privilege inherit all privileges from their role, and can also submit requests on behalf of the indicated users. ::::{note} Roles for the authenticated user and the `run_as` user are not merged. If a user authenticates without specifying the `run_as` parameter, only the authenticated user’s roles are used. If a user authenticates and their roles include the `run_as` parameter, only the `run_as` user’s roles are used. :::: - After a user successfully authenticates to {{es}}, an authorization process determines whether the user behind an incoming request is allowed to run that request. If the authenticated user has the `run_as` privilege in their list of permissions and specifies the run-as header, {{es}} *discards* the authenticated user and associated roles. It then looks in each of the configured realms in the realm chain until it finds the username that’s associated with the `run_as` user, and uses those roles to execute any requests. +### Example + Consider an admin role and an analyst role. The admin role has higher privileges, but might also want to submit requests as another user to test and verify their permissions. -First, we’ll create an admin role named `my_admin_role`. This role has `manage` [privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md) on the entire cluster, and on a subset of indices. This role also contains the `run_as` privilege, which enables any user with this role to submit requests on behalf of the specified `analyst_user`. +This example uses the role management API, but a similar configuration can be set up using the [Create users](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-role-management.md) and [Users](/deploy-manage/users-roles/cluster-or-deployment-auth/native.md#managing-native-users) pages in {{kib}}. -```console -POST /_security/role/my_admin_role?refresh=true -{ - "cluster": ["manage"], - "indices": [ - { - "names": [ "index1", "index2" ], - "privileges": [ "manage" ] - } - ], - "applications": [ - { - "application": "myapp", - "privileges": [ "admin", "read" ], - "resources": [ "*" ] - } - ], - "run_as": [ "analyst_user" ], - "metadata" : { - "version" : 1 - } -} -``` +1. Create an admin role named `my_admin_role`. This role has `manage` [privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md) on the entire cluster, and on a subset of indices. This role also contains the `run_as` privilege, which enables any user with this role to submit requests on behalf of the specified `analyst_user`. -Next, we’ll create an analyst role named `my_analyst_role`, which has more restricted `monitor` cluster privileges and `manage` privileges on a subset of indices. + You can set up a similar role using the [role management UI](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-role-management.md) in {{kib}} by selecting an `analyst_user` from the **Run As privileges** dropdown menu in the **Elasticsearch** section. -```console -POST /_security/role/my_analyst_role?refresh=true -{ - "cluster": [ "monitor"], - "indices": [ - { - "names": [ "index1", "index2" ], - "privileges": ["manage"] - } - ], - "applications": [ + ```console + POST /_security/role/my_admin_role?refresh=true { - "application": "myapp", - "privileges": [ "read" ], - "resources": [ "*" ] + "cluster": ["manage"], + "indices": [ + { + "names": [ "index1", "index2" ], + "privileges": [ "manage" ] + } + ], + "applications": [ + { + "application": "myapp", + "privileges": [ "admin", "read" ], + "resources": [ "*" ] + } + ], + "run_as": [ "analyst_user" ], + "metadata" : { + "version" : 1 + } } - ], - "metadata" : { - "version" : 1 - } -} -``` - -We’ll create an administrator user and assign them the role named `my_admin_role`, which allows this user to submit requests as the `analyst_user`. + ``` -```console -POST /_security/user/admin_user?refresh=true -{ - "password": "l0ng-r4nd0m-p@ssw0rd", - "roles": [ "my_admin_role" ], - "full_name": "Eirian Zola", - "metadata": { "intelligence" : 7} -} -``` +2. Create an analyst role named `my_analyst_role`, which has more restricted `monitor` cluster privileges and `manage` privileges on a subset of indices. -We can also create an analyst user and assign them the role named `my_analyst_role`. - -```console -POST /_security/user/analyst_user?refresh=true -{ - "password": "l0nger-r4nd0mer-p@ssw0rd", - "roles": [ "my_analyst_role" ], - "full_name": "Monday Jaffe", - "metadata": { "innovation" : 8} -} -``` - -You can then authenticate to {{es}} as the `admin_user` or `analyst_user`. However, the `admin_user` could optionally submit requests on behalf of the `analyst_user`. The following request authenticates to {{es}} with a `Basic` authorization token and submits the request as the `analyst_user`: - -```sh -curl -s -X GET -H "Authorization: Basic YWRtaW5fdXNlcjpsMG5nLXI0bmQwbS1wQHNzdzByZA==" -H "es-security-runas-user: analyst_user" https://localhost:9200/_security/_authenticate -``` - -The response indicates that the `analyst_user` submitted this request, using the `my_analyst_role` that’s assigned to that user. When the `admin_user` submitted the request, {{es}} authenticated that user, discarded their roles, and then used the roles of the `run_as` user. - -```sh -{"username":"analyst_user","roles":["my_analyst_role"],"full_name":"Monday Jaffe","email":null, -"metadata":{"innovation":8},"enabled":true,"authentication_realm":{"name":"native", -"type":"native"},"lookup_realm":{"name":"native","type":"native"},"authentication_type":"realm"} -% -``` - -The `authentication_realm` and `lookup_realm` in the response both specify the `native` realm because both the `admin_user` and `analyst_user` are from that realm. If the two users are in different realms, the values for `authentication_realm` and `lookup_realm` are different (such as `pki` and `native`). + ```console + POST /_security/role/my_analyst_role?refresh=true + { + "cluster": [ "monitor"], + "indices": [ + { + "names": [ "index1", "index2" ], + "privileges": ["manage"] + } + ], + "applications": [ + { + "application": "myapp", + "privileges": [ "read" ], + "resources": [ "*" ] + } + ], + "metadata" : { + "version" : 1 + } + } + ``` + +3. Create an administrator user and assign them the role named `my_admin_role`, which allows this user to submit requests as the `analyst_user`. + + ```console + POST /_security/user/admin_user?refresh=true + { + "password": "l0ng-r4nd0m-p@ssw0rd", + "roles": [ "my_admin_role" ], + "full_name": "Eirian Zola", + "metadata": { "intelligence" : 7} + } + ``` + +4. Create an analyst user and assign them the role named `my_analyst_role`. + + ```console + POST /_security/user/analyst_user?refresh=true + { + "password": "l0nger-r4nd0mer-p@ssw0rd", + "roles": [ "my_analyst_role" ], + "full_name": "Monday Jaffe", + "metadata": { "innovation" : 8} + } + ``` + +5. You can then authenticate to {{es}} as the `admin_user` or `analyst_user`. However, the `admin_user` could optionally submit requests on behalf of the `analyst_user`. + + The following request authenticates to {{es}} with a `Basic` authorization token and submits the request as the `analyst_user`: + + ```sh + curl -s -X GET -H "Authorization: Basic YWRtaW5fdXNlcjpsMG5nLXI0bmQwbS1wQHNzdzByZA==" -H "es-security-runas-user: analyst_user" https://localhost:9200/_security/_authenticate + ``` + + The response indicates that the `analyst_user` submitted this request, using the `my_analyst_role` that’s assigned to that user. When the `admin_user` submitted the request, {{es}} authenticated that user, discarded their roles, and then used the roles of the `run_as` user. + + ```sh + {"username":"analyst_user","roles":["my_analyst_role"],"full_name":"Monday Jaffe","email":null, + "metadata":{"innovation":8},"enabled":true,"authentication_realm":{"name":"native", + "type":"native"},"lookup_realm":{"name":"native","type":"native"},"authentication_type":"realm"} + % + ``` + + The `authentication_realm` and `lookup_realm` in the response both specify the `native` realm because both the `admin_user` and `analyst_user` are from that realm. If the two users are in different realms, the values for `authentication_realm` and `lookup_realm` are different (such as `pki` and `native`). From 7e9df7570a5a484697775e1531193fd635dbf4be Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Wed, 26 Feb 2025 23:10:38 -0500 Subject: [PATCH 08/19] fix links --- deploy-manage/toc.yml | 1 + .../elasticsearch-privileges.md | 8 ++++++++ .../cluster-or-deployment-auth/kibana-privileges.md | 2 ++ .../submitting-requests-on-behalf-of-other-users.md | 2 -- .../security/elastic-defend/endpoint-management-req.md | 2 +- .../elastic-defend-feature-privileges.md | 2 +- .../dashboards/detection-rule-monitoring-dashboard.md | 2 +- .../configure-third-party-response-actions.md | 2 +- solutions/security/explore/configure-network-map-data.md | 2 +- 9 files changed, 16 insertions(+), 7 deletions(-) diff --git a/deploy-manage/toc.yml b/deploy-manage/toc.yml index 0f703f39d2..6576348875 100644 --- a/deploy-manage/toc.yml +++ b/deploy-manage/toc.yml @@ -652,6 +652,7 @@ toc: - file: users-roles/cluster-or-deployment-auth/granting-privileges-for-data-streams-aliases.md - file: users-roles/cluster-or-deployment-auth/kibana-role-management.md - file: users-roles/cluster-or-deployment-auth/role-restriction.md + - file: users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md - file: users-roles/cluster-or-deployment-auth/kibana-privileges.md - file: users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md children: diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md b/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md index 062cc7fba0..a37cd32f4b 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md @@ -1,12 +1,20 @@ --- mapped_pages: - https://www.elastic.co/guide/en/elasticsearch/reference/current/security-privileges.html +applies_to: + deployment: + ece: + eck: + ess: + self: --- # Elasticsearch privileges [security-privileges] This section lists the privileges that you can assign to a role. +To learn how to assign privileges to a role, refer to [](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md). + ## Cluster privileges [privileges-list-cluster] `all` diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md b/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md index 41842f504c..33fb4f6676 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md @@ -13,6 +13,8 @@ applies_to: {{kib}} privileges grant users access to features within {{kib}}. Roles have privileges to determine whether users have write or read access. +To learn how to assign privileges to a role, refer to [](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md). + ## Base privileges [_base_privileges] Assigning a base privilege grants access to all {{kib}} features, such as **Discover**, **Dashboard**, **Visualize Library**, and **Canvas**. diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md b/deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md index 6951e79e6b..f656c83fad 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md @@ -170,5 +170,3 @@ This example uses the role management API, but a similar configuration can be se ``` The `authentication_realm` and `lookup_realm` in the response both specify the `native` realm because both the `admin_user` and `analyst_user` are from that realm. If the two users are in different realms, the values for `authentication_realm` and `lookup_realm` are different (such as `pki` and `native`). - - diff --git a/reference/security/elastic-defend/endpoint-management-req.md b/reference/security/elastic-defend/endpoint-management-req.md index a89736e1fe..d4a43ad8ba 100644 --- a/reference/security/elastic-defend/endpoint-management-req.md +++ b/reference/security/elastic-defend/endpoint-management-req.md @@ -7,7 +7,7 @@ mapped_pages: You can create user roles and define privileges to manage feature access in {{elastic-sec}}. This allows you to use the principle of least privilege while managing access to {{elastic-defend}}'s features. -To configure roles and privileges, find **Roles** in the navigation menu or by using the [global search field](/get-started/the-stack.md#kibana-navigation-search). For more details on using this UI, refer to [{{kib}} privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md#adding_kibana_privileges). +To configure roles and privileges, find **Roles** in the navigation menu or by using the [global search field](/get-started/the-stack.md#kibana-navigation-search). For more details on using this UI, refer to [](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-role-management.md). ::::{note} {{elastic-defend}}'s feature privileges must be assigned to **All Spaces**. You can’t assign them to an individual space. diff --git a/solutions/security/configure-elastic-defend/elastic-defend-feature-privileges.md b/solutions/security/configure-elastic-defend/elastic-defend-feature-privileges.md index 12976fd847..d2469832b2 100644 --- a/solutions/security/configure-elastic-defend/elastic-defend-feature-privileges.md +++ b/solutions/security/configure-elastic-defend/elastic-defend-feature-privileges.md @@ -15,7 +15,7 @@ mapped_urls: You can create user roles and define privileges to manage feature access in {{elastic-sec}}. This allows you to use the principle of least privilege while managing access to {{elastic-defend}}'s features. -To configure roles and privileges, find **Roles** in the navigation menu or by using the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md). For more details on using this UI, refer to [{{kib}} privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md#adding_kibana_privileges). +To configure roles and privileges, find **Roles** in the navigation menu or by using the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md). For more details on using this UI, refer to [](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-role-management.md). ::::{note} {{elastic-defend}}'s feature privileges must be assigned to **All Spaces**. You can’t assign them to an individual space. diff --git a/solutions/security/dashboards/detection-rule-monitoring-dashboard.md b/solutions/security/dashboards/detection-rule-monitoring-dashboard.md index 3121d900ad..7c81f994a9 100644 --- a/solutions/security/dashboards/detection-rule-monitoring-dashboard.md +++ b/solutions/security/dashboards/detection-rule-monitoring-dashboard.md @@ -23,7 +23,7 @@ The Detection rule monitoring dashboard provides visualizations to help you moni ::::{admonition} Requirements To access this dashboard and its data, you must have: -* At least `Read` [{{kib}} privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md#adding_kibana_privileges) for both the **Analytics > Dashboard** and **Security > Security** {{kib}} features. +* At least `Read` [{{kib}} privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-role-management.md) for both the **Analytics > Dashboard** and **Security > Security** {{kib}} features. * At least `read` [index privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md#adding_index_privileges) for the `.kibana-event-log-*` index. :::: diff --git a/solutions/security/endpoint-response-actions/configure-third-party-response-actions.md b/solutions/security/endpoint-response-actions/configure-third-party-response-actions.md index 57a73bcb56..fbc6c6a81c 100644 --- a/solutions/security/endpoint-response-actions/configure-third-party-response-actions.md +++ b/solutions/security/endpoint-response-actions/configure-third-party-response-actions.md @@ -23,7 +23,7 @@ Check out [*Third-party response actions*](/solutions/security/endpoint-response ::::{admonition} Prerequisites * [Subscription level](https://www.elastic.co/pricing): Enterprise -* [{{kib}} feature privilege](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md#adding_kibana_privileges): Under **Actions and Connectors**, turn on **Customize sub-feature privileges** and enable **Endpoint Security**. +* [{{kib}} feature privilege](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-role-management.md): Under **Actions and Connectors**, turn on **Customize sub-feature privileges** and enable **Endpoint Security**. * [{{elastic-sec}} feature privileges](/solutions/security/configure-elastic-defend/elastic-defend-feature-privileges.md): **All** for the response action features, such as **Host Isolation**, that you want to perform. * Endpoints must have actively running third-party agents installed. diff --git a/solutions/security/explore/configure-network-map-data.md b/solutions/security/explore/configure-network-map-data.md index eea6bf6111..a9e931754c 100644 --- a/solutions/security/explore/configure-network-map-data.md +++ b/solutions/security/explore/configure-network-map-data.md @@ -21,7 +21,7 @@ To see source and destination connections lines on the map, you must configure ` ## Permissions required [prereq-perms] -To view the map in {{stack}}, you need a role with at least `Read` [privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md#adding_kibana_privileges) for the `Maps` feature. In serverless, you need the appropriate [predefined user role](/deploy-manage/users-roles/cloud-organization/user-roles.md#general-assign-user-roles) or a [custom role](/deploy-manage/users-roles/cloud-organization/user-roles.md) with at least `Read` privileges for the `Maps` feature. +To view the map in {{stack}}, you need a role with at least `Read` [privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-role-management.md) for the `Maps` feature. In serverless, you need the appropriate [predefined user role](/deploy-manage/users-roles/cloud-organization/user-roles.md#general-assign-user-roles) or a [custom role](/deploy-manage/users-roles/cloud-organization/user-roles.md) with at least `Read` privileges for the `Maps` feature. ## Create {{kib}} data views [kibana-index-pattern] From 0abcb0979c20566f7ee3832f8e094996309ef391 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Wed, 26 Feb 2025 23:17:56 -0500 Subject: [PATCH 09/19] another anchor --- .../users-roles/cluster-or-deployment-auth/defining-roles.md | 1 + 1 file changed, 1 insertion(+) diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md b/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md index 34bf7ded1e..f3c117bf2b 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md @@ -263,6 +263,7 @@ You can manage custom roles using the following methods: When you use the UI or APIs to manage roles, the roles are stored in an internal {{es}} index. When you use local files, the roles are only stored in those files. ### Role management UI [roles-management-ui] +$$$defining_kib_privileges$$$ You can manage users and roles easily in {{kib}}. From 56cc8d4ba34699f553619378f78fe30089f21d7c Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Wed, 26 Feb 2025 23:21:45 -0500 Subject: [PATCH 10/19] oops --- .../users-roles/cluster-or-deployment-auth/defining-roles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md b/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md index f3c117bf2b..a112045bca 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md @@ -263,7 +263,7 @@ You can manage custom roles using the following methods: When you use the UI or APIs to manage roles, the roles are stored in an internal {{es}} index. When you use local files, the roles are only stored in those files. ### Role management UI [roles-management-ui] -$$$defining_kib_privileges$$$ +$$$adding_kibana_privileges$$$ You can manage users and roles easily in {{kib}}. From dff4268bba8417e87b07e41a6c60069d0a9feb42 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Wed, 26 Feb 2025 23:37:47 -0500 Subject: [PATCH 11/19] fixes 2 --- .../_snippets/field-doc-sec-limitations.md | 2 +- deploy-manage/users-roles.md | 4 +- .../cloud-organization/user-roles.md | 2 +- .../built-in-roles.md | 8 +- ...trolling-access-at-document-field-level.md | 2 +- .../cluster-or-deployment-auth/user-roles.md | 4 +- .../users-roles/serverless-custom-roles.md | 2 +- .../Security-production-considerations.md | 2 +- .../kibana/kibana/elasticsearch-mutual-tls.md | 2 +- .../kibana/kibana/xpack-spaces.md | 86 ------------------- raw-migrated-files/toc.yml | 6 -- .../machine-learning-job-rule-requirements.md | 2 +- .../detection-rule-monitoring-dashboard.md | 2 +- 13 files changed, 16 insertions(+), 108 deletions(-) delete mode 100644 raw-migrated-files/kibana/kibana/xpack-spaces.md diff --git a/deploy-manage/_snippets/field-doc-sec-limitations.md b/deploy-manage/_snippets/field-doc-sec-limitations.md index 956a20a27c..46c88d957e 100644 --- a/deploy-manage/_snippets/field-doc-sec-limitations.md +++ b/deploy-manage/_snippets/field-doc-sec-limitations.md @@ -40,5 +40,5 @@ When a user’s role enables document or [field level security](/deploy-manage/u * The request cache is disabled for search requests if either of the following are true: - * The role query that defines document level security is [templated](/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md#templating-role-query) using a [stored script](../../../explore-analyze/scripting/modules-scripting-using.md#script-stored-scripts). + * The role query that defines document level security is [templated](/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md#templating-role-query) using a [stored script](/explore-analyze/scripting/modules-scripting-using.md#script-stored-scripts). * The target indices are a mix of local and remote indices. diff --git a/deploy-manage/users-roles.md b/deploy-manage/users-roles.md index 65c4c88467..fb6bb93c33 100644 --- a/deploy-manage/users-roles.md +++ b/deploy-manage/users-roles.md @@ -40,7 +40,7 @@ If you’re using {{ecloud}}, then you can perform the following tasks to contro * [Invite users to join your organization](/deploy-manage/users-roles/cloud-organization/manage-users.md) * Assign [user roles and privileges](/deploy-manage/users-roles/cloud-organization/user-roles.md): * Manage organization-level roles and high-level access to deployments and projects. - * Assign project-level roles and [create custom roles](/deploy-manage/users-roles/custom-roles.md). ({{serverless-short}} only) + * Assign project-level roles and [create custom roles](/deploy-manage/users-roles/serverless-custom-roles.md). ({{serverless-short}} only) * Configure [SAML single sign-on](/deploy-manage/users-roles/cloud-organization/configure-saml-authentication.md) for your organization ::::{tip} @@ -84,7 +84,7 @@ You can't manage users and roles for {{eck}} clusters at the orchestrator level. As an extension of the [predefined instance access roles](/deploy-manage/users-roles/cloud-organization/user-roles.md#ec_instance_access_roles) offered for {{serverless-short}} projects, you can create custom roles at the project level to provide more granular control, and provide users with only the access they need within specific projects. -[Learn more about custom roles for {{serverless-full}} projects](/deploy-manage/users-roles/custom-roles.md). +[Learn more about custom roles for {{serverless-full}} projects](/deploy-manage/users-roles/serverless-custom-roles.md). ## Cluster or deployment level diff --git a/deploy-manage/users-roles/cloud-organization/user-roles.md b/deploy-manage/users-roles/cloud-organization/user-roles.md index 18bd14ba55..534d3a6009 100644 --- a/deploy-manage/users-roles/cloud-organization/user-roles.md +++ b/deploy-manage/users-roles/cloud-organization/user-roles.md @@ -69,7 +69,7 @@ For {{ech}} deployments, the following predefined roles are available: There are two ways for a user to access {{kib}} instances of an {{ech}} deployment: * [Directly with {{es}} credentials](/deploy-manage/users-roles/cluster-or-deployment-auth.md). In this case, users and their roles are managed directly in {{kib}}. Users in this case don’t need to be members of the {{ecloud}} organization to access the deployment. Note that if you have several deployments, you need to manage users for each of them, individually. -* Through your {{ecloud}} organization. In this case, users who are members of your organization log in to {{ecloud}} and can open the deployments they have access to. Their access level is determined by the roles assigned to them from the **Organization** page. {{ecloud}} roles are mapped to [Stack roles](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md#built-in-roles) on a per-deployment level. When logging in to a specific deployment, users get the stack role that maps to their {{ecloud}} role for that particular deployment. +* Through your {{ecloud}} organization. In this case, users who are members of your organization log in to {{ecloud}} and can open the deployments they have access to. Their access level is determined by the roles assigned to them from the **Organization** page. {{ecloud}} roles are mapped to [{{stack}} roles](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md) on a per-deployment level. When logging in to a specific deployment, users get the stack role that maps to their {{ecloud}} role for that particular deployment. The following table shows the default mapping: diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md b/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md index a5766ec530..92f84a25a5 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md @@ -68,10 +68,10 @@ $$$built-in-roles-ingest-user$$$ `ingest_admin` $$$built-in-roles-kibana-dashboard$$$ `kibana_dashboard_only_user` -: (This role is deprecated, please use [{{kib}} feature privileges](../../../deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md#kibana-feature-privileges) instead). Grants read-only access to the {{kib}} Dashboard in every [space in {{kib}}](../../../deploy-manage/manage-spaces.md). This role does not have access to editing tools in {{kib}}. +: (This role is deprecated, please use [{{kib}} feature privileges](../../../deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md#kibana-feature-privileges) instead). Grants read-only access to the {{kib}} Dashboard in every [space in {{kib}}](/deploy-manage/manage-spaces.md). This role does not have access to editing tools in {{kib}}. $$$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 tokens, and check the availability of the {{es}} cluster. It also permits activating, searching, and retrieving user profiles, as well as updating user profile data for the `kibana-*` namespace. This role grants read access to the `.monitoring-*` indices and read and write access to the `.reporting-*` indices. For more information, see [Configuring Security in {{kib}}](../../../deploy-manage/security.md). +: Grants access necessary for the {{kib}} system user to read from and write to the {{kib}} indices, manage index templates and tokens, and check the availability of the {{es}} cluster. It also permits activating, searching, and retrieving user profiles, as well as updating user profile data for the `kibana-*` namespace. This role grants read access to the `.monitoring-*` indices and read and write access to the `.reporting-*` indices. For more information, see [Configuring Security in {{kib}}](/deploy-manage/security.md). ::::{note} This role should not be assigned to users as the granted permissions may change between releases. @@ -79,10 +79,10 @@ $$$built-in-roles-kibana-system$$$ `kibana_system` $$$built-in-roles-kibana-admin$$$ `kibana_admin` -: Grants access to all {{kib}} features in all spaces. For more information on {{kib}} authorization, see [{{kib}} authorization](../../../deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md). +: Grants access to all {{kib}} features in all spaces. For more information on {{kib}} authorization, see [](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md). $$$built-in-roles-kibana-user$$$ `kibana_user` -: This role is deprecated, please use the [`kibana_admin`](../../../deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md#built-in-roles-kibana-admin) role instead. Grants access to all features in {{kib}}.. +: This role is deprecated, please use the [`kibana_admin`](#built-in-roles-kibana-admin) role instead. Grants access to all features in {{kib}}. $$$built-in-roles-logstash-admin$$$ `logstash_admin` : Grants access to the `.logstash*` indices for managing configurations, and grants necessary access for logstash-specific APIs exposed by the logstash x-pack plugin. diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md b/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md index 0bf238104b..cd8a9f39c3 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md @@ -26,7 +26,7 @@ Document and field level security is currently meant to operate with read-only p A role can define both field and document level permissions on a per-index basis. A role that doesn’t specify field level permissions grants access to ALL fields. Similarly, a role that doesn’t specify document level permissions grants access to ALL documents in the index. -On this page, you'll learn how to implement [document level security](#document-level-security) and [field level security](#field-level-security-field-level-security). +On this page, you'll learn how to implement [document level security](#document-level-security) and [field level security](#field-level-security). You'll also learn the following: * How [multiple roles with document and field level security](#multiple-roles-dls-fls) interact diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles.md b/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles.md index 4f0704a468..6614284a4c 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles.md @@ -75,11 +75,11 @@ The way that you assign roles to users depends on your authentication realm: * [Native realm](/deploy-manage/users-roles/cluster-or-deployment-auth/native.md): * Using {{es}} API [`_security` endpoints](https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-security) - * [In {{kib}}](/deploy-manage/users-roles/cluster-or-deployment-auth/native#managing-native-users), using the **Stack Management > Security > Users** page + * [In {{kib}}](/deploy-manage/users-roles/cluster-or-deployment-auth/native.md#managing-native-users), using the **Stack Management > Security > Users** page * [File realm](/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md): * Using a [`user_roles` file](/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md#k8s-basic) * In ECK: As part of a [basic authentication secret](/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md#k8s-basic) -* [External realms](/deploy-manage/users-roles/cluster-or-deployment-auth/external-authentication): By [mapping users and groups to roles](/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md) +* [External realms](/deploy-manage/users-roles/cluster-or-deployment-auth/external-authentication.md): By [mapping users and groups to roles](/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md) ### Advanced topics diff --git a/deploy-manage/users-roles/serverless-custom-roles.md b/deploy-manage/users-roles/serverless-custom-roles.md index fb021ab73f..d6c9587532 100644 --- a/deploy-manage/users-roles/serverless-custom-roles.md +++ b/deploy-manage/users-roles/serverless-custom-roles.md @@ -73,7 +73,7 @@ Document-level and field-level security affords you even more granularity when i * With field-level security (FLS), you can instruct {{es}} to grant or deny access to specific fields within each document. List these fields in the **Granted fields** field. :::{{tip}} -{{serverless-full}} and {{stack}} both use queries to specify the documents that a role can access. For additional query examples, refer to [Controlling access at the document and field level](/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level#document-level-security). +{{serverless-full}} and {{stack}} both use queries to specify the documents that a role can access. For additional query examples, refer to [Controlling access at the document and field level](/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md#document-level-security). ::: diff --git a/raw-migrated-files/kibana/kibana/Security-production-considerations.md b/raw-migrated-files/kibana/kibana/Security-production-considerations.md index d6c0d3c9f2..def16107eb 100644 --- a/raw-migrated-files/kibana/kibana/Security-production-considerations.md +++ b/raw-migrated-files/kibana/kibana/Security-production-considerations.md @@ -23,7 +23,7 @@ When {{security-features}} are enabled, {{kib}} users have to log in. They must If a user loads a {{kib}} dashboard that accesses data in an index that they are not authorized to view, they get an error that indicates the index does not exist. -For more information on granting access to {{kib}}, see [Granting access to {{kib}}](xpack-security-authorization.md). +For more information on granting access to {{kib}}, see [](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md). ## Use secure HTTP headers [configuring-security-headers] diff --git a/raw-migrated-files/kibana/kibana/elasticsearch-mutual-tls.md b/raw-migrated-files/kibana/kibana/elasticsearch-mutual-tls.md index 0da3e478de..f016151895 100644 --- a/raw-migrated-files/kibana/kibana/elasticsearch-mutual-tls.md +++ b/raw-migrated-files/kibana/kibana/elasticsearch-mutual-tls.md @@ -79,7 +79,7 @@ If you haven’t already, start {{kib}} and connect it to {{es}} using the [enro ![Role mapping for the {{kib}} client certificate](../../../images/kibana-mutual-tls-role-mapping.png "") - For more information, see [role mappings](role-mappings.md). + For more information, see [](deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md). 7. Configure {{kib}} to use the client certificate and private key. diff --git a/raw-migrated-files/kibana/kibana/xpack-spaces.md b/raw-migrated-files/kibana/kibana/xpack-spaces.md deleted file mode 100644 index a01227eae1..0000000000 --- a/raw-migrated-files/kibana/kibana/xpack-spaces.md +++ /dev/null @@ -1,86 +0,0 @@ -# Spaces [xpack-spaces] - -You can define multiple spaces in a single {{kib}} instance from the **Spaces** menu. Each space has its own navigation and saved objects, and users can only access the spaces that they have been granted access to. This access is based on user roles, and a given role can have different permissions per space. - -{{kib}} creates a default space for you. When you create more spaces, users are asked to choose a space when they log in to {{kib}}, and can change their current space at any time from the top menu. - -:::{image} ../../../images/kibana-change-space.png -:alt: Change current space menu -:class: screenshot -::: - -To go to **Spaces***, find ***Stack Management** in the navigation menu or use the [global search bar](/explore-analyze/find-and-organize/find-apps-and-objects.md). - - -## Required privileges [_required_privileges_3] - -The `kibana_admin` role or equivalent is required to manage **Spaces**. - - -## Create a space [spaces-managing] - -$$$spaces-control-feature-visibility$$$ -You can have up to 1,000 spaces by default. The maximum number of spaces can be configured by the `xpack.spaces.maxSpaces` setting (refer to [Spaces settings in {{kib}}](asciidocalypse://docs/kibana/docs/reference/configuration-reference/spaces-settings.md)). - -1. Select **Create space** and provide a name, description, and URL identifier. - - The URL identifier is a short text string that becomes part of the {{kib}} URL when you are inside that space. {{kib}} suggests a URL identifier based on the name of your space, but you can customize the identifier to your liking. You cannot change the space identifier once you create the space. - -2. Select a **Solution view**. This setting controls the navigation that all users of the space will get: - - * **Search**: A light navigation menu focused on analytics and Search use cases. Features specific to Observability and Security are hidden. - * **Observability**: A light navigation menu focused on analytics and Observability use cases. Features specific to Search and Security are hidden. - * **Security**: A light navigation menu focused on analytics and Security use cases. Features specific to Observability and Search are hidden. - * **Classic**: All features from all solutions are visible by default using the classic, multilayered navigation menus. You can customize which features are visible individually. - -3. If you selected the **Classic*** solution view, you can customize the ***Feature visibility** as you need it to be for that space. - - ::::{note} - Even when disabled in this menu, some Management features can remain visible to some users depending on their privileges. Additionally, controlling feature visibility is not a security feature. To secure access to specific features on a per-user basis, you must configure [{{kib}} Security](../../../deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md). - :::: - -4. Customize the avatar of the space to your liking. -5. Save your new space by selecting **Create space**. - -You can edit all of the space settings you just defined at any time, except for the URL identifier. - -{{kib}} also has an [API](https://www.elastic.co/guide/en/kibana/current/spaces-api.html) if you prefer to create spaces programmatically. - - -## Define access to a space [spaces-control-user-access] - -Users can access spaces based on the roles that they have. - -* Certain reserved roles can view and access all spaces by default. You can’t prevent those roles from accessing a space. Instead, you can grant different roles to your users. -* When [creating or editing a role](../../../deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md), you can define which existing spaces that role can access, and with which permissions. -* When editing a space, you can assign roles to the space and define the permissions within the space for these roles. To do that, go to the **Permissions** tab of the space you’re editing. - - When a role is assigned to *All Spaces*, you can’t remove its access from the space settings. You must instead edit the role to give it more granular access to individual spaces. - - - -## Delete a space [_delete_a_space] - -Deleting a space permanently removes the space and all of its contents. Find the space on the **Spaces** overview page and click the trash icon in the Actions column. You can’t delete the default space, but you can customize it to your liking. - - -## Move saved objects between spaces [spaces-moving-objects] - -To move saved objects between spaces, you can [copy objects](/explore-analyze/find-and-organize/saved-objects.md#saved-objects-copy-to-other-spaces), or [export and import objects](/explore-analyze/find-and-organize/saved-objects.md#saved-objects-export). - - -## Configure a space-level landing page [spaces-default-route] - -You can create a custom experience for users by configuring the {{kib}} landing page on a per-space basis. The landing page can route users to a specific dashboard, application, or saved object as they enter each space. - -To configure the landing page, use the default route setting in [Stack Management > {{kib}} > Advanced settings](asciidocalypse://docs/kibana/docs/reference/advanced-settings.md#kibana-general-settings). For example, you might set the default route to `/app/dashboards`. - -:::{image} ../../../images/kibana-spaces-configure-landing-page.png -:alt: Configure space-level landing page -:class: screenshot -::: - - -## Disable spaces [spaces-delete-started] - -Since {{kib}} 8.0, the Spaces feature cannot be disabled. diff --git a/raw-migrated-files/toc.yml b/raw-migrated-files/toc.yml index 983416345f..9c11ccc69c 100644 --- a/raw-migrated-files/toc.yml +++ b/raw-migrated-files/toc.yml @@ -20,7 +20,6 @@ toc: - file: cloud-on-k8s/cloud-on-k8s/k8s-securing-stack.md - file: cloud-on-k8s/cloud-on-k8s/k8s-tls-certificates.md - file: cloud-on-k8s/cloud-on-k8s/k8s-upgrading-stack.md - - file: cloud-on-k8s/cloud-on-k8s/k8s-users-and-roles.md - file: cloud/cloud-enterprise/index.md children: - file: cloud/cloud-enterprise/ece_re_running_the_ece_upgrade.md @@ -280,7 +279,6 @@ toc: - file: elasticsearch/elasticsearch-reference/autoscaling-reactive-storage-decider.md - file: elasticsearch/elasticsearch-reference/bootstrap-checks-xpack.md - file: elasticsearch/elasticsearch-reference/bootstrap-checks.md - - file: elasticsearch/elasticsearch-reference/built-in-roles.md - file: elasticsearch/elasticsearch-reference/change-passwords-native-users.md - file: elasticsearch/elasticsearch-reference/configuring-stack-security.md - file: elasticsearch/elasticsearch-reference/data-management.md @@ -297,12 +295,10 @@ toc: - file: elasticsearch/elasticsearch-reference/index-modules-mapper.md - file: elasticsearch/elasticsearch-reference/install-elasticsearch.md - file: elasticsearch/elasticsearch-reference/ip-filtering.md - - file: elasticsearch/elasticsearch-reference/mapping-roles.md - file: elasticsearch/elasticsearch-reference/monitor-elasticsearch-cluster.md - file: elasticsearch/elasticsearch-reference/monitoring-overview.md - file: elasticsearch/elasticsearch-reference/monitoring-production.md - file: elasticsearch/elasticsearch-reference/recovery-prioritization.md - - file: elasticsearch/elasticsearch-reference/role-mapping-resources.md - file: elasticsearch/elasticsearch-reference/scalability.md - file: elasticsearch/elasticsearch-reference/search-analyze.md - file: elasticsearch/elasticsearch-reference/search-with-synonyms.md @@ -338,7 +334,6 @@ toc: - file: kibana/kibana/logging-settings.md - file: kibana/kibana/management.md - file: kibana/kibana/reporting-production-considerations.md - - file: kibana/kibana/role-mappings.md - file: kibana/kibana/search-ai-assistant.md - file: kibana/kibana/secure-reporting.md - file: kibana/kibana/secure-settings.md @@ -349,7 +344,6 @@ toc: - file: kibana/kibana/upgrade-migrations-rolling-back.md - file: kibana/kibana/upgrade.md - file: kibana/kibana/using-kibana-with-security.md - - file: kibana/kibana/xpack-security-authorization.md - file: kibana/kibana/xpack-security-fips-140-2.md - file: kibana/kibana/xpack-security.md - file: kibana/kibana/xpack-spaces.md diff --git a/solutions/security/advanced-entity-analytics/machine-learning-job-rule-requirements.md b/solutions/security/advanced-entity-analytics/machine-learning-job-rule-requirements.md index 57825d0fed..5316b78686 100644 --- a/solutions/security/advanced-entity-analytics/machine-learning-job-rule-requirements.md +++ b/solutions/security/advanced-entity-analytics/machine-learning-job-rule-requirements.md @@ -12,7 +12,7 @@ To run and create {{ml}} jobs and rules in serverless, you need the appropriate * There must be at least one {{ml}} node in your cluster * The `machine_learning_admin` user role -Additionally, to configure [alert suppression](/solutions/security/detect-and-alert/suppress-detection-alerts.md) for {{ml}} rules, your role needs the following [index privilege](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md#adding_index_privileges): +Additionally, to configure [alert suppression](/solutions/security/detect-and-alert/suppress-detection-alerts.md) for {{ml}} rules, your role needs the following [index privilege](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-role-management.md#adding_index_privileges): * `read` permission for the `.ml-anomalies-*` index diff --git a/solutions/security/dashboards/detection-rule-monitoring-dashboard.md b/solutions/security/dashboards/detection-rule-monitoring-dashboard.md index 7c81f994a9..666fc719e0 100644 --- a/solutions/security/dashboards/detection-rule-monitoring-dashboard.md +++ b/solutions/security/dashboards/detection-rule-monitoring-dashboard.md @@ -24,7 +24,7 @@ The Detection rule monitoring dashboard provides visualizations to help you moni To access this dashboard and its data, you must have: * At least `Read` [{{kib}} privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-role-management.md) for both the **Analytics > Dashboard** and **Security > Security** {{kib}} features. -* At least `read` [index privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md#adding_index_privileges) for the `.kibana-event-log-*` index. +* At least `read` [index privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-role-management.md#adding_index_privileges) for the `.kibana-event-log-*` index. :::: From 427004f359a5703d23a8f0e3b2ce42fa9aa21ea7 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Wed, 26 Feb 2025 23:44:10 -0500 Subject: [PATCH 12/19] cleanup --- raw-migrated-files/kibana/kibana/elasticsearch-mutual-tls.md | 2 +- raw-migrated-files/toc.yml | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/raw-migrated-files/kibana/kibana/elasticsearch-mutual-tls.md b/raw-migrated-files/kibana/kibana/elasticsearch-mutual-tls.md index f016151895..3a476d98b7 100644 --- a/raw-migrated-files/kibana/kibana/elasticsearch-mutual-tls.md +++ b/raw-migrated-files/kibana/kibana/elasticsearch-mutual-tls.md @@ -79,7 +79,7 @@ If you haven’t already, start {{kib}} and connect it to {{es}} using the [enro ![Role mapping for the {{kib}} client certificate](../../../images/kibana-mutual-tls-role-mapping.png "") - For more information, see [](deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md). + For more information, see [](/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md). 7. Configure {{kib}} to use the client certificate and private key. diff --git a/raw-migrated-files/toc.yml b/raw-migrated-files/toc.yml index 9c11ccc69c..e01f32a780 100644 --- a/raw-migrated-files/toc.yml +++ b/raw-migrated-files/toc.yml @@ -346,7 +346,6 @@ toc: - file: kibana/kibana/using-kibana-with-security.md - file: kibana/kibana/xpack-security-fips-140-2.md - file: kibana/kibana/xpack-security.md - - file: kibana/kibana/xpack-spaces.md - file: logstash/logstash/index.md children: - file: logstash/logstash/health-report-pipeline-flow-worker-utilization.md From aaf65dee7670da4bc1fca0dc47ab11af55404660 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Thu, 27 Feb 2025 22:15:59 -0500 Subject: [PATCH 13/19] edu structure suggestion --- .../api-keys/serverless-project-api-keys.md | 2 +- deploy-manage/security/secure-endpoints.md | 2 +- deploy-manage/toc.yml | 1 + .../snapshot-and-restore/create-snapshots.md | 6 +- .../snapshot-and-restore/restore-snapshot.md | 4 +- .../snapshot-and-restore/self-managed.md | 4 +- .../defining-roles.md | 231 +----------------- ...ing-privileges-for-data-streams-aliases.md | 4 +- .../kibana-role-management.md | 6 +- .../role-structure.md | 225 +++++++++++++++++ ...tting-requests-on-behalf-of-other-users.md | 2 +- .../cluster-or-deployment-auth/user-roles.md | 4 +- .../users-roles/serverless-custom-roles.md | 4 +- 13 files changed, 251 insertions(+), 244 deletions(-) create mode 100644 deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md diff --git a/deploy-manage/api-keys/serverless-project-api-keys.md b/deploy-manage/api-keys/serverless-project-api-keys.md index 4aa1b64d9e..1808fecf24 100644 --- a/deploy-manage/api-keys/serverless-project-api-keys.md +++ b/deploy-manage/api-keys/serverless-project-api-keys.md @@ -70,7 +70,7 @@ For example, the following `role_descriptors` object defines a `books-read-only` } ``` -For the `role_descriptors` object schema, check out the [`/_security/api_key` endpoint](https://www.elastic.co/docs/api/doc/elasticsearch-serverless/operation/operation-security-create-api-key) docs. For supported privileges, check [Security privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md#privileges-list-indices). +For the `role_descriptors` object schema, check out the [`/_security/api_key` endpoint](https://www.elastic.co/docs/api/doc/elasticsearch-serverless/operation/operation-security-create-api-key) docs. For supported privileges, check [Security privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-indices). ## Update an API key [api-keys-update-an-api-key] diff --git a/deploy-manage/security/secure-endpoints.md b/deploy-manage/security/secure-endpoints.md index 54e8ef20eb..b8171bc14b 100644 --- a/deploy-manage/security/secure-endpoints.md +++ b/deploy-manage/security/secure-endpoints.md @@ -27,5 +27,5 @@ While you absolutely shouldn’t expose {{es}} directly to the internet, you als ## Implement role based access control [security-create-appropriate-users] -[Define roles](../users-roles/cluster-or-deployment-auth/defining-roles.md) for your users and [assign appropriate privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md) to ensure that users have access only to the resources that they need. This process determines whether the user behind an incoming request is allowed to run that request. +[Define roles](../users-roles/cluster-or-deployment-auth/defining-roles.md) for your users and [assign appropriate privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md) to ensure that users have access only to the resources that they need. This process determines whether the user behind an incoming request is allowed to run that request. diff --git a/deploy-manage/toc.yml b/deploy-manage/toc.yml index 6576348875..74c577e2e4 100644 --- a/deploy-manage/toc.yml +++ b/deploy-manage/toc.yml @@ -649,6 +649,7 @@ toc: - file: users-roles/cluster-or-deployment-auth/built-in-roles.md - file: users-roles/cluster-or-deployment-auth/defining-roles.md children: + - file: users-roles/cluster-or-deployment-auth/role-structure.md - file: users-roles/cluster-or-deployment-auth/granting-privileges-for-data-streams-aliases.md - file: users-roles/cluster-or-deployment-auth/kibana-role-management.md - file: users-roles/cluster-or-deployment-auth/role-restriction.md diff --git a/deploy-manage/tools/snapshot-and-restore/create-snapshots.md b/deploy-manage/tools/snapshot-and-restore/create-snapshots.md index 1cffbf8034..cfe941935b 100644 --- a/deploy-manage/tools/snapshot-and-restore/create-snapshots.md +++ b/deploy-manage/tools/snapshot-and-restore/create-snapshots.md @@ -26,8 +26,8 @@ The guide also provides tips for creating dedicated cluster state snapshots and * To use {{kib}}'s **Snapshot and Restore** feature, you must have the following permissions: - * [Cluster privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md#privileges-list-cluster): `monitor`, `manage_slm`, `cluster:admin/snapshot`, and `cluster:admin/repository` - * [Index privilege](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md#privileges-list-indices): `all` on the `monitor` index + * [Cluster privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-cluster): `monitor`, `manage_slm`, `cluster:admin/snapshot`, and `cluster:admin/repository` + * [Index privilege](/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-indices): `all` on the `monitor` index * You can only take a snapshot from a running cluster with an elected [master node](../../distributed-architecture/clusters-nodes-shards/node-roles.md#master-node-role). * A snapshot repository must be [registered](self-managed.md) and available to the cluster. @@ -59,7 +59,7 @@ Elastic Cloud Hosted deployments automatically include the `cloud-snapshot-polic ### {{slm-init}} security [slm-security] -The following [cluster privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md#privileges-list-cluster) control access to the {{slm-init}} actions when {{es}} {{security-features}} are enabled: +The following [cluster privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-cluster) control access to the {{slm-init}} actions when {{es}} {{security-features}} are enabled: `manage_slm` : Allows a user to perform all {{slm-init}} actions, including creating and updating policies and starting and stopping {{slm-init}}. diff --git a/deploy-manage/tools/snapshot-and-restore/restore-snapshot.md b/deploy-manage/tools/snapshot-and-restore/restore-snapshot.md index 7dbbf0c29d..e306dcf705 100644 --- a/deploy-manage/tools/snapshot-and-restore/restore-snapshot.md +++ b/deploy-manage/tools/snapshot-and-restore/restore-snapshot.md @@ -24,8 +24,8 @@ This guide also provides tips for [restoring to another cluster](#restore-differ ## Prerequisites - To use Kibana’s Snapshot and Restore feature, you must have the following permissions: - - [Cluster privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md#privileges-list-cluster): `monitor`, `manage_slm`, `cluster:admin/snapshot`, and `cluster:admin/repository` - - [Index privilege](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md#privileges-list-indices): `all` on the monitor index + - [Cluster privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-cluster): `monitor`, `manage_slm`, `cluster:admin/snapshot`, and `cluster:admin/repository` + - [Index privilege](/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-indices): `all` on the monitor index - You can only restore a snapshot to a running cluster with an elected [master node](/deploy-manage/distributed-architecture/clusters-nodes-shards/node-roles.md#master-node-role). The snapshot’s repository must be registered and available to the cluster. - The snapshot and cluster versions must be compatible. See [Snapshot compatibility](/deploy-manage/tools/snapshot-and-restore.md#snapshot-compatibility). - To restore a snapshot, the cluster’s global metadata must be writable. Ensure there aren’t any cluster blocks that prevent writes. The restore operation ignores index blocks. diff --git a/deploy-manage/tools/snapshot-and-restore/self-managed.md b/deploy-manage/tools/snapshot-and-restore/self-managed.md index 8fc06f7c7d..3b18273e43 100644 --- a/deploy-manage/tools/snapshot-and-restore/self-managed.md +++ b/deploy-manage/tools/snapshot-and-restore/self-managed.md @@ -20,8 +20,8 @@ In this guide, you’ll learn how to: * To use {{kib}}'s **Snapshot and Restore** feature, you must have the following permissions: - * [Cluster privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md#privileges-list-cluster): `monitor`, `manage_slm`, `cluster:admin/snapshot`, and `cluster:admin/repository` - * [Index privilege](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md#privileges-list-indices): `all` on the `monitor` index + * [Cluster privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-cluster): `monitor`, `manage_slm`, `cluster:admin/snapshot`, and `cluster:admin/repository` + * [Index privilege](/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-indices): `all` on the `monitor` index * To register a snapshot repository, the cluster’s global metadata must be writeable. Ensure there aren’t any [cluster blocks](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/configuration-reference/miscellaneous-cluster-settings.md#cluster-read-only) that prevent write access. diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md b/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md index a112045bca..b3f3601a95 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md @@ -17,9 +17,7 @@ applies_to: If [built-in roles](built-in-roles.md) do not address your use case, then you can create additional custom roles. -In this page, you'll learn about the [data structure of a role](#role-structure), and about the [methods for defining and managing custom roles](#managing-custom-roles). - -The data structure described in [Role structure](#role-structure) must be used when defining a role using the API or in a file. You can also define roles using the Role management UI, which does not require knowledge of a role's data structure. +In this section, you'll learn about the [data structure of a role](#role-structure), and about the [methods for defining and managing custom roles](#managing-custom-roles). You can also implement 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 [](/deploy-manage/users-roles/cluster-or-deployment-auth/authorization-plugins.md). @@ -27,230 +25,13 @@ After you create your custom roles, you can [learn how to assign them to users]( ## Role structure -A role is defined by the following JSON structure: - -```js -{ - "run_as": [ ... ], <1> - "cluster": [ ... ], <2> - "global": { ... }, <3> - "indices": [ ... ], <4> - "applications": [ ... ], <5> - "remote_indices": [ ... ], <6> - "remote_cluster": [ ... ], <7> - "metadata": { ... }, <8> - "description": "..." <9> -} -``` - -1. A list of usernames the owners of this role can [impersonate](/deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md). -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. An object defining global privileges. A global privilege is a form of cluster privilege that is request sensitive. A standard cluster privilege makes authorization decisions based solely on the action being executed. A global privilege also considers the parameters included in the request. Support for global privileges is currently limited to the management of application privileges. This field is optional. -4. A list of indices permissions entries. - - This field is optional (missing `indices` privileges effectively mean no index level permissions). -5. A list of application privilege entries. This field is optional. -6. A list of indices permissions entries for [remote clusters configured with the API key based model](/deploy-manage/remote-clusters/remote-clusters-api-key.md). - - This field is optional (missing `remote_indices` privileges effectively mean no index level permissions for any API key based remote clusters). -7. A list of cluster permissions entries for [remote clusters configured with the API key based model](/deploy-manage/remote-clusters/remote-clusters-api-key.md). - - This field is optional (missing `remote_cluster` privileges effectively means no additional cluster permissions for any API key based remote clusters). -8. Metadata field associated with the role, such as `metadata.app_tag`. Metadata is internally indexed as a [flattened](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/mapping-reference/flattened.md) field type. This means that all sub-fields act like `keyword` fields when querying and sorting. Metadata values can be simple values, but also lists and maps. This field is optional. -9. A string value with the description text of the role. The maximum length of it is `1000` chars. The field is internally indexed as a [text](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/mapping-reference/text.md#text-field-type) field type (with default values for all parameters). This field is optional. - - -::::{note} -:name: valid-role-name - -Role names must be at least 1 and no more than 507 characters. They can contain alphanumeric characters (`a-z`, `A-Z`, `0-9`), spaces, punctuation, and printable symbols in the [Basic Latin (ASCII) block](https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)). Leading or trailing whitespace is not allowed. -:::: - - -### Indices privileges [roles-indices-priv] - -The following describes the structure of an indices permissions entry: - -```js -{ - "names": [ ... ], <1> - "privileges": [ ... ], <2> - "field_security" : { ... }, <3> - "query": "...", <4> - "allow_restricted_indices": false <5> -} -``` - -1. A list of data streams, indices, and aliases to which the permissions in this entry apply. Supports wildcards (`*`). -2. The index level privileges the owners of the role have on the associated data streams and indices specified in the `names` argument. -3. Specification for document fields the owners of the role have read access to. See [Setting up field and document level security](/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md) for details. -4. A search query that defines the documents the owners of the role have read access to. A document within the associated data streams and indices must match this query in order for it to be accessible by the owners of the role. -5. Restricted indices are a special category of indices that are used internally to store configuration data and should not be directly accessed. Only internal system roles should normally grant privileges over the restricted indices. **Toggling this flag is very strongly discouraged because it could effectively grant unrestricted operations on critical data, making the entire system unstable or leaking sensitive information.** If however, for administrative purposes, you need to create a role with privileges covering restricted indices, you must set this field to `true` (default is `false`), and then the `names` field will cover the restricted indices as well. - - -::::{admonition} Using wildcards and regex -The `names` parameter accepts wildcard and regular expressions that may refer to multiple data streams, indices, and aliases. - -* 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. - -```js -"foo-bar": <1> -"foo-*": <2> -"logstash-201?-*": <3> -"/.*-201[0-9]-.*/": <4> -"/foo": <5> -``` -1. Match the literal `foo-bar` -2. Match anything beginning with "foo-" -3. `?` matches any one character -4. Use a regex to match anything containing 2010-2019 -5. syntax error - missing final `/` -:::: - - - - - - -### Global privileges [roles-global-priv] - -The following describes the structure of the global privileges entry: - -```js -{ - "application": { - "manage": { <1> - "applications": [ ... ] <2> - } - }, - "profile": { - "write": { <3> - "applications": [ ... ] <4> - } - } -} -``` - -1. The privilege for the ability to manage application privileges -2. The list of application names that may be managed. This list supports wildcards (e.g. `"myapp-*"`) and regular expressions (e.g. `"/app[0-9]*/"`) -3. The privilege for the ability to write the `access` and `data` of any user profile -4. The list of names, wildcards and regular expressions to which the write privilege is restricted to - - - -### Application privileges [roles-application-priv] - -The following describes the structure of an application privileges entry: - -```js -{ - "application": "my_app", <1> - "privileges": [ ... ], <2> - "resources": [ ... ] <3> -} -``` - -1. The name of the application. -2. The list of the names of the application privileges to grant to this role. -3. The resources to which those privileges apply. These are handled in the same way as index name pattern in `indices` permissions. These resources do not have any special meaning to the {{es}} {{security-features}}. - +Custom roles follow a strict data structure. If you're working with custom roles using the role management API or role files, then you need to understand and follow the structure when parsing role information or making changes. -For details about the validation rules for these fields, see the [add application privileges API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-put-privileges). - -A role may refer to application privileges that do not exist - that is, they have not yet been defined through the add application privileges API (or they were defined, but have since been deleted). In this case, the privilege has no effect, and will not grant any actions in the [has privileges API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-has-privileges). - - -### Remote indices privileges [roles-remote-indices-priv] - -For [remote clusters configured with the API key based model](/deploy-manage/remote-clusters/remote-clusters-api-key.md), remote indices privileges can be used to specify desired indices privileges for matching remote clusters. The final effective index privileges will be an intersection of the remote indices privileges and the [cross-cluster API key](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-cross-cluster-api-key)'s indices privileges. - -::::{note} -Remote indices are effective for remote clusters configured with the API key based model. They have no effect for remote clusters configured with the certificate based model. -:::: - - -The remote indices privileges entry has an extra mandatory `clusters` field compared to an [indices privileges entry](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md#roles-indices-priv). Otherwise the two have identical structure. The following describes the structure of a remote indices permissions entry: - -```js -{ - "clusters": [ ... ], <1> - "names": [ ... ], <2> - "privileges": [ ... ], <3> - "field_security" : { ... }, <4> - "query": "...", <5> - "allow_restricted_indices": false <6> -} -``` - -1. A list of remote cluster aliases. It supports literal strings as well as [wildcards](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/rest-apis/api-conventions.md#api-multi-index) and [regular expressions](asciidocalypse://docs/elasticsearch/docs/reference/query-languages/regexp-syntax.md). This field is required. -2. A list of data streams, indices, and aliases to which the permissions in this entry apply. Supports wildcards (`*`). -3. The index level privileges the owners of the role have on the associated data streams and indices specified in the `names` argument. -4. Specification for document fields the owners of the role have read access to. See [Setting up field and document level security](/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md) for details. -5. A search query that defines the documents the owners of the role have read access to. A document within the associated data streams and indices must match this query in order for it to be accessible by the owners of the role. -6. Restricted indices are a special category of indices that are used internally to store configuration data and should not be directly accessed. Only internal system roles should normally grant privileges over the restricted indices. **Toggling this flag is very strongly discouraged because it could effectively grant unrestricted operations on critical data, making the entire system unstable or leaking sensitive information.** If however, for administrative purposes, you need to create a role with privileges covering restricted indices, you must set this field to `true` (default is `false`), and then the `names` field will cover the restricted indices as well. - - - -### Remote cluster privileges [roles-remote-cluster-priv] - -For [remote clusters configured with the API key based model](/deploy-manage/remote-clusters/remote-clusters-api-key.md), remote cluster privileges can be used to specify additional cluster privileges for matching remote clusters. - -::::{note} -Remote cluster privileges are only effective for remote clusters configured with the API key based model. They have no effect on remote clusters configured with the certificate based model. -:::: - - -The following describes the structure of a remote cluster permissions entry: - -```js -{ - "clusters": [ ... ], <1> - "privileges": [ ... ] <2> -} -``` - -1. A list of remote cluster aliases. It supports literal strings as well as [wildcards](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/rest-apis/api-conventions.md#api-multi-index) and [regular expressions](asciidocalypse://docs/elasticsearch/docs/reference/query-languages/regexp-syntax.md). This field is required. -2. The cluster level privileges for the remote cluster. The allowed values here are a subset of the [cluster privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md#privileges-list-cluster). The [builtin privileges API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-get-builtin-privileges) can be used to determine which privileges are allowed here. This field is required. - - - -### Example [_example_9] - -The following snippet shows an example definition of a `clicks_admin` role: - -```console -POST /_security/role/clicks_admin -{ - "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} -View a complete list of available [cluster and indices privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md). -:::: +[Learn about the data structure of a role and its entries](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md). +:::{{note}} +You don't need to use this structure when interacting with roles using the role management UI. +::: ## Managing custom roles diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/granting-privileges-for-data-streams-aliases.md b/deploy-manage/users-roles/cluster-or-deployment-auth/granting-privileges-for-data-streams-aliases.md index 3bdc5e8a4e..34c79bb25b 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/granting-privileges-for-data-streams-aliases.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/granting-privileges-for-data-streams-aliases.md @@ -15,7 +15,7 @@ applies_to: ## Data stream privileges [data-stream-privileges] -Use [index privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md#privileges-list-indices) to control access to a data stream. Granting privileges on a data stream grants the same privileges on its backing indices. +Use [index privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-indices) to control access to a data stream. Granting privileges on a data stream grants the same privileges on its backing indices. For example, `my-data-stream` consists of two backing indices: `.ds-my-data-stream-2099.03.07-000001` and `.ds-my-data-stream-2099.03.08-000002`. @@ -43,7 +43,7 @@ GET .ds-my-data-stream-2099.03.09-000003/_doc/2 ## Alias privileges [index-alias-privileges] -Use [index privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md#privileges-list-indices) to control access to an [alias](../../../manage-data/data-store/aliases.md). Privileges on an index or data stream do not grant privileges on its aliases. For information about managing aliases, see [*Aliases*](../../../manage-data/data-store/aliases.md). +Use [index privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-indices) to control access to an [alias](../../../manage-data/data-store/aliases.md). Privileges on an index or data stream do not grant privileges on its aliases. For information about managing aliases, see [*Aliases*](../../../manage-data/data-store/aliases.md). ::::{important} Don’t use [filtered aliases](../../../manage-data/data-store/aliases.md#filter-alias) in place of [document level security](controlling-access-at-document-field-level.md). {{es}} doesn’t always apply alias filters. diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-role-management.md b/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-role-management.md index 794cd4875c..411ea7a22d 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-role-management.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-role-management.md @@ -18,19 +18,19 @@ To create a role, open the menu, then click **Stack Management > Roles** and cli ## Required permissions [_required_permissions_7] -The `manage_security` [cluster privilege](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md#privileges-list-cluster) is required to access role management. +The `manage_security` [cluster privilege](/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-cluster) is required to access role management. ## Cluster privileges [adding_cluster_privileges] Cluster privileges grant access to monitoring and management features in {{es}}. They also enable [Stack Management](/deploy-manage/index.md) capabilities in {{kib}}. -Refer to [cluster privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md#privileges-list-cluster) for a complete description of available options. +Refer to [cluster privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-cluster) for a complete description of available options. ## Index privileges [adding_index_privileges] Each role can grant access to multiple data indices, and each index can have a different set of privileges. We recommend granting the `read` and `view_index_metadata` privileges to each index that you expect your users to work with in {{kib}}. -Refer to [index privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md#privileges-list-indices) for a complete description of available options. +Refer to [index privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-indices) for a complete description of available options. Document-level and field-level security affords you even more granularity when it comes to granting access to your data. With document-level security (DLS), you can write an {{es}} query to describe which documents this role grants access to. With field-level security (FLS), you can instruct {{es}} to grant or deny access to specific fields within each document. diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md b/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md new file mode 100644 index 0000000000..11a0553b53 --- /dev/null +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md @@ -0,0 +1,225 @@ +--- +applies_to: + deployment: + ece: + ess: + eck: + self: +--- + +# Role structure + +A role is defined by the following JSON structure: + +```js +{ + "run_as": [ ... ], <1> + "cluster": [ ... ], <2> + "global": { ... }, <3> + "indices": [ ... ], <4> + "applications": [ ... ], <5> + "remote_indices": [ ... ], <6> + "remote_cluster": [ ... ], <7> + "metadata": { ... }, <8> + "description": "..." <9> +} +``` + +1. A list of usernames the owners of this role can [impersonate](/deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md). +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. An object defining global privileges. A global privilege is a form of cluster privilege that is request sensitive. A standard cluster privilege makes authorization decisions based solely on the action being executed. A global privilege also considers the parameters included in the request. Support for global privileges is currently limited to the management of application privileges. This field is optional. +4. A list of indices permissions entries. + + This field is optional (missing `indices` privileges effectively mean no index level permissions). +5. A list of application privilege entries. This field is optional. +6. A list of indices permissions entries for [remote clusters configured with the API key based model](/deploy-manage/remote-clusters/remote-clusters-api-key.md). + + This field is optional (missing `remote_indices` privileges effectively mean no index level permissions for any API key based remote clusters). +7. A list of cluster permissions entries for [remote clusters configured with the API key based model](/deploy-manage/remote-clusters/remote-clusters-api-key.md). + + This field is optional (missing `remote_cluster` privileges effectively means no additional cluster permissions for any API key based remote clusters). +8. Metadata field associated with the role, such as `metadata.app_tag`. Metadata is internally indexed as a [flattened](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/mapping-reference/flattened.md) field type. This means that all sub-fields act like `keyword` fields when querying and sorting. Metadata values can be simple values, but also lists and maps. This field is optional. +9. A string value with the description text of the role. The maximum length of it is `1000` chars. The field is internally indexed as a [text](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/mapping-reference/text.md#text-field-type) field type (with default values for all parameters). This field is optional. + + +::::{note} +:name: valid-role-name + +Role names must be at least 1 and no more than 507 characters. They can contain alphanumeric characters (`a-z`, `A-Z`, `0-9`), spaces, punctuation, and printable symbols in the [Basic Latin (ASCII) block](https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)). Leading or trailing whitespace is not allowed. +:::: + + +## Indices privileges [roles-indices-priv] + +The following describes the structure of an indices permissions entry: + +```js +{ + "names": [ ... ], <1> + "privileges": [ ... ], <2> + "field_security" : { ... }, <3> + "query": "...", <4> + "allow_restricted_indices": false <5> +} +``` + +1. A list of data streams, indices, and aliases to which the permissions in this entry apply. Supports wildcards (`*`). +2. The index level privileges the owners of the role have on the associated data streams and indices specified in the `names` argument. +3. Specification for document fields the owners of the role have read access to. See [Setting up field and document level security](/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md) for details. +4. A search query that defines the documents the owners of the role have read access to. A document within the associated data streams and indices must match this query in order for it to be accessible by the owners of the role. +5. Restricted indices are a special category of indices that are used internally to store configuration data and should not be directly accessed. Only internal system roles should normally grant privileges over the restricted indices. **Toggling this flag is very strongly discouraged because it could effectively grant unrestricted operations on critical data, making the entire system unstable or leaking sensitive information.** If however, for administrative purposes, you need to create a role with privileges covering restricted indices, you must set this field to `true` (default is `false`), and then the `names` field will cover the restricted indices as well. + + +::::{admonition} Using wildcards and regex +The `names` parameter accepts wildcard and regular expressions that may refer to multiple data streams, indices, and aliases. + +* 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. + +```js +"foo-bar": <1> +"foo-*": <2> +"logstash-201?-*": <3> +"/.*-201[0-9]-.*/": <4> +"/foo": <5> +``` +1. Match the literal `foo-bar` +2. Match anything beginning with "foo-" +3. `?` matches any one character +4. Use a regex to match anything containing 2010-2019 +5. syntax error - missing final `/` +:::: + + +## Global privileges [roles-global-priv] + +The following describes the structure of the global privileges entry: + +```js +{ + "application": { + "manage": { <1> + "applications": [ ... ] <2> + } + }, + "profile": { + "write": { <3> + "applications": [ ... ] <4> + } + } +} +``` + +1. The privilege for the ability to manage application privileges +2. The list of application names that may be managed. This list supports wildcards (e.g. `"myapp-*"`) and regular expressions (e.g. `"/app[0-9]*/"`) +3. The privilege for the ability to write the `access` and `data` of any user profile +4. The list of names, wildcards and regular expressions to which the write privilege is restricted to + +## Application privileges [roles-application-priv] + +The following describes the structure of an application privileges entry: + +```js +{ + "application": "my_app", <1> + "privileges": [ ... ], <2> + "resources": [ ... ] <3> +} +``` + +1. The name of the application. +2. The list of the names of the application privileges to grant to this role. +3. The resources to which those privileges apply. These are handled in the same way as index name pattern in `indices` permissions. These resources do not have any special meaning to the {{es}} {{security-features}}. + +For details about the validation rules for these fields, see the [add application privileges API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-put-privileges). + +A role may refer to application privileges that do not exist - that is, they have not yet been defined through the add application privileges API (or they were defined, but have since been deleted). In this case, the privilege has no effect, and will not grant any actions in the [has privileges API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-has-privileges). + + +## Remote indices privileges [roles-remote-indices-priv] + +For [remote clusters configured with the API key based model](/deploy-manage/remote-clusters/remote-clusters-api-key.md), remote indices privileges can be used to specify desired indices privileges for matching remote clusters. The final effective index privileges will be an intersection of the remote indices privileges and the [cross-cluster API key](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-cross-cluster-api-key)'s indices privileges. + +::::{note} +Remote indices are effective for remote clusters configured with the API key based model. They have no effect for remote clusters configured with the certificate based model. +:::: + + +The remote indices privileges entry has an extra mandatory `clusters` field compared to an [indices privileges entry](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md#roles-indices-priv). Otherwise the two have identical structure. The following describes the structure of a remote indices permissions entry: + +```js +{ + "clusters": [ ... ], <1> + "names": [ ... ], <2> + "privileges": [ ... ], <3> + "field_security" : { ... }, <4> + "query": "...", <5> + "allow_restricted_indices": false <6> +} +``` + +1. A list of remote cluster aliases. It supports literal strings as well as [wildcards](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/rest-apis/api-conventions.md#api-multi-index) and [regular expressions](asciidocalypse://docs/elasticsearch/docs/reference/query-languages/regexp-syntax.md). This field is required. +2. A list of data streams, indices, and aliases to which the permissions in this entry apply. Supports wildcards (`*`). +3. The index level privileges the owners of the role have on the associated data streams and indices specified in the `names` argument. +4. Specification for document fields the owners of the role have read access to. See [Setting up field and document level security](/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md) for details. +5. A search query that defines the documents the owners of the role have read access to. A document within the associated data streams and indices must match this query in order for it to be accessible by the owners of the role. +6. Restricted indices are a special category of indices that are used internally to store configuration data and should not be directly accessed. Only internal system roles should normally grant privileges over the restricted indices. **Toggling this flag is very strongly discouraged because it could effectively grant unrestricted operations on critical data, making the entire system unstable or leaking sensitive information.** If however, for administrative purposes, you need to create a role with privileges covering restricted indices, you must set this field to `true` (default is `false`), and then the `names` field will cover the restricted indices as well. + + +## Remote cluster privileges [roles-remote-cluster-priv] + +For [remote clusters configured with the API key based model](/deploy-manage/remote-clusters/remote-clusters-api-key.md), remote cluster privileges can be used to specify additional cluster privileges for matching remote clusters. + +::::{note} +Remote cluster privileges are only effective for remote clusters configured with the API key based model. They have no effect on remote clusters configured with the certificate based model. +:::: + + +The following describes the structure of a remote cluster permissions entry: + +```js +{ + "clusters": [ ... ], <1> + "privileges": [ ... ] <2> +} +``` + +1. A list of remote cluster aliases. It supports literal strings as well as [wildcards](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/rest-apis/api-conventions.md#api-multi-index) and [regular expressions](asciidocalypse://docs/elasticsearch/docs/reference/query-languages/regexp-syntax.md). This field is required. +2. The cluster level privileges for the remote cluster. The allowed values here are a subset of the [cluster privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-cluster). The [builtin privileges API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-get-builtin-privileges) can be used to determine which privileges are allowed here. This field is required. + + +## Example [_example_9] + +The following snippet shows an example definition of a `clicks_admin` role: + +```console +POST /_security/role/clicks_admin +{ + "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} +View a complete list of available [cluster and indices privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md). +:::: \ No newline at end of file diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md b/deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md index f656c83fad..b9c8339df9 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md @@ -75,7 +75,7 @@ Consider an admin role and an analyst role. The admin role has higher privileges This example uses the role management API, but a similar configuration can be set up using the [Create users](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-role-management.md) and [Users](/deploy-manage/users-roles/cluster-or-deployment-auth/native.md#managing-native-users) pages in {{kib}}. -1. Create an admin role named `my_admin_role`. This role has `manage` [privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md) on the entire cluster, and on a subset of indices. This role also contains the `run_as` privilege, which enables any user with this role to submit requests on behalf of the specified `analyst_user`. +1. Create an admin role named `my_admin_role`. This role has `manage` [privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md) on the entire cluster, and on a subset of indices. This role also contains the `run_as` privilege, which enables any user with this role to submit requests on behalf of the specified `analyst_user`. You can set up a similar role using the [role management UI](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-role-management.md) in {{kib}} by selecting an `analyst_user` from the **Run As privileges** dropdown menu in the **Elasticsearch** section. diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles.md b/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles.md index 6614284a4c..bb6ca111d4 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles.md @@ -37,7 +37,7 @@ The authorization process revolves around the following constructs: : A resource to which access is restricted. Indices, aliases, documents, fields, users, and the {{es}} cluster itself are all examples of secured objects. *Privilege* -: A named group of one or more actions that a user may execute against a secured resource. Each secured resource has its own sets of available privileges. For example, `read` is an index privilege that represents all actions that enable reading the indexed/stored data. For a complete list of available privileges, see [Elasticsearch privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md). +: A named group of one or more actions that a user may execute against a secured resource. Each secured resource has its own sets of available privileges. For example, `read` is an index privilege that represents all actions that enable reading the indexed/stored data. For a complete list of available privileges, see [Elasticsearch privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md). *Permissions* : A set of one or more privileges against a secured resource. Permissions can easily be described in words, here are few examples: @@ -66,7 +66,7 @@ Review these topics to learn how to configure RBAC in your cluster or deployment * Learn about [built-in roles](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md) * [Define your own roles](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md) -* Learn about the [Elasticsearch](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md) and [Kibana](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md) privileges you can assign to roles +* Learn about the [Elasticsearch](/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md) and [Kibana](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md) privileges you can assign to roles * Learn how to [control access at the document and field level](/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md) ### Assign roles to users diff --git a/deploy-manage/users-roles/serverless-custom-roles.md b/deploy-manage/users-roles/serverless-custom-roles.md index d6c9587532..45e45dbb37 100644 --- a/deploy-manage/users-roles/serverless-custom-roles.md +++ b/deploy-manage/users-roles/serverless-custom-roles.md @@ -20,7 +20,7 @@ Roles are a collection of privileges that enable users to access project feature On this page, you'll learn about how to [manage custom roles in your project](#manage-custom-roles), the types of privileges you can assign, and how to [assign the roles](#assign-custom-roles) that you create. ::::{note} -You cannot assign [run as privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md#_run_as_privilege) in {{serverless-full}} custom roles. +You cannot assign [run as privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#_run_as_privilege) in {{serverless-full}} custom roles. :::: :::{{admonition}} Custom roles in {{stack}} @@ -42,7 +42,7 @@ Cluster privileges grant access to monitoring and management features in {{es}}. :class: screenshot ::: -Refer to [cluster privileges](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/security-privileges.md#privileges-list-cluster) for a complete description of available options. +Refer to [cluster privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-cluster) for a complete description of available options. ## {{es}} index privileges [custom-roles-es-index-privileges] From c720a2e8ab00a5301d65d83b51da10ff59d70e08 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Thu, 27 Feb 2025 22:25:17 -0500 Subject: [PATCH 14/19] fixy breakies --- deploy-manage/remote-clusters/ec-remote-cluster-ece.md | 2 +- deploy-manage/remote-clusters/ec-remote-cluster-other-ess.md | 2 +- deploy-manage/remote-clusters/ec-remote-cluster-same-ess.md | 2 +- deploy-manage/remote-clusters/ec-remote-cluster-self-managed.md | 2 +- deploy-manage/remote-clusters/ece-remote-cluster-ece-ess.md | 2 +- deploy-manage/remote-clusters/ece-remote-cluster-other-ece.md | 2 +- deploy-manage/remote-clusters/ece-remote-cluster-same-ece.md | 2 +- .../remote-clusters/ece-remote-cluster-self-managed.md | 2 +- deploy-manage/remote-clusters/remote-clusters-api-key.md | 2 +- deploy-manage/remote-clusters/remote-clusters-migrate.md | 2 +- .../users-roles/cluster-or-deployment-auth/built-in-roles.md | 2 +- .../users-roles/cluster-or-deployment-auth/role-structure.md | 2 +- deploy-manage/users-roles/cluster-or-deployment-auth/saml.md | 2 +- .../elasticsearch/elasticsearch-reference/defining-roles.md | 2 +- 14 files changed, 14 insertions(+), 14 deletions(-) diff --git a/deploy-manage/remote-clusters/ec-remote-cluster-ece.md b/deploy-manage/remote-clusters/ec-remote-cluster-ece.md index 05def9ed72..987653daff 100644 --- a/deploy-manage/remote-clusters/ec-remote-cluster-ece.md +++ b/deploy-manage/remote-clusters/ec-remote-cluster-ece.md @@ -299,4 +299,4 @@ The response will include just the remote clusters from the same {{ecloud}} orga ## Configure roles and users [ec_configure_roles_and_users_3] -To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key). +To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key). diff --git a/deploy-manage/remote-clusters/ec-remote-cluster-other-ess.md b/deploy-manage/remote-clusters/ec-remote-cluster-other-ess.md index de596ba489..156f5ba2a6 100644 --- a/deploy-manage/remote-clusters/ec-remote-cluster-other-ess.md +++ b/deploy-manage/remote-clusters/ec-remote-cluster-other-ess.md @@ -237,4 +237,4 @@ The response will include just the remote clusters from the same {{ecloud}} orga ## Configure roles and users [ec_configure_roles_and_users_2] -To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key). \ No newline at end of file +To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key). \ No newline at end of file diff --git a/deploy-manage/remote-clusters/ec-remote-cluster-same-ess.md b/deploy-manage/remote-clusters/ec-remote-cluster-same-ess.md index cf08bc919a..1c0098e230 100644 --- a/deploy-manage/remote-clusters/ec-remote-cluster-same-ess.md +++ b/deploy-manage/remote-clusters/ec-remote-cluster-same-ess.md @@ -274,4 +274,4 @@ The response will include just the remote clusters from the same {{ecloud}} orga ## Configure roles and users [ec_configure_roles_and_users] -To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key). +To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key). diff --git a/deploy-manage/remote-clusters/ec-remote-cluster-self-managed.md b/deploy-manage/remote-clusters/ec-remote-cluster-self-managed.md index 0e1f93873c..3d95571280 100644 --- a/deploy-manage/remote-clusters/ec-remote-cluster-self-managed.md +++ b/deploy-manage/remote-clusters/ec-remote-cluster-self-managed.md @@ -324,4 +324,4 @@ The response will include just the remote clusters from the same {{ecloud}} orga ## Configure roles and users [ec_configure_roles_and_users_4] -To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key). \ No newline at end of file +To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key). \ No newline at end of file diff --git a/deploy-manage/remote-clusters/ece-remote-cluster-ece-ess.md b/deploy-manage/remote-clusters/ece-remote-cluster-ece-ess.md index c400226c0f..8cc3ef63fa 100644 --- a/deploy-manage/remote-clusters/ece-remote-cluster-ece-ess.md +++ b/deploy-manage/remote-clusters/ece-remote-cluster-ece-ess.md @@ -248,4 +248,4 @@ The response includes just the remote clusters from the same ECE environment. In ## Configure roles and users [ece_configure_roles_and_users_3] -To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key). \ No newline at end of file +To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key). \ No newline at end of file diff --git a/deploy-manage/remote-clusters/ece-remote-cluster-other-ece.md b/deploy-manage/remote-clusters/ece-remote-cluster-other-ece.md index 9cfdc15a75..bcaf2db564 100644 --- a/deploy-manage/remote-clusters/ece-remote-cluster-other-ece.md +++ b/deploy-manage/remote-clusters/ece-remote-cluster-other-ece.md @@ -321,4 +321,4 @@ The response includes just the remote clusters from the same ECE environment. In ## Configure roles and users [ece_configure_roles_and_users_2] -To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key). \ No newline at end of file +To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key). \ No newline at end of file diff --git a/deploy-manage/remote-clusters/ece-remote-cluster-same-ece.md b/deploy-manage/remote-clusters/ece-remote-cluster-same-ece.md index fab812ee38..3ecb9d2f2d 100644 --- a/deploy-manage/remote-clusters/ece-remote-cluster-same-ece.md +++ b/deploy-manage/remote-clusters/ece-remote-cluster-same-ece.md @@ -277,4 +277,4 @@ The response includes just the remote clusters from the same ECE environment. In ## Configure roles and users [ece_configure_roles_and_users] -To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key). +To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key). diff --git a/deploy-manage/remote-clusters/ece-remote-cluster-self-managed.md b/deploy-manage/remote-clusters/ece-remote-cluster-self-managed.md index 88b107c9ea..820a7f18ab 100644 --- a/deploy-manage/remote-clusters/ece-remote-cluster-self-managed.md +++ b/deploy-manage/remote-clusters/ece-remote-cluster-self-managed.md @@ -328,4 +328,4 @@ The response includes just the remote clusters from the same ECE environment. In ## Configure roles and users [ece_configure_roles_and_users_4] -To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key). \ No newline at end of file +To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key). \ No newline at end of file diff --git a/deploy-manage/remote-clusters/remote-clusters-api-key.md b/deploy-manage/remote-clusters/remote-clusters-api-key.md index 63e2436733..699798b3be 100644 --- a/deploy-manage/remote-clusters/remote-clusters-api-key.md +++ b/deploy-manage/remote-clusters/remote-clusters-api-key.md @@ -321,7 +321,7 @@ cluster: ## Configure roles and users [remote-clusters-privileges-api-key] -To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-indices-priv) or [remote cluster privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-cluster-priv) on the local cluster. +To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-indices-priv) or [remote cluster privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-cluster-priv) on the local cluster. You can manage users and roles from Stack Management in {{kib}} by selecting **Security > Roles** from the side navigation. You can also use the [role management APIs](https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-security) to add, update, remove, and retrieve roles dynamically. diff --git a/deploy-manage/remote-clusters/remote-clusters-migrate.md b/deploy-manage/remote-clusters/remote-clusters-migrate.md index fc36820dfc..59dc1e72e4 100644 --- a/deploy-manage/remote-clusters/remote-clusters-migrate.md +++ b/deploy-manage/remote-clusters/remote-clusters-migrate.md @@ -117,7 +117,7 @@ On the local cluster, stop any persistent tasks that refer to the remote cluster On the local cluster: -1. Enhance any roles used by local cluster users with the required [remote indices privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-indices-priv) or [remote cluster privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-cluster-priv) for {{ccr}} and {{ccs}}. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key). Note: +1. Enhance any roles used by local cluster users with the required [remote indices privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-indices-priv) or [remote cluster privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-cluster-priv) for {{ccr}} and {{ccs}}. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key). Note: * You only need to assign additional `remote_indices` or `remote_cluster` privileges to existing roles used for cross-cluster operations. You should be able to copy these privileges from the original roles on the remote cluster, where they are defined under the certification based security model. * The roles on the local cluster can’t exceed the `access` privilege granted by the cross-cluster API key. Any extra local privileges will be suppressed by the cross-cluster API key’s privileges. diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md b/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md index 92f84a25a5..9f9b2c338f 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md @@ -113,7 +113,7 @@ $$$built-in-roles-remote-monitoring-collector$$$ `remote_monitoring_collector` : Grants the minimum privileges required to collect monitoring data for the {{stack}}. $$$built-in-roles-reporting-user$$$ `reporting_user` -: Grants the necessary privileges required to use {{reporting}} features in {{kib}}, including generating and downloading reports. This role implicitly grants access to all Kibana reporting features, with each user having access only to their own reports. Note that reporting users should also be assigned additional roles that grant read access to the [indices](../../../deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md#roles-indices-priv) that will be used to generate reports. +: Grants the necessary privileges required to use {{reporting}} features in {{kib}}, including generating and downloading reports. This role implicitly grants access to all Kibana reporting features, with each user having access only to their own reports. Note that reporting users should also be assigned additional roles that grant read access to the [indices](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#roles-indices-priv) that will be used to generate reports. $$$built-in-roles-rollup-admin$$$ `rollup_admin` : Grants `manage_rollup` cluster privileges, which enable you to manage and execute all rollup actions. diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md b/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md index 11a0553b53..c15ca9b7d1 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md @@ -147,7 +147,7 @@ Remote indices are effective for remote clusters configured with the API key bas :::: -The remote indices privileges entry has an extra mandatory `clusters` field compared to an [indices privileges entry](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md#roles-indices-priv). Otherwise the two have identical structure. The following describes the structure of a remote indices permissions entry: +The remote indices privileges entry has an extra mandatory `clusters` field compared to an [indices privileges entry](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#roles-indices-priv). Otherwise the two have identical structure. The following describes the structure of a remote indices permissions entry: ```js { diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/saml.md b/deploy-manage/users-roles/cluster-or-deployment-auth/saml.md index 6d3893716d..d12d3f81c1 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/saml.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/saml.md @@ -591,7 +591,7 @@ PUT /_security/role_mapping/saml-example } ``` -1. The `example_role` role is **not** a builtin Elasticsearch role. This example assumes that you have created a custom role of your own, with appropriate access to your [data streams, indices,](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md#roles-indices-priv) and [Kibana features](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md#kibana-feature-privileges). +1. The `example_role` role is **not** a builtin Elasticsearch role. This example assumes that you have created a custom role of your own, with appropriate access to your [data streams, indices,](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#roles-indices-priv) and [Kibana features](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md#kibana-feature-privileges). ### Example: Role mapping API, using SAML attributes diff --git a/raw-migrated-files/elasticsearch/elasticsearch-reference/defining-roles.md b/raw-migrated-files/elasticsearch/elasticsearch-reference/defining-roles.md index 7525007da7..24bb1db7bc 100644 --- a/raw-migrated-files/elasticsearch/elasticsearch-reference/defining-roles.md +++ b/raw-migrated-files/elasticsearch/elasticsearch-reference/defining-roles.md @@ -130,7 +130,7 @@ Remote indices are effective for remote clusters configured with the API key bas :::: -The remote indices privileges entry has an extra mandatory `clusters` field compared to an [indices privileges entry](../../../deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md#roles-indices-priv). Otherwise the two have identical structure. The following describes the structure of a remote indices permissions entry: +The remote indices privileges entry has an extra mandatory `clusters` field compared to an [indices privileges entry](../../../deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#roles-indices-priv). Otherwise the two have identical structure. The following describes the structure of a remote indices permissions entry: ```js { From 91f7061406bfeeb0faf5a5048e0dc9f53fee573f Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Thu, 27 Feb 2025 22:25:55 -0500 Subject: [PATCH 15/19] delete --- .../elasticsearch-reference/defining-roles.md | 266 ------------------ 1 file changed, 266 deletions(-) delete mode 100644 raw-migrated-files/elasticsearch/elasticsearch-reference/defining-roles.md diff --git a/raw-migrated-files/elasticsearch/elasticsearch-reference/defining-roles.md b/raw-migrated-files/elasticsearch/elasticsearch-reference/defining-roles.md deleted file mode 100644 index 24bb1db7bc..0000000000 --- a/raw-migrated-files/elasticsearch/elasticsearch-reference/defining-roles.md +++ /dev/null @@ -1,266 +0,0 @@ -# Defining roles [defining-roles] - -A role is defined by the following JSON structure: - -```js -{ - "run_as": [ ... ], <1> - "cluster": [ ... ], <2> - "global": { ... }, <3> - "indices": [ ... ], <4> - "applications": [ ... ], <5> - "remote_indices": [ ... ], <6> - "remote_cluster": [ ... ], <7> - "metadata": { ... }, <8> - "description": "..." <9> -} -``` - -1. A list of usernames the owners of this role can [impersonate](../../../deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md). -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. An object defining global privileges. A global privilege is a form of cluster privilege that is request sensitive. A standard cluster privilege makes authorization decisions based solely on the action being executed. A global privilege also considers the parameters included in the request. Support for global privileges is currently limited to the management of application privileges. This field is optional. -4. A list of indices permissions entries. This field is optional (missing `indices` privileges effectively mean no index level permissions). -5. A list of application privilege entries. This field is optional. -6. A list of indices permissions entries for [remote clusters configured with the API key based model](../../../deploy-manage/remote-clusters/remote-clusters-api-key.md). This field is optional (missing `remote_indices` privileges effectively mean no index level permissions for any API key based remote clusters). -7. A list of cluster permissions entries for [remote clusters configured with the API key based model](../../../deploy-manage/remote-clusters/remote-clusters-api-key.md). This field is optional (missing `remote_cluster` privileges effectively means no additional cluster permissions for any API key based remote clusters). -8. Metadata field associated with the role, such as `metadata.app_tag`. Metadata is internally indexed as a [flattened](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/mapping-reference/flattened.md) field type. This means that all sub-fields act like `keyword` fields when querying and sorting. Metadata values can be simple values, but also lists and maps. This field is optional. -9. A string value with the description text of the role. The maximum length of it is `1000` chars. The field is internally indexed as a [text](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/mapping-reference/text.md#text-field-type) field type (with default values for all parameters). This field is optional. - - -::::{note} -:name: valid-role-name - -Role names must be at least 1 and no more than 507 characters. They can contain alphanumeric characters (`a-z`, `A-Z`, `0-9`), spaces, punctuation, and printable symbols in the [Basic Latin (ASCII) block](https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)). Leading or trailing whitespace is not allowed. -:::: - - -## Indices privileges [roles-indices-priv] - -The following describes the structure of an indices permissions entry: - -```js -{ - "names": [ ... ], <1> - "privileges": [ ... ], <2> - "field_security" : { ... }, <3> - "query": "...", <4> - "allow_restricted_indices": false <5> -} -``` - -1. A list of data streams, indices, and aliases to which the permissions in this entry apply. Supports wildcards (`*`). -2. The index level privileges the owners of the role have on the associated data streams and indices specified in the `names` argument. -3. Specification for document fields the owners of the role have read access to. See [Setting up field and document level security](../../../deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md) for details. -4. A search query that defines the documents the owners of the role have read access to. A document within the associated data streams and indices must match this query in order for it to be accessible by the owners of the role. -5. Restricted indices are a special category of indices that are used internally to store configuration data and should not be directly accessed. Only internal system roles should normally grant privileges over the restricted indices. **Toggling this flag is very strongly discouraged because it could effectively grant unrestricted operations on critical data, making the entire system unstable or leaking sensitive information.** If however, for administrative purposes, you need to create a role with privileges covering restricted indices, you must set this field to `true` (default is `false`), and then the `names` field will cover the restricted indices as well. - - -::::{tip} -The `names` parameter accepts wildcard and regular expressions that may refer to multiple data streams, indices, and aliases. - -* 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. - -```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 / -``` - -:::: - - - -## Global privileges [roles-global-priv] - -The following describes the structure of the global privileges entry: - -```js -{ - "application": { - "manage": { <1> - "applications": [ ... ] <2> - } - }, - "profile": { - "write": { <3> - "applications": [ ... ] <4> - } - } -} -``` - -1. The privilege for the ability to manage application privileges -2. The list of application names that may be managed. This list supports wildcards (e.g. `"myapp-*"`) and regular expressions (e.g. `"/app[0-9]*/"`) -3. The privilege for the ability to write the `access` and `data` of any user profile -4. The list of names, wildcards and regular expressions to which the write privilege is restricted to - - - -## Application privileges [roles-application-priv] - -The following describes the structure of an application privileges entry: - -```js -{ - "application": "my_app", <1> - "privileges": [ ... ], <2> - "resources": [ ... ] <3> -} -``` - -1. The name of the application. -2. The list of the names of the application privileges to grant to this role. -3. The resources to which those privileges apply. These are handled in the same way as index name pattern in `indices` permissions. These resources do not have any special meaning to the {{es}} {{security-features}}. - - -For details about the validation rules for these fields, see the [add application privileges API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-put-privileges). - -A role may refer to application privileges that do not exist - that is, they have not yet been defined through the add application privileges API (or they were defined, but have since been deleted). In this case, the privilege has no effect, and will not grant any actions in the [has privileges API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-has-privileges). - - -## Remote indices privileges [roles-remote-indices-priv] - -For [remote clusters configured with the API key based model](../../../deploy-manage/remote-clusters/remote-clusters-api-key.md), remote indices privileges can be used to specify desired indices privileges for matching remote clusters. The final effective index privileges will be an intersection of the remote indices privileges and the [cross-cluster API key](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-cross-cluster-api-key)'s indices privileges. - -::::{note} -Remote indices are effective for remote clusters configured with the API key based model. They have no effect for remote clusters configured with the certificate based model. -:::: - - -The remote indices privileges entry has an extra mandatory `clusters` field compared to an [indices privileges entry](../../../deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#roles-indices-priv). Otherwise the two have identical structure. The following describes the structure of a remote indices permissions entry: - -```js -{ - "clusters": [ ... ], <1> - "names": [ ... ], <2> - "privileges": [ ... ], <3> - "field_security" : { ... }, <4> - "query": "...", <5> - "allow_restricted_indices": false <6> -} -``` - -1. A list of remote cluster aliases. It supports literal strings as well as [wildcards](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/rest-apis/api-conventions.md#api-multi-index) and [regular expressions](asciidocalypse://docs/elasticsearch/docs/reference/query-languages/regexp-syntax.md). This field is required. -2. A list of data streams, indices, and aliases to which the permissions in this entry apply. Supports wildcards (`*`). -3. The index level privileges the owners of the role have on the associated data streams and indices specified in the `names` argument. -4. Specification for document fields the owners of the role have read access to. See [Setting up field and document level security](../../../deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md) for details. -5. A search query that defines the documents the owners of the role have read access to. A document within the associated data streams and indices must match this query in order for it to be accessible by the owners of the role. -6. Restricted indices are a special category of indices that are used internally to store configuration data and should not be directly accessed. Only internal system roles should normally grant privileges over the restricted indices. **Toggling this flag is very strongly discouraged because it could effectively grant unrestricted operations on critical data, making the entire system unstable or leaking sensitive information.** If however, for administrative purposes, you need to create a role with privileges covering restricted indices, you must set this field to `true` (default is `false`), and then the `names` field will cover the restricted indices as well. - - - -## Remote cluster privileges [roles-remote-cluster-priv] - -For [remote clusters configured with the API key based model](../../../deploy-manage/remote-clusters/remote-clusters-api-key.md), remote cluster privileges can be used to specify additional cluster privileges for matching remote clusters. - -::::{note} -Remote cluster privileges are only effective for remote clusters configured with the API key based model. They have no effect on remote clusters configured with the certificate based model. -:::: - - -The following describes the structure of a remote cluster permissions entry: - -```js -{ - "clusters": [ ... ], <1> - "privileges": [ ... ] <2> -} -``` - -1. A list of remote cluster aliases. It supports literal strings as well as [wildcards](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/rest-apis/api-conventions.md#api-multi-index) and [regular expressions](asciidocalypse://docs/elasticsearch/docs/reference/query-languages/regexp-syntax.md). This field is required. -2. The cluster level privileges for the remote cluster. The allowed values here are a subset of the [cluster privileges](../../../deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-cluster). The [builtin privileges API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-get-builtin-privileges) can be used to determine which privileges are allowed here. This field is required. - - - -## Example [_example_9] - -The following snippet shows an example definition of a `clicks_admin` role: - -```console -POST /_security/role/clicks_admin -{ - "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 [cluster and indices privileges](../../../deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md) -:::: - - -There are two available mechanisms to define roles: using the *Role Management APIs* or in local files on the {{es}} nodes. You can also implement 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 [Customizing roles and authorization](../../../deploy-manage/users-roles/cluster-or-deployment-auth/authorization-plugins.md). - - -## Role management UI [roles-management-ui] - -You can manage users and roles easily in {{kib}}. To manage roles, log in to {{kib}} and go to **Management / Security / Roles**. - - -## Role management API [roles-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 [Roles](https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-security). - - -## File-based role management [roles-management-file] - -Apart from the *Role Management APIs*, roles can also be defined in local `roles.yml` file located in `ES_PATH_CONF`. 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. Please note however, that the `roles.yml` file is provided as a minimal administrative function and is not intended to cover and be used to define roles for all use cases. - -::::{important} -You cannot view, edit, or remove any roles that are defined in `roles.yml` by using the [role management UI](../../../deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md#roles-management-ui) or the [role management APIs](../../../deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md#roles-management-api). - -:::: - - -::::{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: - -```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"}}' -``` - -{{es}} continuously monitors the `roles.yml` file and automatically picks up and applies any changes to it. From d53ce3806220c99690468f32c853c7948950f5f0 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Thu, 27 Feb 2025 22:31:41 -0500 Subject: [PATCH 16/19] more cleanup --- .../elasticsearch-privileges.md | 2 +- .../document-level-security.md | 69 ------ .../field-and-document-access-control.md | 135 ------------ .../field-level-security.md | 197 ----------------- .../kibana/kibana/kibana-role-management.md | 198 ------------------ raw-migrated-files/toc.yml | 5 - 6 files changed, 1 insertion(+), 605 deletions(-) delete mode 100644 raw-migrated-files/elasticsearch/elasticsearch-reference/document-level-security.md delete mode 100644 raw-migrated-files/elasticsearch/elasticsearch-reference/field-and-document-access-control.md delete mode 100644 raw-migrated-files/elasticsearch/elasticsearch-reference/field-level-security.md delete mode 100644 raw-migrated-files/kibana/kibana/kibana-role-management.md diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md b/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md index a37cd32f4b..f433733eaa 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md @@ -305,7 +305,7 @@ To learn how to assign privileges to a role, refer to [](/deploy-manage/users-ro : Privilege to create an index or data stream. 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. `cross_cluster_replication` -: Privileges to perform cross-cluster replication for indices located on [remote clusters configured with the API key based model](../../remote-clusters/remote-clusters-api-key.md). This privilege should only be used for the `privileges` field of [remote indices privileges](defining-roles.md#roles-remote-indices-priv). +: Privileges to perform cross-cluster replication for indices located on [remote clusters configured with the API key based model](../../remote-clusters/remote-clusters-api-key.md). This privilege should only be used for the `privileges` field of [remote indices privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-indices-priv). This privilege is not available in {{serverless-full}}. diff --git a/raw-migrated-files/elasticsearch/elasticsearch-reference/document-level-security.md b/raw-migrated-files/elasticsearch/elasticsearch-reference/document-level-security.md deleted file mode 100644 index 9eca45be4f..0000000000 --- a/raw-migrated-files/elasticsearch/elasticsearch-reference/document-level-security.md +++ /dev/null @@ -1,69 +0,0 @@ -# Document level security [document-level-security] - -Document level security restricts the documents that users have read access to. In particular, it restricts which documents can be accessed from document-based read APIs. - -To enable document level security, you use a query to specify the documents that each role can access. The document `query` is associated with a particular data stream, index, or wildcard (`*`) pattern and operates in conjunction with the privileges specified for the data streams and indices. - -The specified document `query`: - -* Expects the same format as if it was defined in the search request -* Supports [templating a role query](../../../deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md#templating-role-query) that can access the details of the currently authenticated user -* Accepts queries written as either string values or nested JSON -* Supports the majority of the {{es}} [Query Domain Specific Language (DSL)](../../../explore-analyze/query-filter/languages/querydsl.md), with [some limitations](../../../deploy-manage/security.md#field-document-limitations) for field and document level security - -::::{important} -Omitting the `query` parameter entirely disables document level security for the respective indices permission entry. -:::: - - -The following role definition grants read access only to documents that belong to the `click` category within all the `events-*` data streams and indices: - -```console -POST /_security/role/click_role -{ - "indices": [ - { - "names": [ "events-*" ], - "privileges": [ "read" ], - "query": "{\"match\": {\"category\": \"click\"}}" - } - ] -} -``` - -You can write this same query using nested JSON syntax: - -```console -POST _security/role/click_role -{ - "indices": [ - { - "names": [ "events-*" ], - "privileges": [ "read" ], - "query": { - "match": { - "category": "click" - } - } - } - ] -} -``` - -The following role grants read access only to the documents whose `department_id` equals `12`: - -```console -POST /_security/role/dept_role -{ - "indices" : [ - { - "names" : [ "*" ], - "privileges" : [ "read" ], - "query" : { - "term" : { "department_id" : 12 } - } - } - ] -} -``` - diff --git a/raw-migrated-files/elasticsearch/elasticsearch-reference/field-and-document-access-control.md b/raw-migrated-files/elasticsearch/elasticsearch-reference/field-and-document-access-control.md deleted file mode 100644 index 07109e9a94..0000000000 --- a/raw-migrated-files/elasticsearch/elasticsearch-reference/field-and-document-access-control.md +++ /dev/null @@ -1,135 +0,0 @@ -# Setting up field and document level security [field-and-document-access-control] - -You can control access to data within a data stream or index by adding field and document level security permissions to a role. [Field level security permissions](../../../deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md) restrict access to particular fields within a document. [Document level security permissions](../../../deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md) restrict access to particular documents. - -::::{note} -Document and field level security is currently meant to operate with read-only privileged accounts. Users with document and field level security enabled for a data stream or index should not perform write operations. -:::: - - -A role can define both field and document level permissions on a per-index basis. A role that doesn’t specify field level permissions grants access to ALL fields. Similarly, a role that doesn’t specify document level permissions grants access to ALL documents in the index. - -::::{important} -When assigning users multiple roles, be careful that you don’t inadvertently grant wider access than intended. Each user has a single set of field level and document level permissions per data stream or index. See [Multiple roles with document and field level security](../../../deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md#multiple-roles-dls-fls). - -:::: - - -## Multiple roles with document and field level security [multiple-roles-dls-fls] - -A user can have many roles and each role can define different permissions on the same data stream or index. It is important to understand the behavior of document and field level security in this scenario. - -Document level security takes into account each role held by the user and combines each document level security query for a given data stream or index with an "OR". This means that only one of the role queries must match for a document to be returned. For example, if a role grants access to an index without document level security and another grants access with document level security, document level security is not applied; the user with both roles has access to all of the documents in the index. - -Field level security takes into account each role the user has and combines all of the fields listed into a single set for each data stream or index. For example, if a role grants access to an index without field level security and another grants access with field level security, field level security is not be applied for that index; the user with both roles has access to all of the fields in the index. - -For example, let’s say `role_a` grants access to only the `address` field of the documents in `index1`; it doesn’t specify any document restrictions. Conversely, `role_b` limits access to a subset of the documents in `index1`; it doesn’t specify any field restrictions. If you assign a user both roles, `role_a` gives the user access to all documents and `role_b` gives the user access to all fields. - -::::{important} -If you need to restrict access to both documents and fields, consider splitting documents by index instead. - -:::: - - - -## Templating a role query [templating-role-query] - -When you create a role, you can specify a query that defines the [document level security permissions](../../../deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md). You can optionally use Mustache templates in the role query to insert the username of the current authenticated user into the role. Like other places in {{es}} that support templating or scripting, you can specify inline, stored, or file-based templates and define custom parameters. You access the details for the current authenticated user through the `_user` parameter. - -For example, the following role query uses a template to insert the username of the current authenticated user: - -```console -POST /_security/role/example1 -{ - "indices" : [ - { - "names" : [ "my-index-000001" ], - "privileges" : [ "read" ], - "query" : { - "template" : { - "source" : { - "term" : { "acl.username" : "{{_user.username}}" } - } - } - } - } - ] -} -``` - -You can access the following information through the `_user` variable: - -| Property | Description | -| --- | --- | -| `_user.username` | The username of the current authenticated user. | -| `_user.full_name` | If specified, the full name of the current authenticated user. | -| `_user.email` | If specified, the email of the current authenticated user. | -| `_user.roles` | If associated, a list of the role names of the current authenticated user. | -| `_user.metadata` | If specified, a hash holding custom metadata of the current authenticated user. | - -You can also access custom user metadata. For example, if you maintain a `group_id` in your user metadata, you can apply document level security based on the `group.id` field in your documents: - -```console -POST /_security/role/example2 -{ - "indices" : [ - { - "names" : [ "my-index-000001" ], - "privileges" : [ "read" ], - "query" : { - "template" : { - "source" : { - "term" : { "group.id" : "{{_user.metadata.group_id}}" } - } - } - } - } - ] -} -``` - -If your metadata field contains an object or array, you can access it using the `{{#toJson}}parameter{{/toJson}}` function. - -```console -POST /_security/role/example3 -{ - "indices" : [ - { - "names" : [ "my-index-000001" ], - "privileges" : [ "read" ], - "query" : { - "template" : { - "source" : "{ \"terms\": { \"group.statuses\": {{#toJson}}_user.metadata.statuses{{/toJson}} }}" - } - } - } - ] -} -``` - - -## Pre-processing documents to add security details [set-security-user-processor] - -To guarantee that a user reads only their own documents, it makes sense to set up document level security. In this scenario, each document must have the username or role name associated with it, so that this information can be used by the role query for document level security. This is a situation where the [set security user processor](asciidocalypse://docs/elasticsearch/docs/reference/ingestion-tools/enrich-processor/ingest-node-set-security-user-processor.md) ingest processor can help. - -::::{note} -Document level security doesn’t apply to write APIs. You must use unique ids for each user that uses the same data stream or index, otherwise they might overwrite other users' documents. The ingest processor just adds properties for the current authenticated user to the documents that are being indexed. -:::: - - -The [set security user processor](asciidocalypse://docs/elasticsearch/docs/reference/ingestion-tools/enrich-processor/ingest-node-set-security-user-processor.md) attaches user-related details (such as `username`, `roles`, `email`, `full_name` and `metadata` ) from the current authenticated user to the current document by pre-processing the ingest. When you index data with an ingest pipeline, user details are automatically attached to the document. If the authenticating credential is an API key, the API key `id`, `name` and `metadata` (if it exists and is non-empty) are also attached to the document. - -For more information see [Ingest pipelines](../../../manage-data/ingest/transform-enrich/ingest-pipelines.md) and [Set security user](asciidocalypse://docs/elasticsearch/docs/reference/ingestion-tools/enrich-processor/ingest-node-set-security-user-processor.md) - - -## Field and document level security with Cross-cluster API keys [ccx-apikeys-dls-fls] - -[Cross-Cluster API keys](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-cross-cluster-api-key) can be used to authenticate requests to a remote cluster. The `search` parameter defines permissions for cross-cluster search. The `replication` parameter defines permissions for cross-cluster replication. - -`replication` does not support any field or document level security. `search` supports field and document level security. - -For reasons similar to those described in [Multiple roles with document and field level security](../../../deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md#multiple-roles-dls-fls), you can’t create a single cross-cluster API key with both the `search` and `replication` parameters if the `search` parameter has document or field level security defined. - -If you need to use both of these parameters, and you need to define document or field level security for the `search` parameter, create two separate cross-cluster API keys, one using the `search` parameter, and one using the `replication` parameter. You will also need to set up two different remote connections to the same cluster, with each named connection using the appropriate cross-cluster API key. - - diff --git a/raw-migrated-files/elasticsearch/elasticsearch-reference/field-level-security.md b/raw-migrated-files/elasticsearch/elasticsearch-reference/field-level-security.md deleted file mode 100644 index c02cd1db22..0000000000 --- a/raw-migrated-files/elasticsearch/elasticsearch-reference/field-level-security.md +++ /dev/null @@ -1,197 +0,0 @@ -# Field level security [field-level-security] - -Field level security restricts the fields that users have read access to. In particular, it restricts which fields can be accessed from document-based read APIs. - -To enable field level security, specify the fields that each role can access as part of the indices permissions in a role definition. Field level security is thus bound to a well-defined set of data streams or indices (and potentially a set of [documents](../../../deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md)). - -The following role definition grants read access only to the `category`, `@timestamp`, and `message` fields in all the `events-*` data streams and indices. - -```console -POST /_security/role/test_role1 -{ - "indices": [ - { - "names": [ "events-*" ], - "privileges": [ "read" ], - "field_security" : { - "grant" : [ "category", "@timestamp", "message" ] - } - } - ] -} -``` - -Access to the following metadata fields is always allowed: `_id`, `_type`, `_parent`, `_routing`, `_timestamp`, `_ttl`, `_size` and `_index`. If you specify an empty list of fields, only these metadata fields are accessible. - -::::{note} -Omitting the fields entry entirely disables field level security. -:::: - - -You can also specify field expressions. For example, the following example grants read access to all fields that start with an `event_` prefix: - -```console -POST /_security/role/test_role2 -{ - "indices" : [ - { - "names" : [ "*" ], - "privileges" : [ "read" ], - "field_security" : { - "grant" : [ "event_*" ] - } - } - ] -} -``` - -Use the dot notations to refer to nested fields in more complex documents. For example, assuming the following document: - -```js -{ - "customer": { - "handle": "Jim", - "email": "jim@mycompany.com", - "phone": "555-555-5555" - } -} -``` - -The following role definition enables only read access to the customer `handle` field: - -```console -POST /_security/role/test_role3 -{ - "indices" : [ - { - "names" : [ "*" ], - "privileges" : [ "read" ], - "field_security" : { - "grant" : [ "customer.handle" ] - } - } - ] -} -``` - -This is where wildcard support shines. For example, use `customer.*` to enable only read access to the `customer` data: - -```console -POST /_security/role/test_role4 -{ - "indices" : [ - { - "names" : [ "*" ], - "privileges" : [ "read" ], - "field_security" : { - "grant" : [ "customer.*" ] - } - } - ] -} -``` - -You can deny permission to access fields with the following syntax: - -```console -POST /_security/role/test_role5 -{ - "indices" : [ - { - "names" : [ "*" ], - "privileges" : [ "read" ], - "field_security" : { - "grant" : [ "*"], - "except": [ "customer.handle" ] - } - } - ] -} -``` - -The following rules apply: - -* The absence of `field_security` in a role is equivalent to * access. -* If permission has been granted explicitly to some fields, you can specify denied fields. The denied fields must be a subset of the fields to which permissions were granted. -* Defining denied and granted fields implies access to all granted fields except those which match the pattern in the denied fields. - -For example: - -```console -POST /_security/role/test_role6 -{ - "indices" : [ - { - "names" : [ "*" ], - "privileges" : [ "read" ], - "field_security" : { - "except": [ "customer.handle" ], - "grant" : [ "customer.*" ] - } - } - ] -} -``` - -In the above example, users can read all fields with the prefix "customer." except for "customer.handle". - -An empty array for `grant` (for example, `"grant" : []`) means that access has not been granted to any fields. - -When a user has several roles that specify field level permissions, the resulting field level permissions per data stream or index are the union of the individual role permissions. For example, if these two roles are merged: - -```console -POST /_security/role/test_role7 -{ - "indices" : [ - { - "names" : [ "*" ], - "privileges" : [ "read" ], - "field_security" : { - "grant": [ "a.*" ], - "except" : [ "a.b*" ] - } - } - ] -} - -POST /_security/role/test_role8 -{ - "indices" : [ - { - "names" : [ "*" ], - "privileges" : [ "read" ], - "field_security" : { - "grant": [ "a.b*" ], - "except" : [ "a.b.c*" ] - } - } - ] -} -``` - -The resulting permission is equal to: - -```js -{ - // role 1 + role 2 - ... - "indices" : [ - { - "names" : [ "*" ], - "privileges" : [ "read" ], - "field_security" : { - "grant": [ "a.*" ], - "except" : [ "a.b.c*" ] - } - } - ] -} -``` - -::::{note} -Field-level security should not be set on [`alias`](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/mapping-reference/field-alias.md) fields. To secure a concrete field, its field name must be used directly. -:::: - - -For more information, see [Setting up field and document level security](../../../deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md). - diff --git a/raw-migrated-files/kibana/kibana/kibana-role-management.md b/raw-migrated-files/kibana/kibana/kibana-role-management.md deleted file mode 100644 index 5a1029678d..0000000000 --- a/raw-migrated-files/kibana/kibana/kibana-role-management.md +++ /dev/null @@ -1,198 +0,0 @@ -# {{kib}} role management [kibana-role-management] - -Roles are a collection of privileges that allow you to perform actions in {{kib}} and {{es}}. Users are not directly granted privileges, but are instead assigned one or more roles that describe the desired level of access. When you assign a user multiple roles, the user receives a union of the roles’ privileges. This means that you cannot reduce the privileges of a user by assigning them an additional role. You must instead remove or edit one of their existing roles. - -To create a role, open the menu, then click **Stack Management > Roles** and click **Create role**. - - -### Required permissions [_required_permissions_7] - -The `manage_security` [cluster privilege](../../../deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-cluster) is required to access role management. - -## Cluster privileges [adding_cluster_privileges] - -Cluster privileges grant access to monitoring and management features in {{es}}. They also enable [Stack Management](../../../deploy-manage/index.md) capabilities in {{kib}}. - -Refer to [cluster privileges](../../../deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-cluster) for a complete description of available options. - - -## Index privileges [adding_index_privileges] - -Each role can grant access to multiple data indices, and each index can have a different set of privileges. We recommend granting the `read` and `view_index_metadata` privileges to each index that you expect your users to work with in {{kib}}. - -Refer to [index privileges](../../../deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-indices) for a complete description of available options. - -Document-level and field-level security affords you even more granularity when it comes to granting access to your data. With document-level security (DLS), you can write an {{es}} query to describe which documents this role grants access to. With field-level security (FLS), you can instruct {{es}} to grant or deny access to specific fields within each document. - -### Example: Grant access to indices that match the `filebeat-*` pattern [index_privilege_example_1] - -1. Go to **Stack Management > Roles***, and then click ***Create role**. -2. In **Index privileges**, enter: - - 1. `filebeat-*` in the **Index** field. - 2. `read` and `view_index_metadata` in the **Privileges** field. - - -:::{image} ../../../images/kibana-create-role-index-example.png -:alt: Create role with index privileges -:class: screenshot -::: - - -### Example: Grant read access to specific documents in indices that match the `filebeat-*` pattern [index_privilege_dls_example] - -[Document-level security](../../../deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md) is a [subscription feature](https://www.elastic.co/subscriptions). - -1. Go to **Stack Management > Roles***, and then click ***Create role**. -2. In **Index privileges**, enter: - - 1. `filebeat-*` in the **Indices** field. - 2. `read` and `view_index_metadata` in the **Privileges** field. - -3. Select **Grant read privileges to specific documents**. -4. Enter an {{es}} query that matches the documents your users should access. This example writes a query that allows access to documents that have a `category` field equal to `click`: - - ```sh - { - "match": { - "category": "click" - } - } - ``` - - ::::{note} - {{kib}} automatically surrounds your DLS query with a `query` block, so you don’t have to provide your own. - :::: - - -:::{image} ../../../images/kibana-create-role-dls-example.png -:alt: Create role with DLS index privileges -:class: screenshot -::: - - - -## Remote index privileges [adding_remote_index_privileges] - -If you have at least a platinum license, you can manage access to indices in remote clusters. - -You can assign the same privileges, document-level, and field-level as for [local index privileges](../../../deploy-manage/index.md#adding_index_privileges). - -### Example: Grant access to indices in remote clusters [remote_index_privilege_example_1] - -1. Go to **Stack Management > Roles***, and then click ***Create role**. -2. In **Remote index privileges**, enter: - - 1. The name of your remote cluster in the **Remote clusters** field. - 2. The name of the index in your remote cluster in the **Remote indices** field. - 3. The allowed actions in the **Privileges** field. (e.g. `read` and `view_index_metadata`) - - -:::{image} ../../../images/kibana-create-role-remote-index-example.png -:alt: Create role with remote index privileges -:class: screenshot -::: - - - -## {{kib}} privileges [adding_kibana_privileges] - -To assign {{kib}} privileges to the role, click **Add {{kib}} privilege** in the {{kib}} section. - -:::{image} ../../../images/kibana-spaces-roles.png -:alt: Add {{kib}} privileges -:class: screenshot -::: - -Open the **Spaces*** selection control to specify whether to grant the role access to all spaces ***All Spaces*** or one or more individual spaces. If you select ***All Spaces**, you can’t select individual spaces until you clear your selection. - -Use the **Privilege*** menu to grant access to features. The default is ***Custom***, which you can use to grant access to individual features. Otherwise, you can grant read and write access to all current and future features by selecting ***All***, or grant read access to all current and future features by selecting ***Read**. - -When using the **Customize by feature*** option, you can choose either ***All***, ***Read*** or ***None** for access to each feature. As new features are added to {{kib}}, roles that use the custom option do not automatically get access to the new features. You must manually update the roles. - -::::{note} -**{{stack-monitor-app}}** relies on built-in roles to grant access. When a user is assigned the appropriate roles, the **{{stack-monitor-app}}** application is available; otherwise, it is not visible. -:::: - - -To apply your changes, click **Add {{kib}} privilege**. The privilege shows up under the {{kib}} privileges section of the role. - -:::{image} ../../../images/kibana-create-space-privilege.png -:alt: Add {{kib}} privilege -:class: screenshot -::: - - -## Feature availability [_feature_availability] - -Features are available to users when their roles grant access to the features, **and** those features are visible in their current space. The following matrix explains when features are available to users when controlling access via [spaces](../../../deploy-manage/manage-spaces.md#spaces-managing) and role-based access control: - -| **Spaces config*** | ***Role config*** | ***Result** | -| --- | --- | --- | -| Feature hidden | Feature disabled | Feature not available | -| Feature hidden | Feature enabled | Feature not available | -| Feature visible | Feature disabled | Feature not available | -| Feature visible | Feature enabled | **Feature available** | - - -## Assigning different privileges to different spaces [_assigning_different_privileges_to_different_spaces] - -Using the same role, it’s possible to assign different privileges to different spaces. After you’ve added privileges, click **Add {{kib}} privilege***. If you’ve already added privileges for either ***All Spaces*** or an individual space, you will not be able to select these in the ***Spaces** selection control. - -Additionally, if you’ve already assigned privileges at **All Spaces***, you are only able to assign additional privileges to individual spaces. Similar to the behavior of multiple roles granting the union of all privileges, {{kib}} privileges are also a union. If you’ve already granted the user the ***All*** privilege at ***All Spaces***, you’re not able to restrict the role to only the ***Read** privilege at an individual space. - - -## Privilege summary [_privilege_summary] - -To view a summary of the privileges granted, click **View privilege summary**. - -:::{image} ../../../images/kibana-view-privilege-summary.png -:alt: View privilege summary -:class: screenshot -::: - - -## Example 1: Grant all access to Dashboard at an individual space [_example_1_grant_all_access_to_dashboard_at_an_individual_space] - -1. Click **Add {{kib}} privilege**. -2. For **Spaces**, select an individual space. -3. For **Privilege***, leave the default selection of ***Custom**. -4. For the Dashboard feature, select **All** -5. Click **Add {{kib}} privilege**. - -:::{image} ../../../images/kibana-privilege-example-1.png -:alt: Privilege example 1 -:class: screenshot -::: - - -## Example 2: Grant all access to one space and read access to another [_example_2_grant_all_access_to_one_space_and_read_access_to_another] - -1. Click **Add {{kib}} privilege**. -2. For **Spaces**, select the first space. -3. For **Privilege***, select ***All**. -4. Click **Add {{kib}} privilege**. -5. For **Spaces**, select the second space. -6. For **Privilege***, select ***Read**. -7. Click **Add {{kib}} privilege**. - -:::{image} ../../../images/kibana-privilege-example-2.png -:alt: Privilege example 2 -:class: screenshot -::: - - -## Example 3: Grant read access to all spaces and write access to an individual space [_example_3_grant_read_access_to_all_spaces_and_write_access_to_an_individual_space] - -1. Click **Add {{kib}} privilege**. -2. For **Spaces***, select ***All Spaces**. -3. For **Privilege***, select ***Read**. -4. Click **Add {{kib}} privilege**. -5. For **Spaces**, select the individual space. -6. For **Privilege***, select ***All**. -7. Click **Add {{kib}} privilege**. - -:::{image} ../../../images/kibana-privilege-example-3.png -:alt: Privilege example 3 -:class: screenshot -::: diff --git a/raw-migrated-files/toc.yml b/raw-migrated-files/toc.yml index 44d033d8c2..8cf656b010 100644 --- a/raw-migrated-files/toc.yml +++ b/raw-migrated-files/toc.yml @@ -273,13 +273,9 @@ toc: - file: elasticsearch/elasticsearch-reference/change-passwords-native-users.md - file: elasticsearch/elasticsearch-reference/configuring-stack-security.md - file: elasticsearch/elasticsearch-reference/data-management.md - - file: elasticsearch/elasticsearch-reference/defining-roles.md - - file: elasticsearch/elasticsearch-reference/document-level-security.md - file: elasticsearch/elasticsearch-reference/documents-indices.md - file: elasticsearch/elasticsearch-reference/es-security-principles.md - file: elasticsearch/elasticsearch-reference/esql-using.md - - file: elasticsearch/elasticsearch-reference/field-and-document-access-control.md - - file: elasticsearch/elasticsearch-reference/field-level-security.md - file: elasticsearch/elasticsearch-reference/fips-140-compliance.md - file: elasticsearch/elasticsearch-reference/how-monitoring-works.md - file: elasticsearch/elasticsearch-reference/index-modules-allocation.md @@ -321,7 +317,6 @@ toc: - file: kibana/kibana/elasticsearch-mutual-tls.md - file: kibana/kibana/esql.md - file: kibana/kibana/install.md - - file: kibana/kibana/kibana-role-management.md - file: kibana/kibana/logging-settings.md - file: kibana/kibana/management.md - file: kibana/kibana/reporting-production-considerations.md From 1114de59be6dd52b8cc8913f12ea5ade0b084fd2 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Thu, 27 Feb 2025 22:33:12 -0500 Subject: [PATCH 17/19] more cleanup --- .../tutorial-secure-access-to-kibana.md | 144 ------------------ raw-migrated-files/toc.yml | 1 - 2 files changed, 145 deletions(-) delete mode 100644 raw-migrated-files/kibana/kibana/tutorial-secure-access-to-kibana.md diff --git a/raw-migrated-files/kibana/kibana/tutorial-secure-access-to-kibana.md b/raw-migrated-files/kibana/kibana/tutorial-secure-access-to-kibana.md deleted file mode 100644 index bf50df7be2..0000000000 --- a/raw-migrated-files/kibana/kibana/tutorial-secure-access-to-kibana.md +++ /dev/null @@ -1,144 +0,0 @@ -# Securing access to {{kib}} [tutorial-secure-access-to-kibana] - -{{kib}} is home to an ever-growing suite of powerful features, which help you get the most out of your data. Your data is important, and should be protected. {{kib}} allows you to secure access to your data and control how users are able to interact with your data. - -For example, some users might only need to view your stunning dashboards, while others might need to manage your fleet of Elastic agents and run machine learning jobs to detect anomalous behavior in your network. - -This guide introduces you to three of {{kib}}'s security features: spaces, roles, and users. By the end of this tutorial, you will learn how to manage these entities, and how you can leverage them to secure access to both {{kib}} and your data. - - -## Spaces [_spaces] - -Do you have multiple teams using {{kib}}? Do you want a “playground” to experiment with new visualizations or rules? If so, then [{{kib}} Spaces](../../../deploy-manage/manage-spaces.md) can help. - -Think of a space as another instance of {{kib}}. A space allows you to organize your [dashboards](../../../explore-analyze/dashboards.md), [rules](../../../explore-analyze/alerts-cases.md), [machine learning jobs](../../../explore-analyze/machine-learning/machine-learning-in-kibana.md), and much more into their own categories. For example, you might have a Marketing space for your marketeers to track the results of their campaigns, and an Engineering space for your developers to [monitor application performance](/solutions/observability/apps/application-performance-monitoring-apm.md). - -The assets you create in one space are isolated from other spaces, so when you enter a space, you only see the assets that belong to that space. - -Refer to the [Spaces documentation](../../../deploy-manage/manage-spaces.md) for more information. - - -## Roles [_roles] - -Once your spaces are setup, the next step to securing access is to provision your roles. Roles are a collection of privileges that allow you to perform actions in {{kib}} and Elasticsearch. Roles are assigned to users, and to [system accounts](../../../deploy-manage/users-roles/cluster-or-deployment-auth/built-in-users.md) that power the Elastic Stack. - -You can create your own roles, or use any of the [built-in roles](../../../deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md). Some built-in roles are intended for Elastic Stack components and should not be assigned to end users directly. - -One of the more useful built-in roles is `kibana_admin`. Assigning this role to your users will grant access to all of {{kib}}'s features. This includes the ability to manage Spaces. - -The built-in roles are great for getting started with the Elastic Stack, and for system administrators who do not need more restrictive access. With so many features, it’s not possible to ship more granular roles to accommodate everyone’s needs. This is where custom roles come in. - -As an administrator, you have the ability to create your own roles to describe exactly the kind of access your users should have. For example, you might create a `marketing_user` role, which you then assign to all users in your marketing department. This role would grant access to all of the necessary data and features for this team to be successful, without granting them access they don’t require. - - -## Users [_users] - -Once your roles are setup, the next step to securing access is to create your users, and assign them one or more roles. {{kib}}'s user management allows you to provision accounts for each of your users. - -::::{tip} -Want Single Sign-on? {{kib}} supports a wide range of SSO implementations, including SAML, OIDC, LDAP/AD, and Kerberos. [Learn more about {{kib}}'s SSO features](../../../deploy-manage/users-roles/cluster-or-deployment-auth/user-authentication.md). -:::: - - - -## Example: Create a user with access only to dashboards [tutorial-secure-kibana-dashboards-only] - -Let’s work through an example together. Consider a marketing analyst who wants to monitor the effectiveness of their campaigns. They should be able to see their team’s dashboards, but not be allowed to view or manage anything else in {{kib}}. All of the team’s dashboards are located in the Marketing space. - - -### Create a space [_create_a_space] - -Create a Marketing space for your marketing analysts to use. - -1. Go to the **Spaces** management page using the navigation menu or the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md). -2. Click **Create a space**. -3. Give this space a unique name. For example: `Marketing`. -4. Click **Create space**. - - If you’ve followed the example above, you should end up with a space that looks like this: - - :::{image} ../../../images/kibana-tutorial-secure-access-example-1-space.png - :alt: Create space UI - :class: screenshot - ::: - - - -### Create a role [_create_a_role] - -To effectively use dashboards, create a role that describes the privileges you want to grant. In this example, a marketing analyst will need: - -* Access to **read** the data that powers the dashboards -* Access to **read** the dashboards within the `Marketing` space - -To create the role: - -1. Go to the **Roles** management page using the navigation menu or the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md). -2. Click **Create role**. -3. Give this role a unique name. For example: `marketing_dashboards_role`. -4. For this example, you want to store all marketing data in the `acme-marketing-*` set of indices. To grant this access, locate the **Index privileges** section and enter: - - 1. `acme-marketing-*` in the **Indices** field. - 2. `read` and `view_index_metadata` in the **Privileges** field. - - ::::{tip} - You can add multiple patterns of indices, and grant different access levels to each. Click **Add index privilege** to grant additional access. - :::: - -5. To grant access to dashboards in the `Marketing` space, locate the {{kib}} section, and click **Add {{kib}} privilege**: - - 1. From the **Spaces** dropdown, select the `Marketing` space. - 2. Expand the **Analytics*** section, and select the ***Read*** privilege for ***Dashboard**. - 3. Click **Add Kibana privilege**. - -6. Click **Create role**. - - If you’ve followed the example above, you should end up with a role that looks like this: - - :::{image} ../../../images/kibana-tutorial-secure-access-example-1-role.png - :alt: Create role UI - :class: screenshot - ::: - - - -### Create a user [_create_a_user] - -Now that you created a role, create a user account. - -1. Navigate to **Stack Management**, and under **Security**, select **Users**. -2. Click **Create user**. -3. Give this user a descriptive username, and choose a secure password. -4. Assign the **marketing_dashboards_role** that you previously created to this new user. -5. Click **Create user**. - -:::{image} ../../../images/kibana-tutorial-secure-access-example-1-user.png -:alt: Create user UI -:class: screenshot -::: - - -### Verify [_verify] - -Verify that the user and role are working correctly. - -1. Logout of {{kib}} if you are already logged in. -2. In the login screen, enter the username and password for the account you created. - - You’re taken into the `Marketing` space, and the main navigation shows only the **Dashboard** application. - - :::{image} ../../../images/kibana-tutorial-secure-access-example-1-test.png - :alt: Verifying access to dashboards - :class: screenshot - ::: - - - -## What’s next? [_whats_next_2] - -This guide is an introduction to {{kib}}'s security features. Check out these additional resources to learn more about authenticating and authorizing your users. - -* View the [authentication guide](../../../deploy-manage/users-roles/cluster-or-deployment-auth/user-authentication.md) to learn more about single-sign on and other login features. -* View the [authorization guide](../../../deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md) to learn more about authorizing access to {{kib}}'s features. - -Still have questions? Ask on our [Kibana discuss forum](https://discuss.elastic.co/c/kibana) and a fellow community member or Elastic engineer will help out. diff --git a/raw-migrated-files/toc.yml b/raw-migrated-files/toc.yml index 8cf656b010..3a61c151bf 100644 --- a/raw-migrated-files/toc.yml +++ b/raw-migrated-files/toc.yml @@ -326,7 +326,6 @@ toc: - file: kibana/kibana/Security-production-considerations.md - file: kibana/kibana/set-time-filter.md - file: kibana/kibana/setup.md - - file: kibana/kibana/tutorial-secure-access-to-kibana.md - file: kibana/kibana/upgrade-migrations-rolling-back.md - file: kibana/kibana/upgrade.md - file: kibana/kibana/using-kibana-with-security.md From f8f9c38512a63fb32acba1116e7737b256a9dc11 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Fri, 28 Feb 2025 11:21:44 -0500 Subject: [PATCH 18/19] add some safety redirects --- redirects.yml | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/redirects.yml b/redirects.yml index 0148559007..9f7f27c92f 100644 --- a/redirects.yml +++ b/redirects.yml @@ -1,12 +1,27 @@ redirects: - 'solutions/search/search-approaches/near-real-time-search.md': '!manage-data/data-store/near-real-time-search.md' +# get-started 'get-started/installing-elastic-stack.md': '!deploy-manage/deploy/self-managed.md' + +# solutions + 'solutions/search/search-approaches/near-real-time-search.md': '!manage-data/data-store/near-real-time-search.md' + +## deploy-manage 'deploy-manage/deploy/elastic-cloud/ec-configure-deployment-settings.md': '!deploy-manage/deploy/elastic-cloud/ec-customize-deployment-components.md' 'deploy-manage/users-roles/cluster-or-deployment-auth/user-authentication.md': anchors: 'anonymous-authentication': 'basic-authentication': 'http-authentication': + 'deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md': + anchors: + 'roles-indices-priv': + 'roles-global-priv': + 'roles-application-priv': + 'roles-remote-indices-priv': + 'roles-remote-cluster-priv': + '_example_9': + +## reference 'reference/security/elastic-defend/index.md': 'solutions/security/configure-elastic-defend.md' 'reference/security/elastic-defend/elastic-endpoint-deploy-reqs.md': 'solutions/security/configure-elastic-defend/elastic-defend-requirements.md' 'reference/security/elastic-defend/install-endpoint.md': 'solutions/security/configure-elastic-defend/install-elastic-defend.md' From 9519ecfbac178b23aaa09edfaa0c7600f34f8bc8 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Fri, 28 Feb 2025 11:23:13 -0500 Subject: [PATCH 19/19] -1" --- redirects.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/redirects.yml b/redirects.yml index 9f7f27c92f..66c410dd18 100644 --- a/redirects.yml +++ b/redirects.yml @@ -19,7 +19,6 @@ redirects: 'roles-application-priv': 'roles-remote-indices-priv': 'roles-remote-cluster-priv': - '_example_9': ## reference 'reference/security/elastic-defend/index.md': 'solutions/security/configure-elastic-defend.md'