Connect Elastic Cloud Hosted deployments to self-managed clusters

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.

If you run into any issues, refer to Troubleshooting.

• The local and remote deployments must be on Elastic Stack 8.14 or later.
• Contrary to the certificate security model, the API key security model does not require that both local and remote clusters trust each other.

• On the deployment you will use as remote, use the Elasticsearch API or Kibana to create a cross-cluster API key. Configure it with access to the indices you want to use for cross-cluster search or cross-cluster replication.
• Copy the encoded key (encoded in the response) to a safe location. You will need it in the next step.

The API key created previously will be used by the local deployment to authenticate with the corresponding set of permissions to the remote deployment. For that, you need to add the API key to the local deployment’s keystore.

The steps to follow depend on whether the Certificate Authority (CA) of the remote environment’s Elasticsearch HTTPS server, proxy or, load balancing infrastructure is public or private.

A deployment can be configured to trust all or specific deployments in any environment:

1. From the Security page, select Remote Connections > Add trusted environment and choose Self-managed. Then click Next.

2. Select Certificates as authentication mechanism and click Next.

3. Upload the public certificate for the Certificate Authority of the self-managed environment (the one used to sign all the cluster certificates). The certificate needs to be in PEM format and should not contain the private key. If you only have the key in p12 format, then you can create the necessary file like this: openssl pkcs12 -in elastic-stack-ca.p12 -out newfile.crt.pem -clcerts -nokeys

4. Select the clusters to trust. There are two options here depending on the subject name of the certificates presented by the nodes in your self managed cluster:

   • Following the Elastic Cloud pattern. In Elastic Cloud, the certificates of all Elasticsearch nodes follow this convention: CN = {{node_id}}.node.{{cluster_id}}.cluster.{{scope_id}}. If you follow the same convention in your self-managed environment, then choose this option and you will be able to select all or specific clusters to trust.

   • If your clusters don’t follow the previous convention for the certificates subject name of your nodes, you can still specify the node name of each of the nodes that should be trusted by this deployment. (Keep in mind that following this convention will simplify the management of this cluster since otherwise this configuration will need to be updated every time the topology of your self-managed cluster changes along with the trust restriction file. For this reason, it is recommended migrating your cluster certificates to follow the previous convention).

     Note

     Trust management will not work properly in clusters without an otherName value specified, as is the case by default in an out-of-the-box Elasticsearch installation. To have the Elasticsearch certutil generate new certificates with the otherName attribute, use the file input with the cn attribute as in the example below.

5. Provide a name for the trusted environment. That name will appear in the trust summary of your deployment’s Security page.

6. Select Create trust to complete the configuration.

7. Configure the self-managed cluster to trust this deployment, so that both deployments are configured to trust each other:

   • Download the Certificate Authority used to sign the certificates of your deployment nodes (it can be found in the Security page of your deployment)
   • Trust this CA either using the setting xpack.security.transport.ssl.certificate_authorities in elasticsearch.yml or by adding it to the trust store.

8. Generate certificates with an otherName attribute using the Elasticsearch certutil. Create a file called instances.yaml with all the details of the nodes in your on-premise cluster like below. The dns and ip settings are optional, but cn is mandatory for use with the trust_restrictions path setting in the next step. Next, run ./bin/elasticsearch-certutil cert --ca elastic-stack-ca.p12 -in instances.yaml to create new certificates for all the nodes at once. You can then copy the resulting files into each node.

    instances: - name: "node1" dns: ["node1.mydomain.com"] ip: ["192.168.1.1"] cn: ["node1.node.1234567abcd.cluster.myscope.account"] - name: "node2" dns: ["node2.mydomain.com"] ip: ["192.168.1.2"] cn: ["node2.node.1234567abcd.cluster.myscope.account"] 

9. Restrict the trusted clusters to allow only the ones which your self-managed cluster should trust.

   • All the clusters in an Elastic Cloud region are signed by the same certificate authority. Therefore, adding this CA would make the self-managed cluster trust all the clusters in that region, including clusters from other organizations. This can be limited using the setting xpack.security.transport.ssl.trust_restrictions.path which points to a file that limits the certificates to trust based on their otherName-attribute.

   • For example, the following file would trust:

     • two specific clusters with the cluster IDs aaaabbbbaaaabbbb<1> and xxxxyyyyxxxxyyyy<2> from an organization with organization ID 1053523734
     • <3> any cluster from an organization with organization ID 83988631
     • <4> The nodes from its own cluster (whose certificates follow a different convention: CN = node1.example.com, CN = node2.example.com and CN = node3.example.com)

 trust.subject_name: - *.node.aaaabbbbaaaabbbb.cluster.1053523734.account - *.node.xxxxyyyyxxxxyyyy.cluster.1053523734.account - *.node.*.cluster.83988631.account - node*.example.com 

 { "trust":{ "accounts":[ { "account_id":"ec38dd0aa45f4a69909ca5c81c27138a", "trust_all":true } ], "direct": [ { "type" : "generic", "name" : "My Self-managed environment", "additional_node_names" : ["node1.example.com", "node2.example.com", "node3.example.com",], "certificates" : [ { "pem" : "-----BEGIN CERTIFICATE-----\nMIIDTzCCA...H0=\n-----END CERTIFICATE-----" } ], "trust_all":false } ] } }