[[remote-clusters-privileges-api-key]]
=== Configure roles and users

To use a remote cluster for {ccr} or {ccs}, you need to create user roles with
<<roles-remote-indices-priv,remote indices privileges>> on the local cluster.

You can manage users and roles from Stack Management in {kib} by selecting
*Security > Roles* from the side navigation. You can also use the
<<security-role-apis,role management APIs>> to add, update, remove, and retrieve
roles dynamically.

The following examples use the <<security-api-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}

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:

[source,console]
----
POST /_security/role/remote-replication
{
  "cluster": [
    "manage_ccr"
  ],
  "remote_indices": [
    {
      "clusters": [ "my_remote_cluster" ],
      "names": [
        "leader-index"
      ],
      "privileges": [
        "cross_cluster_replication"
      ]
    }
  ]
}
----
// TEST[skip:TODO]

After creating the local `remote-replication` role, use the
<<security-api-put-user>> API to create a user on the local cluster cluster and
assign the `remote-replication` role. For example, the following request assigns
the `remote-replication` role to a user named `cross-cluster-user`:

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

Note that you only need to create this user on the local cluster.

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

[source,console]
----
POST /_security/role/remote-search
{
  "remote_indices": [
    {
      "clusters": [ "my_remote_cluster" ],
      "names": [
        "target-index"
      ],
      "privileges": [
        "read",
        "read_cross_cluster",
        "view_index_metadata" 
      ]
    }
  ]
}

----
// TEST[skip:TODO]

After creating the `remote-search` role, use the <<security-api-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`:

[source,console]
----
POST /_security/user/cross-search-user
{
  "password" : "l0ng-r4nd0m-p@ssw0rd",
  "roles" : [ "remote-search" ]
}
----
// TEST[skip:TODO]

Note that you only need to create this user on the local cluster.