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/allow-connection-intro.md b/deploy-manage/remote-clusters/_snippets/allow-connection-intro.md index ef1f9f237f..f95d13f206 100644 --- a/deploy-manage/remote-clusters/_snippets/allow-connection-intro.md +++ b/deploy-manage/remote-clusters/_snippets/allow-connection-intro.md @@ -17,7 +17,7 @@ This snippet is in use in the following locations: Before you start, consider the [security model](/deploy-manage/remote-clusters/security-models.md) that you would prefer to use for authenticating remote connections between clusters, and follow the corresponding steps. API key -: For deployments based on {{stack}} 8.14 or later, you can use an API key to authenticate and authorize cross-cluster operations to a remote cluster. This model uses a dedicated service endpoint, on port `9443` by default, and gives administrators fine-grained control over remote access. The API key is created on the remote cluster and defines the permissions available to all cross-cluster requests, while local user roles can further restrict, but not extend, those permissions. +: For deployments based on {{stack}} 8.14 or later, you can use an API key to authenticate and authorize cross-cluster operations to a remote cluster. This model uses a dedicated service endpoint, on port `9443` by default, and gives administrators fine-grained control over remote access. The API key is created on the remote cluster and defines the maximum privileges that any user can exercise on remote clusters. Local user roles with remote privileges grant access to specific users and they cannot extend API key permissions. By default users have no remote privileges unless they are superusers or are assigned such a role. Starting with {{stack}} 9.3, the API key security model also supports [strong identity verification](/deploy-manage/remote-clusters/security-models.md#remote-cluster-strong-verification), adding an extra layer of security. With this feature, the API key can be restricted to only be usable by requests that present an allowed certificate identity, which the remote cluster validates during authentication. diff --git a/deploy-manage/remote-clusters/_snippets/configure-privileges-api-key-authorization.md b/deploy-manage/remote-clusters/_snippets/configure-privileges-api-key-authorization.md new file mode 100644 index 0000000000..4aff06c6b2 --- /dev/null +++ b/deploy-manage/remote-clusters/_snippets/configure-privileges-api-key-authorization.md @@ -0,0 +1,16 @@ + + +Authorization 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 privileges that any user can exercise on remote clusters. This key is created and configured when you configure the remote cluster. +* 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) grant remote access to specific users. + +By default, users have no remote privileges unless they are superusers or are assigned a role that includes remote privileges. A user's effective access is the intersection of their role privileges and the API key privileges. + +:::{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. +::: diff --git a/deploy-manage/remote-clusters/_snippets/configure-privileges-role-management.md b/deploy-manage/remote-clusters/_snippets/configure-privileges-role-management.md new file mode 100644 index 0000000000..b2f73c70a6 --- /dev/null +++ b/deploy-manage/remote-clusters/_snippets/configure-privileges-role-management.md @@ -0,0 +1,9 @@ + + +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. 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..30624bbcfa 100644 --- a/deploy-manage/remote-clusters/_snippets/configure-roles-and-users.md +++ b/deploy-manage/remote-clusters/_snippets/configure-roles-and-users.md @@ -15,6 +15,9 @@ This snippet is in use in the following locations: - ec-remote-cluster-ece.md - ec-enable-ccs-for-eck.md --> -% 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}}, the [cross-cluster API key](/deploy-manage/remote-clusters/remote-clusters-api-key.md) used to connect to a remote cluster defines the maximum privileges that any user can exercise on that remote cluster. Define 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 grant remote access to specific users. By default, users have no remote privileges unless they are superusers or are assigned a role that includes remote privileges. + +If you're using TLS certificate–based authentication, create roles with the same name on both the local and remote clusters. Each cluster defines its own role privileges, but the names must match so that authorization is enforced on both sides of the connection. + +For more details, refer to [Configure privileges for {{ccr}}](/deploy-manage/tools/cross-cluster-replication/_configure_privileges_for_cross_cluster_replication_2.md) and [Configure privileges for {{ccs}}](/explore-analyze/cross-cluster-search.md#configure-privileges-for-ccs). 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..ba705441cf 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,88 @@ 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] +:::{include} /deploy-manage/remote-clusters/_snippets/configure-privileges-role-management.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. +## API key authentication [configure-privileges-for-ccr-api-key] -::::{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. -:::: +:::{include} /deploy-manage/remote-clusters/_snippets/configure-privileges-api-key-authorization.md +::: +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} -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. -:::: +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 matching user roles on both the local and remote clusters and assign the necessary privileges. With TLS-based authentication, the local user's role names are forwarded to the remote cluster, which authorizes the request by evaluating roles with the same names defined locally. + +:::{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 +107,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 +135,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 +148,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..2b792645b9 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,131 @@ 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 remote 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. + +:::{include} /deploy-manage/remote-clusters/_snippets/configure-privileges-role-management.md +::: + +### API key authentication [configure-privileges-for-ccs-api-key] + +:::{include} /deploy-manage/remote-clusters/_snippets/configure-privileges-api-key-authorization.md +::: + +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. + +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 and role on the **local** cluster. + +The same user can hold multiple roles, or a single role can combine [remote indices privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-indices-priv) with local index privileges and {{kib}} access roles. +::: + +### 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 matching user roles on both the local and remote clusters and assign the necessary privileges. With TLS-based authentication, the local user's role names are forwarded to the remote cluster, which authorizes the request by evaluating roles with the same names defined locally. + +:::{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, assign users the `remote-search` role. If users only need remote access, you can leave the local role empty. If they also need to query local indices or use {{kib}}, grant the required local privileges in the same role or assign the user additional roles. + +The following request creates a `remote-search` role on the local cluster with no privileges: + +```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. +::: ## {{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..cab275519a 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-cert-local' + '_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-cert-local' + '_remote_cluster_3': 'configure-privileges-for-ccs-cert-remote' + + # 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 `:`.