---
title: Configure privileges for cross-cluster replication
description: To use a remote cluster for cross-cluster replication, you need to configure user roles with the correct cluster and index privileges. The steps depend...
url: https://www.elastic.co/docs/deploy-manage/tools/cross-cluster-replication/_configure_privileges_for_cross_cluster_replication_2
products:
  - Elastic Documentation
  - Elasticsearch
applies_to:
  - Elastic Stack: Generally available
---

# Configure privileges for cross-cluster replication
To use a [remote cluster](https://www.elastic.co/docs/deploy-manage/remote-clusters) for cross-cluster replication, you need to configure user roles with the correct cluster and index privileges. The steps depend on the [remote cluster security model](https://www.elastic.co/docs/deploy-manage/remote-clusters/security-models) 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>Elastic Stack: Deprecated since 9.0</applies-to> [TLS certificate authentication](#configure-privileges-for-ccr-cert), where you create matching roles on both the local and remote clusters.

You can manage roles in Kibana on the **Roles** page in the navigation menu or use the [global search field](https://www.elastic.co/docs/explore-analyze/find-and-organize/find-apps-and-objects). You can also use the [role management](https://www.elastic.co/docs/api/doc/elasticsearch/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 Elasticsearch index. When you use local files, the roles are only stored in those files. For more information, refer to [Defining roles](https://www.elastic.co/docs/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles).
The following examples use the [create or update roles](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-put-role) API and the [create or update users](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-put-user) API. You must have at least the `manage_security` [cluster privilege](https://docs-demo.elastic.dev/docs/reference/elasticsearch/security-privileges#privileges-list-cluster) to use these APIs.
<note>
  The role examples on this page use the `manage_ccr` cluster privilege on the local cluster because it is the minimum cluster privilege required to manage CCR. If a user already has a role that grants a broader cluster privilege covering these operations, such as `manage` or `all`, you don't need to grant `manage_ccr` separately. Regardless of which cluster privilege you use, you must still grant the required index privileges.
</note>


## API key authentication

Authorization works in two parts:
- The [cross-cluster API key](https://www.elastic.co/docs/deploy-manage/remote-clusters/remote-clusters-api-key) 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](/docs/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure#roles-remote-indices-priv) or [remote cluster privileges](/docs/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure#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.
</note>

To grant a user cross-cluster replication access, you create a role on the local cluster, assign it the `manage_ccr` [cluster privilege](https://docs-demo.elastic.dev/docs/reference/elasticsearch/security-privileges#privileges-list-cluster) and the `cross_cluster_replication` [index privilege](https://docs-demo.elastic.dev/docs/reference/elasticsearch/security-privileges#privileges-list-indices) for the remote cluster alias and leader index, 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 role called `remote-replication` on the local cluster that allows replicating the remote `leader-index` index:
```json

{
  "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](https://www.elastic.co/docs/api/doc/elasticsearch/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`:
```json

{
  "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 cross-cluster replication](https://www.elastic.co/docs/deploy-manage/tools/cross-cluster-replication/set-up-cross-cluster-replication) to replicate your data across datacenters.

## TLS certificate authentication

<applies-to>
  - Elastic Stack: Deprecated since 9.0
</applies-to>

<warning>
  Certificate based authentication is deprecated. Configure [API key authentication](https://www.elastic.co/docs/deploy-manage/remote-clusters/remote-clusters-api-key) instead or follow a guide on how to [migrate remote clusters from certificate to API key authentication](https://www.elastic.co/docs/deploy-manage/remote-clusters/remote-clusters-migrate).
</warning>

After [connecting remote clusters](https://www.elastic.co/docs/deploy-manage/remote-clusters/remote-clusters-self-managed), 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.
</important>


### Remote cluster

On the remote cluster that contains the leader index, the cross-cluster replication role requires the `read_ccr` [cluster privilege](https://docs-demo.elastic.dev/docs/reference/elasticsearch/security-privileges#privileges-list-cluster), and `monitor` and `read` [index privileges](https://docs-demo.elastic.dev/docs/reference/elasticsearch/security-privileges#privileges-list-indices) on the leader index.
<note>
  If requests are issued [on behalf of other users](https://www.elastic.co/docs/deploy-manage/users-roles/cluster-or-deployment-auth/submitting-requests-on-behalf-of-other-users), then the authenticating user must have the [`run_as` privilege](https://docs-demo.elastic.dev/docs/reference/elasticsearch/security-privileges#_run_as_privilege).
</note>

The following request creates a `remote-replication` role on the remote cluster:
```json

{
  "cluster": [
    "read_ccr"
  ],
  "indices": [
    {
      "names": [
        "leader-index-name"
      ],
      "privileges": [
        "monitor",
        "read"
      ]
    }
  ]
}
```


### Local cluster

On the local cluster that contains the follower index, the `remote-replication` role requires the `manage_ccr` [cluster privilege](https://docs-demo.elastic.dev/docs/reference/elasticsearch/security-privileges#privileges-list-cluster), and `monitor`, `read`, `write`, and `manage_follow_index` [index privileges](https://docs-demo.elastic.dev/docs/reference/elasticsearch/security-privileges#privileges-list-indices) on the follower index.
The following request creates a `remote-replication` role on the local cluster:
```json

{
  "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](https://www.elastic.co/docs/api/doc/elasticsearch/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`:
```json

{
  "password" : "l0ng-r4nd0m-p@ssw0rd",
  "roles" : [ "remote-replication" ]
}
```

<note>
  You only need to create this user on the **local** cluster.
</note>

You can then [configure cross-cluster replication](https://www.elastic.co/docs/deploy-manage/tools/cross-cluster-replication/set-up-cross-cluster-replication) to replicate your data across datacenters.