elasticsearch/docs/reference/modules/cluster/remote-clusters-api-key.asciidoc

[[remote-clusters-api-key]]
=== Add remote clusters using API key authentication

API key authentication enables a local cluster to authenticate itself with a
remote cluster via a <<security-api-create-cross-cluster-api-key,cross-cluster
API key>>. The API key needs to be created by an administrator of the remote
cluster. The local cluster is configured to provide this API key on each request
to the remote cluster. The remote cluster verifies the API key and grants
access, based on the API key's privileges.

All cross-cluster requests from the local cluster are bound by the API key's
privileges, regardless of local users associated with the requests. For example,
if the API key only allows read access to `my-index` on the remote cluster, even
a superuser from the local cluster is limited by this constraint. This mechanism
enables the remote cluster's administrator to have full control over who can
access what data with cross-cluster search and/or cross-cluster replication. The
remote cluster's administrator can be confident that no access is possible
beyond what is explicitly assigned to the API key.

On the local cluster side, not every local user needs to access every piece of
data allowed by the API key. An administrator of the local cluster can further
configure additional permission constraints on local users so each user only
gets access to the necessary remote data. Note it is only possible to further
reduce the permissions allowed by the API key for individual local users. It is
impossible to increase the permissions to go beyond what is allowed by the API
key.

In this model, cross-cluster operations use <<remote_cluster.port,a dedicated
server port>> (remote cluster interface) for communication between clusters. A
remote cluster must enable this port for local clusters to connect. Configure
Transport Layer Security (TLS) for this port to maximize security (as explained
in <<remote-clusters-security-api-key>>).

The local cluster must trust the remote cluster on the remote cluster interface.
This means that the local cluster trusts the remote cluster's certificate
authority (CA) that signs the server certificate used by the remote cluster
interface. When establishing a connection, all nodes from the local cluster that
participate in cross-cluster communication verify certificates from nodes on the
other side, based on the TLS trust configuration.

To add a remote cluster using API key authentication:

. <<remote-clusters-prerequisites-api-key,Review the prerequisites>>
. <<remote-clusters-security-api-key>>
. <<remote-clusters-connect-api-key>>
. <<remote-clusters-privileges-api-key>>

If you run into any issues, refer to <<remote-clusters-troubleshooting>>.

[[remote-clusters-prerequisites-api-key]]
==== Prerequisites

* The {es} security features need to be enabled on both clusters, on every node.
Security is enabled by default. If it's disabled, set `xpack.security.enabled`
to `true` in `elasticsearch.yml`. Refer to <<general-security-settings>>.
* The nodes of the local and remote clusters must be on version 8.10 or later.
* The local and remote clusters must have an appropriate license. For more
information, refer to https://www.elastic.co/subscriptions.

[[remote-clusters-security-api-key]]
==== Establish trust with a remote cluster

NOTE: If a remote cluster is part of an {ess} deployment, it has a valid certificate by default. 
You can therefore skip steps related to certificates in these instructions.

===== On the remote cluster

// tag::remote-cluster-steps[]
. Enable the remote cluster server on every node of the remote cluster. In
`elasticsearch.yml`:
.. Set <<remote-cluster-network-settings,`remote_cluster_server.enabled`>> to
`true`.
.. Configure the bind and publish address for remote cluster server traffic, for
example using <<remote-cluster-network-settings,`remote_cluster.host`>>. Without
configuring the address, remote cluster traffic may be bound to the local
interface, and remote clusters running on other machines can't connect.
.. Optionally, configure the remote server port using
<<remote_cluster.port,`remote_cluster.port`>> (defaults to `9443`).
. Next, generate a certificate authority (CA) and a server certificate/key pair.
On one of the nodes of the remote cluster, from the directory where {es} has
been installed:

.. Create a CA, if you don't have a CA already:
+
[source,sh]
----
./bin/elasticsearch-certutil ca --pem --out=cross-cluster-ca.zip --pass CA_PASSWORD
----
+
Replace `CA_PASSWORD` with the password you want to use for the CA. You can
remove the `--pass` option and its argument if you are not deploying to a
production environment.

