| mapped_pages | |||||
|---|---|---|---|---|---|
| applies_to |
|
||||
| products |
|
API key authentication enables a local cluster to authenticate itself with a remote cluster via a 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 a dedicated server port (remote cluster interface) for communication between clusters, which defaults to port 9443. 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 Establish trust with a remote cluster).
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:
- Review the prerequisites
- Establish trust with a remote cluster
- Connect to a remote cluster
- (Optional) Configure strong identity verification
- Configure roles and users
If you run into any issues, refer to Troubleshooting.
- 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.enabledtotrueinelasticsearch.yml. Refer to General security settings. - The nodes of the local and remote clusters must be on {{stack}} 8.14 or later.
- The local and remote clusters must have an appropriate license. For more information, refer to https://www.elastic.co/subscriptions.
::::{note} If a remote cluster is part of an {{ech}} (ECH) deployment, the remote cluster server is enabled by default and it uses a publicly trusted certificate provided by the platform proxies. Therefore, you can skip the following steps in these instructions:
On the remote (ECH) cluster: Skip steps 1-4 (enabling the service, generating certificates, configuring SSL settings, and restarting the cluster), and go directly to create an API key.
On the local (self-managed) cluster: Do not add the xpack.security.remote_cluster_client.ssl.certificate_authorities setting to the configuration file because ECH uses publicly trusted certificates that don't require custom CA configuration.
::::
By default, the remote cluster server interface is not enabled on self-managed clusters. Follow the steps below to enable the interface and create an API key on the remote cluster.
:::{include} _snippets/self_rcs_enable.md :::
:::{include} _snippets/apikeys-create-key.md :::
:::{include} _snippets/self_rcs_local_config.md :::
::::{note}
You must have the manage cluster privilege to connect remote clusters.
::::
The local cluster uses the remote cluster interface to establish communication with remote clusters. The coordinating nodes in the local cluster establish long-lived TCP connections with specific nodes in the remote cluster. {{es}} requires these connections to remain open, even if the connections are idle for an extended period.
To add a remote cluster from Stack Management in {{kib}}:
-
Go to the Remote Clusters management page in the navigation menu or use the global search field.
-
Select Add a remote cluster.
-
Select API keys as the connection type.
-
Enter a name (cluster alias) for the remote cluster.
-
Specify the {{es}} endpoint URL, or the IP address or host name of the remote cluster followed by the remote cluster port (defaults to
9443). For example,cluster.es.eastus2.staging.azure.foundit.no:9443or192.0.2.1:9443.Starting with {{kib}} 9.2, you can also specify IPv6 addresses.
Alternatively, use the cluster update settings API to add a remote cluster. You can also use this API to dynamically configure remote clusters for every node in the local cluster. To configure remote clusters on individual nodes in the local cluster, define static settings in elasticsearch.yml for each node.
::::{note}
If the remote cluster is part of an {{ech}}, {{ece}}, or {{eck}} deployment, configure the connection to use proxy. The default sniff mode doesn't work in these environments. Refer to the connection modes description for more information.
::::
The following request adds a remote cluster with an alias of cluster_one. This cluster alias is a unique identifier that represents the connection to the remote cluster and is used to distinguish between local and remote indices.
PUT /_cluster/settings
{
"persistent" : {
"cluster" : {
"remote" : {
"cluster_one" : { <1>
"seeds" : [
"<MY_REMOTE_CLUSTER_ADDRESS>:9443" <2>
]
}
}
}
}
}- The cluster alias of this remote cluster is
cluster_one. - Specifies the hostname and remote cluster port of a seed node in the remote cluster.
You can use the remote cluster info API to verify that the local cluster is successfully connected to the remote cluster:
GET /_remote/infoThe API response indicates that the local cluster is connected to the remote cluster with the cluster alias cluster_one:
{
"cluster_one" : {
"seeds" : [
"<MY_REMOTE_CLUSTER_ADDRESS>:9443"
],
"connected" : true,
"num_nodes_connected" : 1, <1>
"max_connections_per_cluster" : 3,
"initial_connect_timeout" : "30s",
"skip_unavailable" : true, <2>
"cluster_credentials": "::es_redacted::", <3>
"mode" : "sniff"
}
}
- The number of nodes in the remote cluster the local cluster is connected to.
- Indicates whether to skip the remote cluster if searched through {{ccs}} but no nodes are available.
- If present, indicates the remote cluster has connected using API key authentication.
Use the cluster update settings API to dynamically configure remote settings on every node in the cluster. The following request adds three remote clusters: cluster_one, cluster_two, and cluster_three.
The seeds parameter specifies the hostname and remote cluster port (default 9443) of a seed node in the remote cluster.
The mode parameter determines the configured connection mode, which defaults to sniff. Because cluster_one doesn’t specify a mode, it uses the default. Both cluster_two and cluster_three explicitly use different modes.
PUT _cluster/settings
{
"persistent": {
"cluster": {
"remote": {
"cluster_one": {
"seeds": [
"<MY_REMOTE_CLUSTER_ADDRESS>:9443"
]
},
"cluster_two": {
"mode": "sniff",
"seeds": [
"<MY_SECOND_REMOTE_CLUSTER_ADDRESS>:9443"
],
"transport.compress": true,
"skip_unavailable": true
},
"cluster_three": {
"mode": "proxy",
"proxy_address": "<MY_THIRD_REMOTE_CLUSTER_ADDRESS>:9443"
}
}
}
}
}You can dynamically update settings for a remote cluster after the initial configuration. The following request updates the compression settings for cluster_two, and the compression and ping schedule settings for cluster_three.
::::{note} When the compression or ping schedule settings change, all existing node connections must close and re-open, which can cause in-flight requests to fail. ::::
PUT _cluster/settings
{
"persistent": {
"cluster": {
"remote": {
"cluster_two": {
"transport.compress": false
},
"cluster_three": {
"transport.compress": true,
"transport.ping_schedule": "60s"
}
}
}
}
}You can delete a remote cluster from the cluster settings by passing null values for each remote cluster setting. The following request removes cluster_two from the cluster settings, leaving cluster_one and cluster_three intact:
PUT _cluster/settings
{
"persistent": {
"cluster": {
"remote": {
"cluster_two": {
"mode": null,
"seeds": null,
"skip_unavailable": null,
"transport.compress": null
}
}
}
}
}If you specify settings in elasticsearch.yml, only the nodes with those settings can connect to the remote cluster and serve remote cluster requests.
::::{note}
Remote cluster settings that are specified using the cluster update settings API take precedence over settings that you specify in elasticsearch.yml for individual nodes.
::::
In the following example, cluster_one, cluster_two, and cluster_three are arbitrary cluster aliases representing the connection to each cluster. These names are subsequently used to distinguish between local and remote indices.
cluster:
remote:
cluster_one:
seeds: <MY_REMOTE_CLUSTER_ADDRESS>:9443
cluster_two:
mode: sniff
seeds: <MY_SECOND_REMOTE_CLUSTER_ADDRESS>:9443
transport.compress: true <1>
skip_unavailable: true <2>
cluster_three:
mode: proxy
proxy_address: <MY_THIRD_REMOTE_CLUSTER_ADDRESS>:9443 <3>- Compression is explicitly enabled for requests to
cluster_two. - Disconnected remote clusters are optional for
cluster_two. - The address for the proxy endpoint used to connect to
cluster_three.
stack: preview 9.3
::::{include} _snippets/rcs_strong_identity_intro.md ::::
::::{include} _snippets/rcs_strong_identity_how.md ::::
To use strong identity verification, the local and remote clusters must be configured to sign request headers and to verify request
headers. This can be done through the cluster settings API or elasticsearch.yaml.
:::{note} The steps in this section describe the configuration for self-managed clusters. The same procedure can be adapted for {{ece}} and {{eck}} with the appropriate platform-specific configuration steps.
For {{ech}}-specific steps to configure strong identity verification, refer to Strong identity verification on {{ech}}. :::
When adding the remote cluster to the local cluster, you must configure it to sign cross-cluster requests with a certificate–private key pair. You can generate a signing certificate using elasticsearch-certutil or use an existing certificate. The private key can be encrypted and the password must be stored securely as a secure setting in Elasticsearch keystore. Refer to the remote cluster settings reference for details.
cluster.remote.my_remote_cluster.signing.certificate: "path/to/signing/certificate.crt"
cluster.remote.my_remote_cluster.signing.key: "path/to/signing/key.key"::::{note}
Replace my_remote_cluster with your remote cluster alias, and the paths with the paths to your certificate and key files.
::::
The remote cluster must be configured with a certificate authority that trusts the certificate that was used to sign the request headers.
cluster.remote.signing.certificate_authorities: "path/to/signing/certificate_authorities.crt"When creating a cross-cluster API key on the remote cluster, specify a certificate_identity pattern that matches the Distinguished
Name (DN) of the local cluster's certificate. Use the Create cross-cluster API key API:
POST /_security/cross_cluster/api_key
{
"name": "my-cross-cluster-api-key",
"access": {
"search": [
{
"names": ["logs-*"]
}
]
},
"certificate_identity": "CN=local-cluster.example.com,O=Example Corp,C=US"
}The certificate_identity field supports regular expressions. For example:
"CN=.*.example.com,O=Example Corp,C=US"matches any certificate with a CN ending in "example.com""CN=local-cluster.*,O=Example Corp,C=US"matches any certificate with a CN starting with "local-cluster""CN=.*"matches any certificate (not recommended for production)
For a full list of available strong identity verification settings for remote clusters, refer to the remote cluster settings reference.
To use a remote cluster for {{ccr}} or {{ccs}}, configure privileges so users can use {{ccr}} and {{ccs}}: