mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-24 23:27:25 -04:00
1955bd8ad4
* New docs structure for remote clusters * Fix broken cross-book link errors * More broken cross-book link errors * Remove redirects for new pages * Link to generic remote cluster docs instead * Drop 'API' from the abbreviated title * Add 'Establish trust with a remote cluster' section * Restructure 'Establish trust' section into Prprequisite/local/remote instructions * Add 'Configure roles and users' section * Add 'Connect to a remote cluster' section * Move version compatibility to prerequisites * Fix test errors * Incorporate review feedback * Mention version 8.10 or later in the intro for API keys * Add license prerequisite
184 lines
No EOL
7.2 KiB
Text
184 lines
No EOL
7.2 KiB
Text
[[remote-clusters-api-key]]
|
|
=== Add remote clusters using API key authentication
|
|
|
|
coming::[8.10]
|
|
beta::[]
|
|
|
|
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>>
|
|
|
|
[[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
|
|
|
|
===== On the remote cluster
|
|
|
|
. Enable the remote cluster server port on every node of the remote cluster by
|
|
setting `remote_cluster_server.enabled` to `true` in `elasticsearch.yml`. The
|
|
port number defaults to `9443` and can be configured with the
|
|
`remote_cluster.port` setting. Refer to <<remote-cluster-network-settings>>.
|
|
|
|
. Next, generate a 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 using the
|
|
<<security-api-create-cross-cluster-api-key>> API or
|
|
{kibana-ref}/api-keys.html[Kibana]. Grant the key the required access for {ccs}
|
|
or {ccr}.
|
|
|
|
. Copy the encoded key (`encoded` in the response) to a safe location. You will
|
|
need it to connect to the remote cluster later.
|
|
|
|
===== On the local cluster
|
|
|
|
. 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" ]
|
|
----
|
|
|
|
.. 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 alias you will use to connect to the remote cluster
|
|
later. When prompted, enter the encoded cross-cluster API key created on the
|
|
remote cluster earlier.
|
|
|
|
. Restart the local cluster to load the keystore change.
|
|
|
|
[[remote-clusters-connect-api-key]]
|
|
==== Connect to a remote cluster
|
|
|
|
:trust-mechanism: api-key
|
|
include::remote-clusters-connect.asciidoc[]
|
|
:!trust-mechanism:
|
|
|
|
include::../../../../x-pack/docs/en/security/authentication/remote-clusters-privileges-api-key.asciidoc[leveloffset=+1] |