From d4d505fb97e7fdcb157672a11bad509b261b8c38 Mon Sep 17 00:00:00 2001
From: Clinton Gormley <clint@traveljury.com>
Date: Tue, 11 Apr 2017 10:08:12 +0200
Subject: [PATCH] Added docs for making cross cluster search work with security

relates elastic/x-pack-elasticsearch#868

Original commit: elastic/x-pack-elasticsearch@0292fbb5d30b94e3989211ec44ebfb3b7504c017
---
 docs/en/security/index.asciidoc               |  2 +-
 .../tribe-clients-integrations.asciidoc       | 14 +++--
 .../cross-cluster.asciidoc                    | 61 +++++++++++++++++++
 3 files changed, 71 insertions(+), 6 deletions(-)
 create mode 100644 docs/en/security/tribe-clients-integrations/cross-cluster.asciidoc

diff --git a/docs/en/security/index.asciidoc b/docs/en/security/index.asciidoc
index f7334f9ea9e..9fdd985dbc5 100644
--- a/docs/en/security/index.asciidoc
+++ b/docs/en/security/index.asciidoc
@@ -83,7 +83,7 @@ issues.
   provides more information about how Security supports user authentication,
   authorization, and encryption.
 
-* <<tribe-clients-integrations>>
+* <<ccs-tribe-clients-integrations>>
   shows you how to interact with an Elasticsearch cluster protected by
   X-Pack Security.
 
diff --git a/docs/en/security/tribe-clients-integrations.asciidoc b/docs/en/security/tribe-clients-integrations.asciidoc
index a059f4da956..bee0fbb4bdf 100644
--- a/docs/en/security/tribe-clients-integrations.asciidoc
+++ b/docs/en/security/tribe-clients-integrations.asciidoc
@@ -1,10 +1,12 @@
-[[tribe-clients-integrations]]
-== Tribe, Clients and Integrations
+[[ccs-tribe-clients-integrations]]
+== Cross Cluster Search, Tribe, Clients and Integrations
 
-When using a {ref}/modules-tribe.html[Tribe Nodes] you need to take extra steps to secure its communication
-with the connected clusters
+When using {ref}/modules-cross-cluster-search.html[Cross Cluster Search] or
+{ref}/modules-tribe.html[Tribe Nodes] you need to take extra steps to secure
+communications with the connected clusters.
 
-* <<tribe-node-configuring, Tribe Node Security>>
+* <<cross-cluster-configuring, Cross Cluster Search and Security>>
+* <<tribe-node-configuring, Tribe Nodes and Security>>
 
 You will need to update the configuration for several clients to work with a
 secured cluster:
@@ -23,6 +25,8 @@ be secured as well, or at least communicate with the cluster in a secured way:
 * <<kibana, Kibana>>
 * <<secure-monitoring, Monitoring>>
 
+include::tribe-clients-integrations/cross-cluster.asciidoc[]
+
 include::tribe-clients-integrations/tribe.asciidoc[]
 
 include::tribe-clients-integrations/java.asciidoc[]
diff --git a/docs/en/security/tribe-clients-integrations/cross-cluster.asciidoc b/docs/en/security/tribe-clients-integrations/cross-cluster.asciidoc
new file mode 100644
index 00000000000..e557d054578
--- /dev/null
+++ b/docs/en/security/tribe-clients-integrations/cross-cluster.asciidoc
@@ -0,0 +1,61 @@
+[[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.
+
+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 <<transport-tls-ssl-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>>).
+