diff --git a/deploy-manage/kibana-reporting-configuration.md b/deploy-manage/kibana-reporting-configuration.md index 3e6fbc2dbd..bed9fbef11 100644 --- a/deploy-manage/kibana-reporting-configuration.md +++ b/deploy-manage/kibana-reporting-configuration.md @@ -40,7 +40,7 @@ To secure {{report-features}}, you must grant users access to reporting function :applies_to: {stack: ga 9.1, serverless: unavailable} Report generation requests are authenticated by API keys instead of session cookies. There are several key differences between the authentication methods. API keys capture your role privileges, whereas session cookie are based on your user credentials. API keys are also longer-lived, compared to session cookies, which have a shorter lifespan. -If you have a cross-cluster search environment and want to generate reports from remote clusters, you must have the appropriate cluster and index privileges on the remote cluster and local cluster. For example, if requests are authenticated with an API key, the API key requires certain privileges on the local cluster that contains the local index, in addition to the remote. For more information and examples, refer to [Configure roles and users for remote clusters](../deploy-manage/remote-clusters/remote-clusters-cert.md#remote-clusters-privileges-cert). +If you have a cross-cluster search environment and want to generate reports from remote clusters, you must have the appropriate cluster and index privileges on the remote cluster and local cluster. For example, if requests are authenticated with an API key, the API key requires certain privileges on the local cluster that contains the local index, in addition to the remote. For more information and examples, refer to [Configure privileges for cross-cluster search](/explore-analyze/cross-cluster-search.md#configure-privileges-for-ccs). ::: Configuring reporting in your environment involves two main areas: diff --git a/deploy-manage/remote-clusters/_snippets/configure-roles-and-users.md b/deploy-manage/remote-clusters/_snippets/configure-roles-and-users.md index 66e5bafd72..d434aadec2 100644 --- a/deploy-manage/remote-clusters/_snippets/configure-roles-and-users.md +++ b/deploy-manage/remote-clusters/_snippets/configure-roles-and-users.md @@ -17,4 +17,4 @@ This snippet is in use in the following locations: --> % this will need improvement in a future PR, as the text below is only valid for API key based security model -If you're using the API key–based security model for {{ccr}} or {{ccs}}, you can define 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 to further restrict the permissions granted by the API key. For more details, refer to [Configure roles and users](/deploy-manage/remote-clusters/remote-clusters-api-key.md#remote-clusters-privileges-api-key). \ No newline at end of file +If you're using the API key–based security model for {{ccr}} or {{ccs}}, you can define 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 to further restrict the permissions granted by the API key. For more details, refer to [Configure privileges for {{ccr}}](/deploy-manage/tools/cross-cluster-replication/_configure_privileges_for_cross_cluster_replication_2.md#configure-privileges-for-ccr-api-key) and [Configure privileges for {{ccs}}](/explore-analyze/cross-cluster-search.md#configure-privileges-for-ccs-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 8843c6004f..2ff1bdecdd 100644 --- a/deploy-manage/remote-clusters/remote-clusters-api-key.md +++ b/deploy-manage/remote-clusters/remote-clusters-api-key.md @@ -341,85 +341,7 @@ For a full list of available strong identity verification settings for remote cl ## 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](/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. +To use a remote cluster for {{ccr}} or {{ccs}}, configure privileges so users can use {{ccr}} and {{ccs}}: -To manage users and roles in {{kib}}, go to the **Roles** management page in the navigation menu or use the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md). You can also use the [role management APIs]({{es-apis}}group/endpoint-security) to add, update, remove, and retrieve roles dynamically. - -The following examples use the [Create or update roles]({{es-apis}}operation/operation-security-put-role) API. You must have at least the `manage_security` cluster privilege to use this API. - -::::{note} -The cross-cluster API key used by the local cluster to connect the remote cluster must have sufficient privileges to cover all remote indices privileges required by individual users. -:::: - - -### Configure privileges for {{ccr}} [_configure_privileges_for_ccr] - -Assuming the remote cluster is connected under the name of `my_remote_cluster`, the following request creates a role called `remote-replication` on the local cluster that allows replicating the remote `leader-index` index: - -```console -POST /_security/role/remote-replication -{ - "cluster": [ - "manage_ccr" - ], - "remote_indices": [ - { - "clusters": [ "my_remote_cluster" ], - "names": [ - "leader-index" - ], - "privileges": [ - "cross_cluster_replication" - ] - } - ] -} -``` - -After creating the local `remote-replication` role, use the [Create or update users]({{es-apis}}operation/operation-security-put-user) API to create a user on the local cluster and assign the `remote-replication` role. For example, the following request assigns the `remote-replication` role to a user named `cross-cluster-user`: - -```console -POST /_security/user/cross-cluster-user -{ - "password" : "l0ng-r4nd0m-p@ssw0rd", - "roles" : [ "remote-replication" ] -} -``` - -Note that you only need to create this user on the local cluster. - - -### Configure privileges for {{ccs}} [_configure_privileges_for_ccs] - -Assuming the remote cluster is connected under the name of `my_remote_cluster`, the following request creates a `remote-search` role on the local cluster that allows searching the remote `target-index` index: - -```console -POST /_security/role/remote-search -{ - "remote_indices": [ - { - "clusters": [ "my_remote_cluster" ], - "names": [ - "target-index" - ], - "privileges": [ - "read", - "read_cross_cluster", - "view_index_metadata" - ] - } - ] -} -``` - -After creating the `remote-search` role, use the [Create or update users]({{es-apis}}operation/operation-security-put-user) API to create a user on the local cluster and assign the `remote-search` role. For example, the following request assigns the `remote-search` role to a user named `cross-search-user`: - -```console -POST /_security/user/cross-search-user -{ - "password" : "l0ng-r4nd0m-p@ssw0rd", - "roles" : [ "remote-search" ] -} -``` - -Note that you only need to create this user on the local cluster. +* [Configure privileges for {{ccr}}](/deploy-manage/tools/cross-cluster-replication/_configure_privileges_for_cross_cluster_replication_2.md#configure-privileges-for-ccr-api-key) +* [Configure privileges for {{ccs}}](/explore-analyze/cross-cluster-search.md#configure-privileges-for-ccs-api-key) diff --git a/deploy-manage/remote-clusters/remote-clusters-cert.md b/deploy-manage/remote-clusters/remote-clusters-cert.md index 4517caaaae..505135060e 100644 --- a/deploy-manage/remote-clusters/remote-clusters-cert.md +++ b/deploy-manage/remote-clusters/remote-clusters-cert.md @@ -246,245 +246,7 @@ cluster: ## Configure roles and users for remote clusters [remote-clusters-privileges-cert] -After [connecting remote clusters](/deploy-manage/remote-clusters/remote-clusters-self-managed.md), you create a user role on both the local and remote clusters and assign necessary privileges. These roles are required to use {{ccr}} and {{ccs}}. +After [connecting remote clusters](/deploy-manage/remote-clusters/remote-clusters-self-managed.md), configure privileges so users can use {{ccr}} and {{ccs}}: -::::{important} -You must use the same role names on both the local and remote clusters. For example, the following configuration for {{ccr}} uses the `remote-replication` role name on both the local and remote clusters. However, you can specify different role definitions on each cluster. -:::: - - -To manage users and roles in {{kib}}, go to the **Roles** management page in the navigation menu or use the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md). You can also use the [role management APIs]({{es-apis}}group/endpoint-security) 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. - -The following requests use the [create or update roles API]({{es-apis}}operation/operation-security-put-role). You must have at least the `manage_security` cluster privilege to use this API. - -### Configure privileges for {{ccr}} [remote-clusters-privileges-ccr] - -The {{ccr}} user requires different cluster and index privileges on the remote cluster and local cluster. Use the following requests to create separate roles on the local and remote clusters, and then create a user with the required roles. - - -#### Remote cluster [_remote_cluster] - -On the remote cluster that contains the leader index, the {{ccr}} role requires the `read_ccr` cluster privilege, and `monitor` and `read` privileges on the leader index. - -::::{note} -If requests are authenticated with an [API key]({{es-apis}}operation/operation-security-create-api-key), the API key requires the above privileges on the **local** cluster, instead of the remote. -:::: - - -::::{note} -If requests are issued [on behalf of other users](../users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md), then the authenticating user must have the `run_as` privilege on the remote cluster. -:::: - - -The following request creates a `remote-replication` role on the remote cluster: - -```console -POST /_security/role/remote-replication -{ - "cluster": [ - "read_ccr" - ], - "indices": [ - { - "names": [ - "leader-index-name" - ], - "privileges": [ - "monitor", - "read" - ] - } - ] -} -``` - - -#### Local cluster [_local_cluster] - -On the local cluster that contains the follower index, the `remote-replication` role requires the `manage_ccr` cluster privilege, and `monitor`, `read`, `write`, and `manage_follow_index` privileges on the follower index. - -The following request creates a `remote-replication` role on the local cluster: - -```console -POST /_security/role/remote-replication -{ - "cluster": [ - "manage_ccr" - ], - "indices": [ - { - "names": [ - "follower-index-name" - ], - "privileges": [ - "monitor", - "read", - "write", - "manage_follow_index" - ] - } - ] -} -``` - -After creating the `remote-replication` role on each cluster, use the [create or update users API]({{es-apis}}operation/operation-security-put-user) to create a user on the local cluster and assign the `remote-replication` role. For example, the following request assigns the `remote-replication` role to a user named `cross-cluster-user`: - -```console -POST /_security/user/cross-cluster-user -{ - "password" : "l0ng-r4nd0m-p@ssw0rd", - "roles" : [ "remote-replication" ] -} -``` - -::::{note} -You only need to create this user on the **local** cluster. -:::: - - -You can then [configure {{ccr}}](../tools/cross-cluster-replication/set-up-cross-cluster-replication.md) to replicate your data across datacenters. - - -### Configure privileges for {{ccs}} [remote-clusters-privileges-ccs] - -The {{ccs}} user requires different cluster and index privileges on the remote cluster and local cluster. The following requests create separate roles on the local and remote clusters, and then create a user with the required roles. - - -#### Remote cluster [_remote_cluster_2] - -On the remote cluster, the {{ccs}} role requires the `read` and `read_cross_cluster` privileges for the target indices. - -::::{note} -If requests are authenticated with an [API key]({{es-apis}}operation/operation-security-create-api-key), the API key requires the above privileges on the **local** cluster, instead of the remote. -:::: - - -::::{note} -If requests are issued [on behalf of other users](../users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md), then the authenticating user must have the `run_as` privilege on the remote cluster. -:::: - - -The following request creates a `remote-search` role on the remote cluster: - -```console -POST /_security/role/remote-search -{ - "indices": [ - { - "names": [ - "target-indices" - ], - "privileges": [ - "read", - "read_cross_cluster" - ] - } - ] -} -``` - - -#### Local cluster [_local_cluster_2] - -On the local cluster, which is the cluster used to initiate cross cluster search, a user only needs the `remote-search` role. The role privileges can be empty. - -The following request creates a `remote-search` role on the local cluster: - -```console -POST /_security/role/remote-search -{} -``` - -After creating the `remote-search` role on each cluster, use the [create or update users API]({{es-apis}}operation/operation-security-put-user) to create a user on the local cluster and assign the `remote-search` role. For example, the following request assigns the `remote-search` role to a user named `cross-search-user`: - -```console -POST /_security/user/cross-search-user -{ - "password" : "l0ng-r4nd0m-p@ssw0rd", - "roles" : [ "remote-search" ] -} -``` - -::::{note} -You only need to create this user on the **local** cluster. -:::: - - -Users with the `remote-search` role can then [search across clusters](../../explore-analyze/cross-cluster-search.md). - - -### Configure privileges for {{ccs}} and {{kib}} [clusters-privileges-ccs-kibana-cert] - -When using {{kib}} to search across multiple clusters, a two-step authorization process determines whether or not the user can access data streams and indices on a remote cluster: - -* First, the local cluster determines if the user is authorized to access remote clusters. The local cluster is the cluster that {{kib}} is connected to. -* If the user is authorized, the remote cluster then determines if the user has access to the specified data streams and indices. - -To grant {{kib}} users access to remote clusters, assign them a local role with read privileges to indices on the remote clusters. You specify data streams and indices in a remote cluster as `:`. - -To grant users read access on the remote data streams and indices, you must create a matching role on the remote clusters that grants the `read_cross_cluster` privilege with access to the appropriate data streams and indices. - -For example, you might be actively indexing {{ls}} data on a local cluster and periodically offload older time-based indices to an archive on your remote cluster. You want to search across both clusters, so you must enable {{kib}} users on both clusters. - - -#### Local cluster [_local_cluster_3] - -On the local cluster, create a `logstash-reader` role that grants `read` and `view_index_metadata` privileges on the local `logstash-*` indices. - -::::{note} -If you configure the local cluster as another remote in {{es}}, the `logstash-reader` role on your local cluster also needs to grant the `read_cross_cluster` privilege. -:::: - - -```console -POST /_security/role/logstash-reader -{ - "indices": [ - { - "names": [ - "logstash-*" - ], - "privileges": [ - "read", - "view_index_metadata" - ] - } - ] -} -``` - -Assign your {{kib}} users a role that grants [access to {{kib}}](elasticsearch://reference/elasticsearch/roles.md), as well as your `logstash_reader` role. For example, the following request creates the `cross-cluster-kibana` user and assigns the `kibana-access` and `logstash-reader` roles. - -```console -PUT /_security/user/cross-cluster-kibana -{ - "password" : "l0ng-r4nd0m-p@ssw0rd", - "roles" : [ - "logstash-reader", - "kibana-access" - ] -} -``` - - -#### Remote cluster [_remote_cluster_3] - -On the remote cluster, create a `logstash-reader` role that grants the `read_cross_cluster` privilege and `read` and `view_index_metadata` privileges for the `logstash-*` indices. - -```console -POST /_security/role/logstash-reader -{ - "indices": [ - { - "names": [ - "logstash-*" - ], - "privileges": [ - "read_cross_cluster", - "read", - "view_index_metadata" - ] - } - ] -} -``` +* [Configure privileges for {{ccr}}](/deploy-manage/tools/cross-cluster-replication/_configure_privileges_for_cross_cluster_replication_2.md#configure-privileges-for-ccr-cert) +* [Configure privileges for {{ccs}}](/explore-analyze/cross-cluster-search.md#configure-privileges-for-ccs-cert) diff --git a/deploy-manage/remote-clusters/remote-clusters-migrate.md b/deploy-manage/remote-clusters/remote-clusters-migrate.md index 0edffae6d0..1cb8c53218 100644 --- a/deploy-manage/remote-clusters/remote-clusters-migrate.md +++ b/deploy-manage/remote-clusters/remote-clusters-migrate.md @@ -119,7 +119,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](/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: +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 privileges for {{ccr}}](/deploy-manage/tools/cross-cluster-replication/_configure_privileges_for_cross_cluster_replication_2.md#configure-privileges-for-ccr-api-key) and [Configure privileges for {{ccs}}](/explore-analyze/cross-cluster-search.md#configure-privileges-for-ccs-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/tools/cross-cluster-replication/_configure_privileges_for_cross_cluster_replication_2.md b/deploy-manage/tools/cross-cluster-replication/_configure_privileges_for_cross_cluster_replication_2.md index 66ca21bfd6..20646ef642 100644 --- a/deploy-manage/tools/cross-cluster-replication/_configure_privileges_for_cross_cluster_replication_2.md +++ b/deploy-manage/tools/cross-cluster-replication/_configure_privileges_for_cross_cluster_replication_2.md @@ -2,33 +2,95 @@ mapped_pages: - https://www.elastic.co/guide/en/elasticsearch/reference/current/_configure_privileges_for_cross_cluster_replication_2.html applies_to: - deployment: - eck: - ess: - ece: - self: + stack: all + products: - id: elasticsearch --- -# Configure privileges for cross-cluster replication [_configure_privileges_for_ccr_2] +# Configure privileges for {{ccr}} [_configure_privileges_for_ccr_2] -The {{ccr}} user requires different cluster and index privileges on the remote cluster and local cluster. Use the following requests to create separate roles on the local and remote clusters, and then create a user with the required roles. +To use a [remote cluster](/deploy-manage/remote-clusters.md) for {{ccr}}, you need to configure user roles with the correct cluster and index privileges. The steps depend on the [remote cluster security model](/deploy-manage/remote-clusters/security-models.md) in use: +* [API key authentication](#configure-privileges-for-ccr-api-key) (recommended), where you create roles with the required privileges on the local cluster. +* {applies_to}`stack: deprecated 9.0` [TLS certificate authentication](#configure-privileges-for-ccr-cert), where you create matching roles on both the local and remote clusters. -## Remote cluster [_remote_cluster_4] +You can manage roles in {{kib}} on the **Roles** page in the navigation menu or use the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md). You can also use the [role management]({{es-apis}}group/endpoint-security) APIs to add, update, remove, and retrieve roles dynamically. 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. For more information, refer to [Defining roles](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md). -On the remote cluster that contains the leader index, the {{ccr}} role requires the `read_ccr` cluster privilege, and `monitor` and `read` privileges on the leader index. +The following examples use the [create or update roles]({{es-apis}}operation/operation-security-put-role) API and the [create or update users]({{es-apis}}operation/operation-security-put-user) API. You must have at least the `manage_security` [cluster privilege](elasticsearch://reference/elasticsearch/security-privileges.md#privileges-list-cluster) to use these APIs. -::::{note} -If requests are authenticated with an [API key]({{es-apis}}operation/operation-security-create-api-key), the API key requires the above privileges on the **local** cluster, instead of the remote. -:::: +## API key authentication [configure-privileges-for-ccr-api-key] +Authorization for {{ccr}} works in two parts: -::::{note} -If requests are issued [on behalf of other users](../../users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md), then the authenticating user must have the `run_as` privilege on the remote cluster. -:::: +* The [cross-cluster API key](/deploy-manage/remote-clusters/remote-clusters-api-key.md) used to connect to a remote cluster defines the maximum access that cluster allows. +* Roles on the local cluster 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) further limit which remote indices each user can replicate. + +To grant a user {{ccr}} access, you create a role on the local cluster, assign it the `manage_ccr` [cluster privilege](elasticsearch://reference/elasticsearch/security-privileges.md#privileges-list-cluster) and the `cross_cluster_replication` [index privilege](elasticsearch://reference/elasticsearch/security-privileges.md#privileges-list-indices) for the remote cluster alias and leader index, then assign that role to the user. +:::{note} +The cross-cluster API key used by the local cluster to connect the remote cluster must have sufficient privileges to cover all remote indices privileges required by individual users. +::: + +Assuming the remote cluster is connected under the name of `my_remote_cluster`, the following request creates a role called `remote-replication` on the local cluster that allows replicating the remote `leader-index` index: + +```console +POST /_security/role/remote-replication +{ + "cluster": [ + "manage_ccr" + ], + "remote_indices": [ + { + "clusters": [ "my_remote_cluster" ], + "names": [ + "leader-index" + ], + "privileges": [ + "cross_cluster_replication" + ] + } + ] +} +``` + +After creating the local `remote-replication` role, use the [create or update users]({{es-apis}}operation/operation-security-put-user) API to create a user on the local cluster and assign the `remote-replication` role. For example, the following request assigns the `remote-replication` role to a user named `cross-cluster-user`: + +```console +POST /_security/user/cross-cluster-user +{ + "password" : "l0ng-r4nd0m-p@ssw0rd", + "roles" : [ "remote-replication" ] +} +``` + +Note that you only need to create this user on the local cluster. + +You can then [configure {{ccr}}](set-up-cross-cluster-replication.md) to replicate your data across datacenters. + +## TLS certificate authentication [configure-privileges-for-ccr-cert] +```{applies_to} +stack: deprecated 9.0 +``` + +:::{warning} + +Certificate based authentication is deprecated. Configure [API key authentication](/deploy-manage/remote-clusters/remote-clusters-api-key.md) instead or follow a guide on how to [migrate remote clusters from certificate to API key authentication](/deploy-manage/remote-clusters/remote-clusters-migrate.md). +::: + +After [connecting remote clusters](/deploy-manage/remote-clusters/remote-clusters-self-managed.md), create a user role on both the local and remote clusters and assign the necessary privileges. + +:::{important} +You must use the same role names on both the local and remote clusters. For example, the following configuration uses the `remote-replication` role name on both clusters. However, you can specify different role definitions on each cluster. +::: + +### Remote cluster [_remote_cluster_4] + +On the remote cluster that contains the leader index, the {{ccr}} role requires the `read_ccr` [cluster privilege](elasticsearch://reference/elasticsearch/security-privileges.md#privileges-list-cluster), and `monitor` and `read` [index privileges](elasticsearch://reference/elasticsearch/security-privileges.md#privileges-list-indices) on the leader index. + +:::{note} +If requests are issued [on behalf of other users](/deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md), then the authenticating user must have the [`run_as` privilege](elasticsearch://reference/elasticsearch/security-privileges.md#_run_as_privilege). +::: The following request creates a `remote-replication` role on the remote cluster: @@ -52,10 +114,9 @@ POST /_security/role/remote-replication } ``` +### Local cluster [_local_cluster_4] -## Local cluster [_local_cluster_4] - -On the local cluster that contains the follower index, the `remote-replication` role requires the `manage_ccr` cluster privilege, and `monitor`, `read`, `write`, and `manage_follow_index` privileges on the follower index. +On the local cluster that contains the follower index, the `remote-replication` role requires the `manage_ccr` [cluster privilege](elasticsearch://reference/elasticsearch/security-privileges.md#privileges-list-cluster), and `monitor`, `read`, `write`, and `manage_follow_index` [index privileges](elasticsearch://reference/elasticsearch/security-privileges.md#privileges-list-indices) on the follower index. The following request creates a `remote-replication` role on the local cluster: @@ -81,7 +142,7 @@ POST /_security/role/remote-replication } ``` -After creating the `remote-replication` role on each cluster, use the [create or update users API]({{es-apis}}operation/operation-security-put-user) to create a user on the local cluster and assign the `remote-replication` role. For example, the following request assigns the `remote-replication` role to a user named `cross-cluster-user`: +After creating the `remote-replication` role on each cluster, use the [create or update users]({{es-apis}}operation/operation-security-put-user) API to create a user on the local cluster and assign the `remote-replication` role. For example, the following request assigns the `remote-replication` role to a user named `cross-cluster-user`: ```console POST /_security/user/cross-cluster-user @@ -94,3 +155,5 @@ POST /_security/user/cross-cluster-user ::::{note} You only need to create this user on the **local** cluster. :::: + +You can then [configure {{ccr}}](set-up-cross-cluster-replication.md) to replicate your data across datacenters. diff --git a/explore-analyze/cross-cluster-search.md b/explore-analyze/cross-cluster-search.md index 8071ece3ca..81e061159d 100644 --- a/explore-analyze/cross-cluster-search.md +++ b/explore-analyze/cross-cluster-search.md @@ -36,7 +36,7 @@ The following APIs support {{ccs}}: ## Prerequisites [_prerequisites] -* {{ccs-cap}} requires remote clusters. To set up remote clusters, see [*Remote clusters*](/deploy-manage/remote-clusters.md). +* {{ccs-cap}} requires remote clusters. To set up remote clusters, see [Remote clusters](/deploy-manage/remote-clusters.md). To ensure your remote cluster configuration supports {{ccs}}, see [Supported {{ccs}} configurations](#ccs-supported-configurations). @@ -49,7 +49,204 @@ The following APIs support {{ccs}}: * If you use [proxy mode](/deploy-manage/remote-clusters/remote-clusters-self-managed.md#proxy-mode), the local coordinating node must be able to connect to the configured `proxy_address`. The proxy at this address must be able to route connections to gateway and coordinating nodes on the remote cluster. -* {{ccs-cap}} requires different security privileges on the local cluster and remote cluster. See [Configure privileges for {{ccs}}](/deploy-manage/remote-clusters/remote-clusters-cert.md#remote-clusters-privileges-ccs) and [*Remote clusters*](/deploy-manage/remote-clusters.md). +* {{ccs-cap}} requires different security privileges on the local cluster and remote cluster. Refer to [Configure privileges](#configure-privileges-for-ccs) for details. + + +## Configure privileges for {{ccs}} [configure-privileges-for-ccs] + +After [remote clusters are connected](/deploy-manage/remote-clusters.md), you can configure which users on your local cluster can search data on remote clusters. The steps depend on the [remote cluster security model](/deploy-manage/remote-clusters/security-models.md) in use: + +* [API key authentication](#configure-privileges-for-ccs-api-key) (recommended), where you create roles with the required privileges on the local cluster. +* {applies_to}`stack: deprecated 9.0` [TLS certificate authentication](#configure-privileges-for-ccs-cert), where you create matching roles on both the local and remote clusters. + +You can manage roles in {{kib}} on the **Roles** page in the navigation menu or use the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md). You can also use the [role management]({{es-apis}}group/endpoint-security) APIs to add, update, remove, and retrieve roles dynamically. 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. For more information, refer to [Defining roles](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md). + +The following examples use the [create or update roles]({{es-apis}}operation/operation-security-put-role) API and the [create or update users]({{es-apis}}operation/operation-security-put-user) API. You must have at least the `manage_security` [cluster privilege](elasticsearch://reference/elasticsearch/security-privileges.md#privileges-list-cluster) to use these APIs. + +### API key authentication [configure-privileges-for-ccs-api-key] + +Authorization for {{ccs}} works in two parts: + +* The [cross-cluster API key](/deploy-manage/remote-clusters/remote-clusters-api-key.md) used to connect to a remote cluster defines the maximum access that cluster allows. +* Roles on the local cluster 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) further limit which remote indices each user can search. + +To grant a user {{ccs}} access, create a role on the local cluster, assign it the required privileges for the remote cluster alias and target indices, then assign that role to the user. + +::::{note} +The cross-cluster API key used by the local cluster to connect the remote cluster must have sufficient privileges to cover all remote indices privileges required by individual users. +:::: + +Assuming the remote cluster is connected under the name of `my_remote_cluster`, the following request creates a `remote-search` role on the local cluster that allows searching the remote `target-index` index: + +```console +POST /_security/role/remote-search +{ + "remote_indices": [ + { + "clusters": [ "my_remote_cluster" ], + "names": [ + "target-index" + ], + "privileges": [ + "read", + "read_cross_cluster", + "view_index_metadata" + ] + } + ] +} +``` + +After creating the `remote-search` role, use the [create or update users]({{es-apis}}operation/operation-security-put-user) API to create a user on the local cluster and assign the `remote-search` role. For example, the following request assigns the `remote-search` role to a user named `cross-search-user`: + +```console +POST /_security/user/cross-search-user +{ + "password" : "l0ng-r4nd0m-p@ssw0rd", + "roles" : [ "remote-search" ] +} +``` + +::::{note} +You only need to create this user on the **local** cluster. +:::: + +### TLS certificate authentication [configure-privileges-for-ccs-cert] +```{applies_to} +stack: deprecated 9.0 +``` + +::::{warning} + +Certificate based authentication is deprecated. Configure [API key authentication](/deploy-manage/remote-clusters/remote-clusters-api-key.md) instead or follow a guide on how to [migrate remote clusters from certificate to API key authentication](/deploy-manage/remote-clusters/remote-clusters-migrate.md). +:::: + +After [connecting remote clusters](/deploy-manage/remote-clusters/remote-clusters-self-managed.md), create a user role on both the local and remote clusters and assign the necessary privileges. + +::::{important} +You must use the same role names on both the local and remote clusters. For example, the following configuration uses the `remote-search` role name on both clusters. However, you can specify different role definitions on each cluster. +:::: + +#### Remote cluster [configure-privileges-for-ccs-cert-remote] + +On the remote cluster, the {{ccs}} role requires the `read` and `read_cross_cluster` [index privileges](elasticsearch://reference/elasticsearch/security-privileges.md#privileges-list-indices) for the target indices. + +::::{note} +If requests are issued [on behalf of other users](/deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users.md), then the authenticating user must have the [`run_as` privilege](elasticsearch://reference/elasticsearch/security-privileges.md#_run_as_privilege) on the remote cluster. +:::: + +The following request creates a `remote-search` role on the remote cluster: + +```console +POST /_security/role/remote-search +{ + "indices": [ + { + "names": [ + "target-indices" + ], + "privileges": [ + "read", + "read_cross_cluster" + ] + } + ] +} +``` + +#### Local cluster [configure-privileges-for-ccs-cert-local] + +On the local cluster, which is the cluster used to initiate cross cluster search, a user only needs the `remote-search` role. The role privileges can be empty. + +The following request creates a `remote-search` role on the local cluster: + +```console +POST /_security/role/remote-search +{} +``` + +After creating the `remote-search` role on each cluster, use the [create or update users]({{es-apis}}operation/operation-security-put-user) API to create a user on the local cluster and assign the `remote-search` role. For example, the following request assigns the `remote-search` role to a user named `cross-search-user`: + +```console +POST /_security/user/cross-search-user +{ + "password" : "l0ng-r4nd0m-p@ssw0rd", + "roles" : [ "remote-search" ] +} +``` + +::::{note} +You only need to create this user on the **local** cluster. +:::: + +#### {{kib}} users [configure-privileges-for-ccs-kibana-cert] + +When using {{kib}} to search across multiple clusters, a two-step authorization process determines whether the user can access data streams and indices on a remote cluster: + +* First, the local cluster determines if the user is authorized to access remote clusters. The local cluster is the cluster that {{kib}} is connected to. +* If the user is authorized, the remote cluster then determines if the user has access to the specified data streams and indices. + +To grant {{kib}} users access to remote clusters, assign them a local role with read privileges to indices on the remote clusters. You specify data streams and indices in a remote cluster as `:`. + +To grant users read access on the remote data streams and indices, you must create a matching role on the remote clusters that grants the `read_cross_cluster` privilege with access to the appropriate data streams and indices. + +For example, you might be actively indexing {{ls}} data on a local cluster and periodically offload older time-based indices to an archive on your remote cluster. You want to search across both clusters, so you must enable {{kib}} users on both clusters. + +On the local cluster, create a `logstash-reader` role that grants `read` and `view_index_metadata` privileges on the local `logstash-*` indices. + +::::{note} +If you configure the local cluster as another remote in {{es}}, the `logstash-reader` role on your local cluster also needs to grant the `read_cross_cluster` privilege. +:::: + +```console +POST /_security/role/logstash-reader +{ + "indices": [ + { + "names": [ + "logstash-*" + ], + "privileges": [ + "read", + "view_index_metadata" + ] + } + ] +} +``` + +Assign your {{kib}} users a role that grants [access to {{kib}}](elasticsearch://reference/elasticsearch/roles.md), as well as your `logstash-reader` role. For example, the following request creates the `cross-cluster-kibana` user and assigns the `kibana-access` and `logstash-reader` roles. + +```console +PUT /_security/user/cross-cluster-kibana +{ + "password" : "l0ng-r4nd0m-p@ssw0rd", + "roles" : [ + "logstash-reader", + "kibana-access" + ] +} +``` + +On the remote cluster, create a `logstash-reader` role that grants the `read_cross_cluster` privilege and `read` and `view_index_metadata` privileges for the `logstash-*` indices. + +```console +POST /_security/role/logstash-reader +{ + "indices": [ + { + "names": [ + "logstash-*" + ], + "privileges": [ + "read_cross_cluster", + "read", + "view_index_metadata" + ] + } + ] +} +``` ## {{ccs-cap}} examples [ccs-example] diff --git a/explore-analyze/report-and-share/automating-report-generation.md b/explore-analyze/report-and-share/automating-report-generation.md index 5ca533bae5..e42fb462b9 100644 --- a/explore-analyze/report-and-share/automating-report-generation.md +++ b/explore-analyze/report-and-share/automating-report-generation.md @@ -16,7 +16,7 @@ To automatically generate PDF and CSV reports, generate a POST URL, then submit :applies_to: {stack: ga 9.1, serverless: unavailable} Report generation requests are authenticated by API keys instead of session cookies. There are several key differences between the authentication methods. API keys capture your role privileges, whereas session cookie are based on your user credentials. API keys are also longer-lived, compared to session cookies, which have a shorter lifespan. -If you have a cross-cluster search environment and want to generate reports from remote clusters, you must have the appropriate cluster and index privileges on the remote cluster and local cluster. For example, if requests are authenticated with an API key, the API key requires certain privileges on the local cluster that contains the local index, in addition to the remote. For more information and examples, refer to [Configure roles and users for remote clusters](../../deploy-manage/remote-clusters/remote-clusters-cert.md#remote-clusters-privileges-cert). +If you have a cross-cluster search environment and want to generate reports from remote clusters, you must have the appropriate cluster and index privileges on the remote cluster and local cluster. For example, if requests are authenticated with an API key, the API key requires certain privileges on the local cluster that contains the local index, in addition to the remote. For more information and examples, refer to [Configure privileges for cross-cluster search](/explore-analyze/cross-cluster-search.md#configure-privileges-for-ccs). ::: ## Create a POST URL [create-a-post-url] diff --git a/redirects.yml b/redirects.yml index 3283295428..8beab16afe 100644 --- a/redirects.yml +++ b/redirects.yml @@ -904,3 +904,38 @@ redirects: - to: 'explore-analyze/ai-features/agent-builder/agent-builder-agents.md' anchors: 'enable-elastic-capabilities': 'elastic-capabilities' + + # Rehome CCS and CCR privileges from remote-clusters-cert.md + 'deploy-manage/remote-clusters/remote-clusters-cert.md': + to: 'deploy-manage/remote-clusters/remote-clusters-cert.md' + many: + - to: 'deploy-manage/tools/cross-cluster-replication/_configure_privileges_for_cross_cluster_replication_2.md' + anchors: + 'remote-clusters-privileges-ccr': 'configure-privileges-for-ccr-cert' + '_remote_cluster': '_remote_cluster_4' + '_local_cluster': '_local_cluster_4' + - to: 'explore-analyze/cross-cluster-search.md' + anchors: + 'remote-clusters-privileges-ccs': 'configure-privileges-for-ccs-cert' + 'clusters-privileges-ccs-kibana-cert': 'configure-privileges-for-ccs-kibana-cert' + '_remote_cluster_2': 'configure-privileges-for-ccs-cert-remote' + '_local_cluster_2': 'configure-privileges-for-ccs-cert-local' + '_local_cluster_3': 'configure-privileges-for-ccs-kibana-cert' + '_remote_cluster_3': 'configure-privileges-for-ccs-kibana-cert' + + # Rehome CCS and CCR API key privileges from remote-clusters-api-key.md + 'deploy-manage/remote-clusters/remote-clusters-api-key.md': + to: 'deploy-manage/remote-clusters/remote-clusters-api-key.md' + many: + - to: 'deploy-manage/tools/cross-cluster-replication/_configure_privileges_for_cross_cluster_replication_2.md' + anchors: + '_configure_privileges_for_ccr': 'configure-privileges-for-ccr-api-key' + - to: 'explore-analyze/cross-cluster-search.md' + anchors: + '_configure_privileges_for_ccs': 'configure-privileges-for-ccs-api-key' + + # Redirect removed CCS privileges child page + 'explore-analyze/cross-cluster-search/configure-privileges-for-cross-cluster-search.md': + to: 'explore-analyze/cross-cluster-search.md' + anchors: + '': 'configure-privileges-for-ccs' diff --git a/solutions/security/detect-and-alert/cross-cluster-search-detection-rules.md b/solutions/security/detect-and-alert/cross-cluster-search-detection-rules.md index c6270b70c2..b941126f3f 100644 --- a/solutions/security/detect-and-alert/cross-cluster-search-detection-rules.md +++ b/solutions/security/detect-and-alert/cross-cluster-search-detection-rules.md @@ -27,7 +27,7 @@ This section explains the general process for setting up cross-cluster search in * [Add remote clusters using API key authentication](../../../deploy-manage/remote-clusters/remote-clusters-api-key.md) * [Add remote clusters using TLS certificate authentication](../../../deploy-manage/remote-clusters/remote-clusters-cert.md) -2. On both the local and remote clusters, [create a role for cross-cluster search privileges](../../../deploy-manage/remote-clusters/remote-clusters-cert.md#clusters-privileges-ccs-kibana-cert), and make sure the two roles have *identical* names. Assign each role the following privileges: +2. On both the local and remote clusters, [create a role for {{ccs}} privileges](/explore-analyze/cross-cluster-search.md#configure-privileges-for-ccs-cert), and make sure the two roles have *identical* names. Assign each role the following privileges: 1. **Local cluster role**: Assign the `read` privilege to the indices you want to search, using *both* the local and remote index patterns for each index. To specify a remote index, use the pattern `:`.