.. Unzip the generated `cross-cluster-ca.zip` file. This compressed file
contains the following content:
+
[source,txt]
----
/ca
|_ ca.crt
|_ ca.key
----

.. Generate a certificate and private key pair for the nodes in the remote
cluster:
+
[source,sh]
----
./bin/elasticsearch-certutil cert --out=cross-cluster.p12 --pass=CERT_PASSWORD --ca-cert=ca/ca.crt --ca-key=ca/ca.key --ca-pass=CA_PASSWORD --dns=example.com --ip=127.0.0.1
----
+
* Replace `CA_PASSWORD` with the CA password from the previous step.
* Replace `CERT_PASSWORD` with the password you want to use for the generated
private key.
* Use the `--dns` option to specify the relevant DNS name for the certificate.
You can specify it multiple times for multiple DNS.
* Use the `--ip` option to specify the relevant IP address for the certificate.
You can specify it multiple times for multiple IP addresses.

.. If the remote cluster has multiple nodes, you can either:
+
* create a single wildcard certificate for all nodes;
* or, create separate certificates for each node either manually or in batch
with the <<certutil-silent,silent mode>>.

. On every node of the remote cluster:
.. Copy the `cross-cluster.p12` file from the earlier step to the `config`
directory. If you didn't create a wildcard certificate, make sure you copy the
correct node-specific p12 file.
.. Add following configuration to `elasticsearch.yml`:
+
[source,yaml]
----
xpack.security.remote_cluster_server.ssl.enabled: true
xpack.security.remote_cluster_server.ssl.keystore.path: cross-cluster.p12
----

.. Add the SSL keystore password to the {es} keystore:
+
[source,sh]
----
./bin/elasticsearch-keystore add xpack.security.remote_cluster_server.ssl.keystore.secure_password
----
+
When prompted, enter the `CERT_PASSWORD` from the earlier step.

. Restart the remote cluster.

. On the remote cluster, generate a cross-cluster API key that provides access
to the indices you want to use for {ccs} or {ccr}. You can use the
<<security-api-create-cross-cluster-api-key>> API or
{kibana-ref}/api-keys.html[Kibana].

. Copy the encoded key (`encoded` in the response) to a safe location. You will
need it to connect to the remote cluster later.
// end::remote-cluster-steps[]

===== On the local cluster

// tag::local-cluster-steps[]
. On every node of the local cluster:

.. Copy the `ca.crt` file generated on the remote cluster earlier into the
`config` directory, renaming the file `remote-cluster-ca.crt`.

.. Add following configuration to `elasticsearch.yml`:
+
[source,yaml]
----
xpack.security.remote_cluster_client.ssl.enabled: true
xpack.security.remote_cluster_client.ssl.certificate_authorities: [ "remote-cluster-ca.crt" ]
----
// end::local-cluster-steps[]

.. Add the cross-cluster API key, created on the remote cluster earlier, to the
keystore:
+
[source,sh]
----
./bin/elasticsearch-keystore add cluster.remote.ALIAS.credentials
----
+
Replace `ALIAS` with the same name that you will use to create the remote cluster entry
later. When prompted, enter the encoded cross-cluster API key created on the
remote cluster earlier.

. Restart the local cluster to load changes to the keystore and settings.

**Note:** If you are configuring only the cross-cluster API key, you can call the <<cluster-nodes-reload-secure-settings>> API, instead of restarting the cluster.
Configuring the `remote_cluster_client` settings in `elasticsearch.yml` still requires a restart.

[[remote-clusters-connect-api-key]]
==== Connect to a remote cluster

:trust-mechanism: api-key
include::remote-clusters-connect.asciidoc[]
:!trust-mechanism:

include::{es-ref-dir}/security/authentication/remote-clusters-privileges-api-key.asciidoc[leveloffset=+1]