Skip to content

Rehome CCS/CCR permissions #6934

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
yetanothertw wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Rehome CCS/CCR permissions #6934

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4306a1a
Rehome CCS/CCR permissions
yetanothertw Jun 16, 2026
1711d98
Fix link to be more direct to the section for TLS certs
yetanothertw Jun 17, 2026
8132bb3
Apply some feedback from the docs-review action
yetanothertw Jun 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion deploy-manage/kibana-reporting-configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion deploy-manage/remote-clusters/_snippets/configure-roles-and-users.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
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).

@eedugon eedugon Jun 17, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What if we divide the content in 3 paragraphs?

1st) If you are using the API-key based authentication....

2nd) If you are using TLS certificates-based authentication (with a super short explanation of how a role with the same name must exist in both local and remote clusters).

3rd) For more details, refer to....

Also please note that on the first paragraph I'd love to find an alternative to to further restrict the permissions granted by the API key. I believe it's not 100% like that. The effective permissions are the intersection between the API key used for connecting the clusters, and the remote privileges of the user. If the user (not superuser) doesn't have remote privileges they wouldn't be able to access the remote cluster data, so that means that the role is not just to restrict further the privileges.... I'd say something like:

If you're using the API key–based security model for {{ccr}} or {{ccs}}, you can define user roles with remote indices privileges on the local cluster to specify permissions on remote resources.
(or something equivalent. If you find it useful to say something about the effective permissions, or that the permissions provided by the role cannot exceed the API key permissions that would also be OK!)

I know that original sentence wasn't yours, maybe it was mine :)

84 changes: 3 additions & 81 deletions deploy-manage/remote-clusters/remote-clusters-api-key.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
244 changes: 3 additions & 241 deletions deploy-manage/remote-clusters/remote-clusters-cert.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<remote_cluster_name>:<target>`.

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)
2 changes: 1 addition & 1 deletion deploy-manage/remote-clusters/remote-clusters-migrate.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Loading
Loading