[[cross-cluster-configuring]]
=== Cross Cluster Search and Security

{ref}/modules-cross-cluster-search.html[Cross Cluster Search] enables
federated search across multiple clusters. When using cross cluster search
with secured clusters, all clusters must have {security} enabled.

The local cluster (the cluster used to initiate cross cluster search) must be
allowed to connect to the remote clusters, which means that the CA used to
sign the SSL/TLS key of the local cluster must be trusted by the remote
clusters.

User authentication is performed on the local cluster and the user and user's
roles are passed to the remote clusters. A remote cluster checks the user's
roles against its local role definitions to determine which indices the user
is allowed to access.


[WARNING]
This feature was added as Beta in Elasticsearch `v5.3` with further
improvements made in 5.4 and 5.5. It requires gateway eligible nodes to be on
`v5.5` onwards.

To use cross cluster search with secured clusters:

* Install {xpack} on every node in each connected cluster.

* Enable encryption globally. To encrypt communications, you must enable
  <<ssl-tls,enable SSL/TLS>> on every node.

* Enable a trust relationship between the cluster used for performing cross
  cluster search (the local cluster) and all remote clusters.  This can be done
  either by:
+
  ** Using the same certificate authority to generate certificates for all
    connected clusters, or
  ** Adding the CA certificate from the local cluster as a trusted CA in
    each remote cluster (see {ref}/security-settings.html#transport-tls-ssl-settings[Transport TLS settings]).

* Configure the local cluster to connect to remote clusters as described
  in {ref}/modules-cross-cluster-search.html#_configuring_cross_cluster_search[Configuring Cross Cluster Search].
  For example, the following configuration adds two remote clusters
  to the local cluster:
+
[source,js]
-----------------------------------------------------------
PUT _cluster/settings
{
  "persistent": {
    "search": {
      "remote": {
        "cluster_one": {
          "seeds": [ "10.0.1.1:9300" ]
        },
        "cluster_two": {
          "seeds": [ "10.0.2.1:9300" ]
        }
      }
    }
  }
}
-----------------------------------------------------------

* On the local cluster, ensure that users are assigned to (at least) one role
  that exists on the remote clusters.  On the remote clusters, use that role
  to define which indices the user may access.  (See <<authorization>>).

==== Example Configuration of Cross Cluster Search

In the following example, we will configure the user `alice` to have permissions
to search any index starting with `logs-` in cluster `two` from cluster `one`.

First, enable cluster `one` to perform cross cluster search on remote cluster
`two` by running the following request as the superuser on cluster `one`:

[source,js]
-----------------------------------------------------------
PUT _cluster_settings
{
  "persistent": {
    "search.remote.two.seeds": [ "10.0.2.1:9300" ]
  }
}
-----------------------------------------------------------

Next, set up a role called `cluster_two_logs` on both cluster `one` and
cluster `two`.

On cluster `one`, this role does not need any special privileges:

[source,js]
-----------------------------------------------------------
POST /_xpack/security/role/cluster_two_logs
{
}
-----------------------------------------------------------

On cluster `two`, this role allows the user to query local indices called
`logs-` from a remote cluster:

[source,js]
-----------------------------------------------------------
POST /_xpack/security/role/cluster_two_logs
{
  "cluster": [
    "transport_client"
  ],
  "indices": [
    {
      "names": [
        "logs-*"
      ],
      "privileges": [
        "read",
        "read_cross_cluster"
      ]
    }
  ]
}
-----------------------------------------------------------

Finally, create a user on cluster `one` and apply the `cluster_two_logs` role:

[source,js]
-----------------------------------------------------------
POST /_xpack/security/user/alice
{
  "password" : "somepassword",
  "roles" : [ "cluster_two_logs" ],
  "full_name" : "Alice",
  "email" : "alice@example.com",
  "enabled": true
}
-----------------------------------------------------------

With all of the above setup, the user `alice` is able to search indices in
cluster `two` as follows:

[source,js]
-----------------------------------------------------------
GET two:logs-2017.04/_search <1>
{
  "query": {
    "match_all": {}
  }
}
-----------------------------------------------------------
//TBD: Is there a missing description of the <1> callout above?

include::{xkb-repo-dir}/security/cross-cluster-kibana.asciidoc[]