Configure privileges for cross-cluster replication

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 on the remote cluster security model in use:

• API key authentication (recommended), where you create roles with the required privileges on the local cluster.
• TLS certificate authentication, 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. You can also use the role management 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.

The following examples use the create or update roles API and the create or update users API. You must have at least the manage_security cluster privilege to use these APIs.

Authorization works in two parts:

• The cross-cluster 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 or remote cluster privileges 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.

To grant a user cross-cluster replication access, you create a role on the local cluster, assign it the manage_ccr cluster privilege and the cross_cluster_replication index privilege 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:

				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 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:

				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 cross-cluster replication to replicate your data across datacenters.

After connecting remote clusters, 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.

On the remote cluster that contains the leader index, the cross-cluster replication role requires the read_ccr cluster privilege, and monitor and read index privileges on the leader index.

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

				POST /_security/role/remote-replication
					{
  "cluster": [
    "read_ccr"
  ],
  "indices": [
    {
      "names": [
        "leader-index-name"
      ],
      "privileges": [
        "monitor",
        "read"
      ]
    }
  ]
}
		

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 index privileges on the follower index.

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

				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 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:

				POST /_security/user/cross-cluster-user
					{
  "password" : "l0ng-r4nd0m-p@ssw0rd",
  "roles" : [ "remote-replication" ]
}
		

You can then configure cross-cluster replication to replicate your data across datacenters.