From 9ecc495312ec5aaf38f26b14dd8a5a816dc6ee2b Mon Sep 17 00:00:00 2001 From: Johannes Freden Jansson Date: Mon, 10 Nov 2025 14:36:15 +0100 Subject: [PATCH 01/10] Add RCS Strong Verification Documentation --- .../remote-clusters-api-key.md | 70 +++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/deploy-manage/remote-clusters/remote-clusters-api-key.md b/deploy-manage/remote-clusters/remote-clusters-api-key.md index 1e5a3394a0..0fa12eedad 100644 --- a/deploy-manage/remote-clusters/remote-clusters-api-key.md +++ b/deploy-manage/remote-clusters/remote-clusters-api-key.md @@ -26,6 +26,7 @@ To add a remote cluster using API key authentication: 2. [Establish trust with a remote cluster](#remote-clusters-security-api-key) 3. [Connect to a remote cluster](#remote-clusters-connect-api-key) 4. [Configure roles and users](#remote-clusters-privileges-api-key) +5. (Optional) [Configure remote cluster strong verification](#remote-cluster-strong-verification) for additional security If you run into any issues, refer to [Troubleshooting](/troubleshoot/elasticsearch/remote-clusters.md). @@ -405,3 +406,72 @@ POST /_security/user/cross-search-user ``` Note that you only need to create this user on the local cluster. + + +## Remote cluster strong verification [remote-cluster-strong-verification] +preview::[] + +Cross-cluster API keys can be configured with strong verification to provide an additional layer of security. To enable this feature, +the cross-cluster API key is created with a certificate identity pattern. The local cluster is then required to be configured to sign +the API key for every request to the remote cluster and provide a trusted certificate with a subject matching the certificate identity +pattern that was used when the cross-cluster API key was created. + +### How strong verification works [_how_strong_verification_works] + +When a local cluster makes a request to a remote cluster using a cross-cluster API key: + +1. The local cluster signs the request headers with its configured private key and sends the signature and certificate chain as header + in the request to the remote cluster +2. The remote cluster verifies that the API key is valid +3. If the API key has a certificate identity pattern configured, the remote cluster extracts the Distinguished Name (DN) from the + certificate chain's leaf certificate and matches it against the certificate identity pattern +4. The remote cluster validates that the provided certificate chain is trusted +5. The remote cluster validates the signature and checks that the certificate is not expired + +If any of these validation steps fail, the request is rejected. + +### Configure strong verification [_configure_strong_verification] + +To use certificate identity validation, the local and remote clusters must be configured to sign request headers and to verify request +headers. + +#### On the local cluster [_certificate_identity_local_cluster] + +The local cluster must be configured to sign cross-cluster requests with a certificate-private key pair. + +```yaml +cluster.remote.my_remote_cluster.signing.certificate: "path/to/signing/certificate.crt" +cluster.remote.my_remote_cluster.signing.key: "path/to/signing/key.key" +``` + +#### On the remote cluster [_certificate_identity_remote_cluster] + +The remote cluster must be configured with a certificate authority that trusts the certificate that was used to sign the request headers. + +```yaml +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](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-cross-cluster-api-key) API: + +```console +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 starting with any subdomain of 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) From 1375e5c39ae1f6fdec6da5aa63fe242ce59514cf Mon Sep 17 00:00:00 2001 From: Johannes Freden Jansson Date: Mon, 10 Nov 2025 15:22:24 +0100 Subject: [PATCH 02/10] fixup! nits --- .../remote-clusters-api-key.md | 20 +++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/deploy-manage/remote-clusters/remote-clusters-api-key.md b/deploy-manage/remote-clusters/remote-clusters-api-key.md index 0fa12eedad..cd5ccbf4a3 100644 --- a/deploy-manage/remote-clusters/remote-clusters-api-key.md +++ b/deploy-manage/remote-clusters/remote-clusters-api-key.md @@ -411,10 +411,10 @@ Note that you only need to create this user on the local cluster. ## Remote cluster strong verification [remote-cluster-strong-verification] preview::[] -Cross-cluster API keys can be configured with strong verification to provide an additional layer of security. To enable this feature, -the cross-cluster API key is created with a certificate identity pattern. The local cluster is then required to be configured to sign -the API key for every request to the remote cluster and provide a trusted certificate with a subject matching the certificate identity -pattern that was used when the cross-cluster API key was created. +Cross-cluster API keys can be configured with strong verification to provide an additional layer of security. To enable this feature, +the cross-cluster API key is created with a certificate identity pattern. The local cluster is then required to sign each request +to the remote cluster with its private key and provide a trusted certificate whose subject matches the certificate identity +pattern configured on the cross-cluster API key. ### How strong verification works [_how_strong_verification_works] @@ -437,13 +437,18 @@ headers. #### On the local cluster [_certificate_identity_local_cluster] -The local cluster must be configured to sign cross-cluster requests with a certificate-private key pair. +The local cluster must be configured 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. ```yaml 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 actual paths +:::: + #### On the remote cluster [_certificate_identity_remote_cluster] The remote cluster must be configured with a certificate authority that trusts the certificate that was used to sign the request headers. @@ -472,6 +477,9 @@ POST /_security/cross_cluster/api_key The `certificate_identity` field supports regular expressions. For example: -* `"CN=.*.example.com,O=Example Corp,C=US"` matches any certificate with a CN starting with any subdomain of example.com +* `"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) + +To verify strong verification is active, check the Elasticsearch logs on the remote cluster for certificate validation messages, or +attempt a connection without proper signing configured (which should fail with a certificate validation error). From 15ad32ea0a97ac866c8b42211c206dc27cc841f5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20Fred=C3=A9n?= <109296772+jfreden@users.noreply.github.com> Date: Tue, 11 Nov 2025 16:18:17 +0100 Subject: [PATCH 03/10] Update deploy-manage/remote-clusters/remote-clusters-api-key.md Co-authored-by: shainaraskas <58563081+shainaraskas@users.noreply.github.com> --- deploy-manage/remote-clusters/remote-clusters-api-key.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/deploy-manage/remote-clusters/remote-clusters-api-key.md b/deploy-manage/remote-clusters/remote-clusters-api-key.md index 54a22a8292..f1f5196986 100644 --- a/deploy-manage/remote-clusters/remote-clusters-api-key.md +++ b/deploy-manage/remote-clusters/remote-clusters-api-key.md @@ -428,7 +428,10 @@ Note that you only need to create this user on the local cluster. ## Remote cluster strong verification [remote-cluster-strong-verification] -preview::[] +```{applies_to} +deployment: + self: preview 9.3 +``` Cross-cluster API keys can be configured with strong verification to provide an additional layer of security. To enable this feature, the cross-cluster API key is created with a certificate identity pattern. The local cluster is then required to sign each request From 78c8b8bc400da914bb1229026d970691822540ea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20Fred=C3=A9n?= <109296772+jfreden@users.noreply.github.com> Date: Tue, 11 Nov 2025 16:18:38 +0100 Subject: [PATCH 04/10] Update deploy-manage/remote-clusters/remote-clusters-api-key.md Co-authored-by: shainaraskas <58563081+shainaraskas@users.noreply.github.com> --- .../remote-clusters/remote-clusters-api-key.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/deploy-manage/remote-clusters/remote-clusters-api-key.md b/deploy-manage/remote-clusters/remote-clusters-api-key.md index f1f5196986..767f8aabf0 100644 --- a/deploy-manage/remote-clusters/remote-clusters-api-key.md +++ b/deploy-manage/remote-clusters/remote-clusters-api-key.md @@ -442,13 +442,13 @@ pattern configured on the cross-cluster API key. When a local cluster makes a request to a remote cluster using a cross-cluster API key: -1. The local cluster signs the request headers with its configured private key and sends the signature and certificate chain as header - in the request to the remote cluster -2. The remote cluster verifies that the API key is valid +1. The local cluster signs the request headers with its configured private key and sends the signature and certificate chain as header + in the request to the remote cluster. +2. The remote cluster verifies that the API key is valid. 3. If the API key has a certificate identity pattern configured, the remote cluster extracts the Distinguished Name (DN) from the - certificate chain's leaf certificate and matches it against the certificate identity pattern -4. The remote cluster validates that the provided certificate chain is trusted -5. The remote cluster validates the signature and checks that the certificate is not expired + certificate chain's leaf certificate and matches it against the certificate identity pattern. +4. The remote cluster validates that the provided certificate chain is trusted. +5. The remote cluster validates the signature and checks that the certificate is not expired. If any of these validation steps fail, the request is rejected. From 935929a7538682ea29a16b1fe443c03970790292 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20Fred=C3=A9n?= <109296772+jfreden@users.noreply.github.com> Date: Tue, 11 Nov 2025 16:19:01 +0100 Subject: [PATCH 05/10] Update deploy-manage/remote-clusters/remote-clusters-api-key.md Co-authored-by: shainaraskas <58563081+shainaraskas@users.noreply.github.com> --- deploy-manage/remote-clusters/remote-clusters-api-key.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deploy-manage/remote-clusters/remote-clusters-api-key.md b/deploy-manage/remote-clusters/remote-clusters-api-key.md index 767f8aabf0..1776e79c2e 100644 --- a/deploy-manage/remote-clusters/remote-clusters-api-key.md +++ b/deploy-manage/remote-clusters/remote-clusters-api-key.md @@ -468,7 +468,7 @@ 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 actual paths +Replace `my_remote_cluster` with your remote cluster alias, and the paths with the paths to your certificate and key files. :::: #### On the remote cluster [_certificate_identity_remote_cluster] From 09e40f6083f8cf18d88abfc79ac63af634a7ed47 Mon Sep 17 00:00:00 2001 From: Johannes Freden Jansson Date: Tue, 11 Nov 2025 16:42:42 +0100 Subject: [PATCH 06/10] fixup! Code review comments --- .../remote-clusters-api-key.md | 21 ++++++++++--------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/deploy-manage/remote-clusters/remote-clusters-api-key.md b/deploy-manage/remote-clusters/remote-clusters-api-key.md index 1776e79c2e..90a003ddc3 100644 --- a/deploy-manage/remote-clusters/remote-clusters-api-key.md +++ b/deploy-manage/remote-clusters/remote-clusters-api-key.md @@ -23,10 +23,11 @@ The local cluster must trust the remote cluster on the remote cluster interface. To add a remote cluster using API key authentication: 1. [Review the prerequisites](#remote-clusters-prerequisites-api-key) -2. [Establish trust with a remote cluster](#remote-clusters-security-api-key) +2. [Establish trust with a remote cluster](#remote-clusters-security-api-key) + 1. (Optional) [Configure remote cluster strong verification](#remote-cluster-strong-verification) for additional security 3. [Connect to a remote cluster](#remote-clusters-connect-api-key) 4. [Configure roles and users](#remote-clusters-privileges-api-key) -5. (Optional) [Configure remote cluster strong verification](#remote-cluster-strong-verification) for additional security + If you run into any issues, refer to [Troubleshooting](/troubleshoot/elasticsearch/remote-clusters.md). @@ -433,10 +434,13 @@ deployment: self: preview 9.3 ``` -Cross-cluster API keys can be configured with strong verification to provide an additional layer of security. To enable this feature, -the cross-cluster API key is created with a certificate identity pattern. The local cluster is then required to sign each request -to the remote cluster with its private key and provide a trusted certificate whose subject matches the certificate identity -pattern configured on the cross-cluster API key. +Cross-cluster API keys can be configured with strong verification to provide an additional layer of security. To enable this feature, a +cross-cluster API key is created on the remote cluster with a certificate identity pattern that specifies which certificates are allowed +to use it. The local cluster must then sign each request with its private key and include a certificate whose subject Distinguished Name +(DN) matches the pattern. The remote cluster validates both that the certificate is trusted by its configured certificate authorities +and that the certificate's subject matches the API key's identity pattern. + +Each remote cluster alias on the local cluster can have different remote signing configurations. ### How strong verification works [_how_strong_verification_works] @@ -460,7 +464,7 @@ headers. #### On the local cluster [_certificate_identity_local_cluster] The local cluster must be configured 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. +certificate using [elasticsearch-certutil](#remote-clusters-security-api-key-remote-action) or use an existing certificate. ```yaml cluster.remote.my_remote_cluster.signing.certificate: "path/to/signing/certificate.crt" @@ -502,6 +506,3 @@ 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) - -To verify strong verification is active, check the Elasticsearch logs on the remote cluster for certificate validation messages, or -attempt a connection without proper signing configured (which should fail with a certificate validation error). From 1fe67ae675f7dfae36860758ca81d4e7745c3e96 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20Fred=C3=A9n?= <109296772+jfreden@users.noreply.github.com> Date: Thu, 13 Nov 2025 14:11:34 +0100 Subject: [PATCH 07/10] Update deploy-manage/remote-clusters/remote-clusters-api-key.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Edu González de la Herrán <25320357+eedugon@users.noreply.github.com> --- deploy-manage/remote-clusters/remote-clusters-api-key.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/deploy-manage/remote-clusters/remote-clusters-api-key.md b/deploy-manage/remote-clusters/remote-clusters-api-key.md index 90a003ddc3..e3e5b18711 100644 --- a/deploy-manage/remote-clusters/remote-clusters-api-key.md +++ b/deploy-manage/remote-clusters/remote-clusters-api-key.md @@ -463,8 +463,7 @@ headers. #### On the local cluster [_certificate_identity_local_cluster] -The local cluster must be configured to sign cross-cluster requests with a certificate-private key pair. You can generate a signing -certificate using [elasticsearch-certutil](#remote-clusters-security-api-key-remote-action) or use an existing certificate. +When [adding the remote cluster](#using-the-es-api) 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](#remote-clusters-security-api-key-remote-action) or use an existing certificate. ```yaml cluster.remote.my_remote_cluster.signing.certificate: "path/to/signing/certificate.crt" From ac8fbb4407616501de50062bdca1e77794deba4d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20Fred=C3=A9n?= <109296772+jfreden@users.noreply.github.com> Date: Thu, 13 Nov 2025 14:11:48 +0100 Subject: [PATCH 08/10] Update deploy-manage/remote-clusters/remote-clusters-api-key.md Co-authored-by: shainaraskas <58563081+shainaraskas@users.noreply.github.com> --- deploy-manage/remote-clusters/remote-clusters-api-key.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deploy-manage/remote-clusters/remote-clusters-api-key.md b/deploy-manage/remote-clusters/remote-clusters-api-key.md index e3e5b18711..471789670f 100644 --- a/deploy-manage/remote-clusters/remote-clusters-api-key.md +++ b/deploy-manage/remote-clusters/remote-clusters-api-key.md @@ -431,7 +431,7 @@ Note that you only need to create this user on the local cluster. ## Remote cluster strong verification [remote-cluster-strong-verification] ```{applies_to} deployment: - self: preview 9.3 + stack: preview 9.3 ``` Cross-cluster API keys can be configured with strong verification to provide an additional layer of security. To enable this feature, a From 967bd9d0b86e6f570ae5b6c3d40e9b116eaf096d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20Fred=C3=A9n?= <109296772+jfreden@users.noreply.github.com> Date: Thu, 13 Nov 2025 14:11:56 +0100 Subject: [PATCH 09/10] Update deploy-manage/remote-clusters/remote-clusters-api-key.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Edu González de la Herrán <25320357+eedugon@users.noreply.github.com> --- deploy-manage/remote-clusters/remote-clusters-api-key.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/deploy-manage/remote-clusters/remote-clusters-api-key.md b/deploy-manage/remote-clusters/remote-clusters-api-key.md index 471789670f..93ad761083 100644 --- a/deploy-manage/remote-clusters/remote-clusters-api-key.md +++ b/deploy-manage/remote-clusters/remote-clusters-api-key.md @@ -505,3 +505,5 @@ 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 verification settings for remote clusters, refer to the [remote cluster settings reference](elasticsearch://reference/elasticsearch/configuration-reference/remote-clusters.md#remote-cluster-signing-settings). From fe4d391d0454eb0be1013457ba3a0eab7c320e60 Mon Sep 17 00:00:00 2001 From: Johannes Freden Jansson Date: Thu, 13 Nov 2025 14:22:32 +0100 Subject: [PATCH 10/10] fixup! Code review comments --- .../remote-clusters-api-key.md | 166 +++++++++--------- 1 file changed, 82 insertions(+), 84 deletions(-) diff --git a/deploy-manage/remote-clusters/remote-clusters-api-key.md b/deploy-manage/remote-clusters/remote-clusters-api-key.md index 93ad761083..6f45086b11 100644 --- a/deploy-manage/remote-clusters/remote-clusters-api-key.md +++ b/deploy-manage/remote-clusters/remote-clusters-api-key.md @@ -23,10 +23,10 @@ The local cluster must trust the remote cluster on the remote cluster interface. To add a remote cluster using API key authentication: 1. [Review the prerequisites](#remote-clusters-prerequisites-api-key) -2. [Establish trust with a remote cluster](#remote-clusters-security-api-key) - 1. (Optional) [Configure remote cluster strong verification](#remote-cluster-strong-verification) for additional security +2. [Establish trust with a remote cluster](#remote-clusters-security-api-key) 3. [Connect to a remote cluster](#remote-clusters-connect-api-key) -4. [Configure roles and users](#remote-clusters-privileges-api-key) +4. (Optional) [Configure strong identity verification](#remote-cluster-strong-verification) +5. [Configure roles and users](#remote-clusters-privileges-api-key) If you run into any issues, refer to [Troubleshooting](/troubleshoot/elasticsearch/remote-clusters.md). @@ -340,6 +340,85 @@ cluster: 3. The address for the proxy endpoint used to connect to `cluster_three`. +## Strong identity verification [remote-cluster-strong-verification] +```{applies_to} +deployment: + stack: preview 9.3 +``` + +Cross-cluster API keys can be configured with strong identity verification to provide an additional layer of security. To enable this feature, a +cross-cluster API key is created on the remote cluster with a certificate identity pattern that specifies which certificates are allowed +to use it. The local cluster must then sign each request with its private key and include a certificate whose subject Distinguished Name +(DN) matches the pattern. The remote cluster validates both that the certificate is trusted by its configured certificate authorities +and that the certificate's subject matches the API key's identity pattern. + +Each remote cluster alias on the local cluster can have different remote signing configurations. + +### How strong identity verification works [_how_strong_verification_works] + +When a local cluster makes a request to a remote cluster using a cross-cluster API key: + +1. The local cluster signs the request headers with its configured private key and sends the signature and certificate chain as header + in the request to the remote cluster. +2. The remote cluster verifies that the API key is valid. +3. If the API key has a certificate identity pattern configured, the remote cluster extracts the Distinguished Name (DN) from the + certificate chain's leaf certificate and matches it against the certificate identity pattern. +4. The remote cluster validates that the provided certificate chain is trusted. +5. The remote cluster validates the signature and checks that the certificate is not expired. + +If any of these validation steps fail, the request is rejected. + +### Configure strong identity verification [_configure_strong_verification] + +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`. + +#### On the local cluster [_certificate_identity_local_cluster] + +When [adding the remote cluster](#using-the-es-api) 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](#remote-clusters-security-api-key-remote-action) 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](elasticsearch://reference/elasticsearch/configuration-reference/remote-clusters.md#remote-cluster-signing-settings) for details. + +```yaml +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. +:::: + +#### On the remote cluster [_certificate_identity_remote_cluster] + +The remote cluster must be configured with a certificate authority that trusts the certificate that was used to sign the request headers. + +```yaml +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](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-cross-cluster-api-key) API: + +```console +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](elasticsearch://reference/elasticsearch/configuration-reference/remote-clusters.md#remote-cluster-signing-settings). ## Configure roles and users [remote-clusters-privileges-api-key] @@ -426,84 +505,3 @@ POST /_security/user/cross-search-user ``` Note that you only need to create this user on the local cluster. - - -## Remote cluster strong verification [remote-cluster-strong-verification] -```{applies_to} -deployment: - stack: preview 9.3 -``` - -Cross-cluster API keys can be configured with strong verification to provide an additional layer of security. To enable this feature, a -cross-cluster API key is created on the remote cluster with a certificate identity pattern that specifies which certificates are allowed -to use it. The local cluster must then sign each request with its private key and include a certificate whose subject Distinguished Name -(DN) matches the pattern. The remote cluster validates both that the certificate is trusted by its configured certificate authorities -and that the certificate's subject matches the API key's identity pattern. - -Each remote cluster alias on the local cluster can have different remote signing configurations. - -### How strong verification works [_how_strong_verification_works] - -When a local cluster makes a request to a remote cluster using a cross-cluster API key: - -1. The local cluster signs the request headers with its configured private key and sends the signature and certificate chain as header - in the request to the remote cluster. -2. The remote cluster verifies that the API key is valid. -3. If the API key has a certificate identity pattern configured, the remote cluster extracts the Distinguished Name (DN) from the - certificate chain's leaf certificate and matches it against the certificate identity pattern. -4. The remote cluster validates that the provided certificate chain is trusted. -5. The remote cluster validates the signature and checks that the certificate is not expired. - -If any of these validation steps fail, the request is rejected. - -### Configure strong verification [_configure_strong_verification] - -To use certificate identity validation, the local and remote clusters must be configured to sign request headers and to verify request -headers. - -#### On the local cluster [_certificate_identity_local_cluster] - -When [adding the remote cluster](#using-the-es-api) 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](#remote-clusters-security-api-key-remote-action) or use an existing certificate. - -```yaml -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. -:::: - -#### On the remote cluster [_certificate_identity_remote_cluster] - -The remote cluster must be configured with a certificate authority that trusts the certificate that was used to sign the request headers. - -```yaml -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](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-cross-cluster-api-key) API: - -```console -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 verification settings for remote clusters, refer to the [remote cluster settings reference](elasticsearch://reference/elasticsearch/configuration-reference/remote-clusters.md#remote-cluster-signing-settings).