diff --git a/deploy-manage/remote-clusters.md b/deploy-manage/remote-clusters.md index 593acd5360..6a916cdcbd 100644 --- a/deploy-manage/remote-clusters.md +++ b/deploy-manage/remote-clusters.md @@ -32,7 +32,8 @@ Remote clusters are especially useful in two cases: When configuring remote clusters, you can choose between two security models and two connection modes. Both security models are compatible with either connection mode. -- [Security models](./remote-clusters/security-models.md): API key–based authentication (recommended) or TLS certificate–based authentication (deprecated). +- [Security models](./remote-clusters/security-models.md): API key–based authentication (recommended) or TLS certificate–based authentication (deprecated). Starting with {{stack}} 9.3, API key-based authentication also supports strong identity verification for an additional layer of security. + - [Connection modes](./remote-clusters/connection-modes.md): Sniff mode (direct connections to {{es}} nodes) or proxy mode (connections through a reverse proxy or load balancer endpoint). ::::{note} @@ -45,7 +46,7 @@ Depending on the environment the local and remote clusters are deployed on and t 1. **Configure trust between clusters.** In the settings of the local deployment or cluster, configure the trust security model that your remote connections will use to access the remote cluster. This step involves specifying API keys or certificates retrieved from the remote clusters. -2. **Establish the connection.** In {{kib}} on the local cluster, finalize the connection by specifying each remote cluster's details. +2. **Establish the connection.** In {{kib}} on the local cluster, or using the {{es}} API, finalize the connection by specifying each remote cluster's details. Find the instructions with details on the supported security models and available connection modes for your specific scenario: diff --git a/deploy-manage/remote-clusters/_snippets/allow-connection-intro.md b/deploy-manage/remote-clusters/_snippets/allow-connection-intro.md index 3e5f9b9a4e..ef1f9f237f 100644 --- a/deploy-manage/remote-clusters/_snippets/allow-connection-intro.md +++ b/deploy-manage/remote-clusters/_snippets/allow-connection-intro.md @@ -19,5 +19,7 @@ Before you start, consider the [security model](/deploy-manage/remote-clusters/s API key : For deployments based on {{stack}} 8.14 or later, you can use an API key to authenticate and authorize cross-cluster operations to a remote cluster. This model uses a dedicated service endpoint, on port `9443` by default, and gives administrators fine-grained control over remote access. The API key is created on the remote cluster and defines the permissions available to all cross-cluster requests, while local user roles can further restrict, but not extend, those permissions. + Starting with {{stack}} 9.3, the API key security model also supports [strong identity verification](/deploy-manage/remote-clusters/security-models.md#remote-cluster-strong-verification), adding an extra layer of security. With this feature, the API key can be restricted to only be usable by requests that present an allowed certificate identity, which the remote cluster validates during authentication. + TLS certificate (deprecated in {{stack}} 9.0.0) : This model uses mutual TLS authentication over the {{es}} transport interface for cross-cluster operations. User authentication is performed on the local cluster and a user's role names are passed to the remote cluster for authorization. Because a superuser on the local cluster automatically gains full read access to the remote cluster, this model is only suitable for clusters within the same security domain. diff --git a/deploy-manage/remote-clusters/_snippets/rcs_strong_identity_how.md b/deploy-manage/remote-clusters/_snippets/rcs_strong_identity_how.md new file mode 100644 index 0000000000..e3785070a7 --- /dev/null +++ b/deploy-manage/remote-clusters/_snippets/rcs_strong_identity_how.md @@ -0,0 +1,11 @@ +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. diff --git a/deploy-manage/remote-clusters/_snippets/rcs_strong_identity_intro.md b/deploy-manage/remote-clusters/_snippets/rcs_strong_identity_intro.md new file mode 100644 index 0000000000..d1422369fa --- /dev/null +++ b/deploy-manage/remote-clusters/_snippets/rcs_strong_identity_intro.md @@ -0,0 +1,9 @@ +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. + +:::{note} +Each remote cluster alias on the local cluster can have different remote signing configurations. +::: diff --git a/deploy-manage/remote-clusters/ec-remote-cluster-other-ess.md b/deploy-manage/remote-clusters/ec-remote-cluster-other-ess.md index 321d9447d2..36b1c01136 100644 --- a/deploy-manage/remote-clusters/ec-remote-cluster-other-ess.md +++ b/deploy-manage/remote-clusters/ec-remote-cluster-other-ess.md @@ -36,6 +36,9 @@ If network security policies are applied to the remote cluster, the remote clust :::{include} _snippets/apikeys-intro.md ::: +:::{note} +To configure strong identity verification together with API key authentication for remote cluster connections, refer to [](./ec-remote-cluster-strong-identity.md). Follow the steps there in addition to the procedure described in this section. +::: ### Prerequisites and limitations [ec_prerequisites_and_limitations_2] diff --git a/deploy-manage/remote-clusters/ec-remote-cluster-same-ess.md b/deploy-manage/remote-clusters/ec-remote-cluster-same-ess.md index 211be83d45..7b8a0cb282 100644 --- a/deploy-manage/remote-clusters/ec-remote-cluster-same-ess.md +++ b/deploy-manage/remote-clusters/ec-remote-cluster-same-ess.md @@ -36,6 +36,9 @@ If network security policies are applied to the remote cluster, the remote clust :::{include} _snippets/apikeys-intro.md ::: +:::{note} +To configure strong identity verification together with API key authentication for remote cluster connections, refer to [](./ec-remote-cluster-strong-identity.md). Follow the steps there in addition to the procedure described in this section. +::: ### Prerequisites and limitations [ec_prerequisites_and_limitations] diff --git a/deploy-manage/remote-clusters/ec-remote-cluster-strong-identity.md b/deploy-manage/remote-clusters/ec-remote-cluster-strong-identity.md new file mode 100644 index 0000000000..48f783701b --- /dev/null +++ b/deploy-manage/remote-clusters/ec-remote-cluster-strong-identity.md @@ -0,0 +1,105 @@ +--- +navigation_title: Strong identity verification +applies_to: + deployment: + ess: ga +products: + - id: cloud-hosted +--- + +# Strong identity verification on {{ech}} + +Starting with {{stack}} 9.3, the [API key security model](./security-models.md) for remote cluster connections supports [strong identity verification](./security-models.md#remote-cluster-strong-verification). This adds an extra layer of security by allowing an API key to be used only by requests that present an allowed certificate identity, which the remote cluster validates during authentication. + +This document describes how to enable strong identity verification for {{ech}} deployments and is intended to augment the standard remote cluster setup tutorials. While following the steps to [configure remote clusters](./ec-enable-ccs.md#set-up-remote-clusters-with-ech) with API key authentication, apply the additional settings and procedures described here. Some settings can be applied independently, while others note the stage in the procedure where you should apply them. + +:::{note} +For steps to configure strong identity verification for other deployment types, refer to [Strong identity verification](./remote-clusters-api-key.md#remote-cluster-strong-verification). +::: + +## Prerequisites + +Both the local and remote clusters must run {{stack}} 9.3 or later to use strong identity verification. + +## Configure strong identity verification + +To use strong identity verification, both the local and remote clusters must be configured to sign and verify cross-cluster request headers. All settings described in this guide are dynamic and can be configured using the [cluster settings API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings) or as static [`elasticsearch.yml` configuration](/deploy-manage/stack-settings.md#configure-stack-settings) settings. + +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). + +### On the local cluster + +When adding the remote cluster to the local cluster, you must configure it to sign cross-cluster requests with a TLS certificate–private key pair. You can either generate and use your own certificate for this purpose or reuse an existing certificate. + +This example configures the local cluster to use the existing transport certificates to sign cross-cluster requests. These certificate files are present in all {{ecloud}} deployments: + +```yaml +cluster.remote..signing.certificate: "node.crt" <1> +cluster.remote..signing.key: "node.key" <1> +``` +1. Replace `` with your remote cluster alias. + +If you use your own certificates, upload the certificate and key files [as a ZIP bundle](/deploy-manage/deploy/elastic-cloud/upload-custom-plugins-bundles.md) and reference them in the settings: + +```yaml +cluster.remote..signing.certificate: "/app/config//" <1> +cluster.remote..signing.key: "/app/config//" <1> +``` +1. Replace `` with your remote cluster alias, and the paths with the paths to your certificate and key files included in the bundle. + +### On the remote cluster + +The certificate and key used by the local cluster to sign cross-cluster requests determine how the remote cluster must be configured. Specifically: + +1. Add the certificate authority (CA) that issued the local cluster certificate to the `cluster.remote.signing.certificate_authorities` setting of the remote cluster: + + ```yaml + cluster.remote.signing.certificate_authorities: "internal_tls_ca.crt" <1> + ``` + 1. This example uses the regional CA certificate file that is available in all {{ecloud}} deployments. This CA is unique per {{ecloud}} region and cloud provider. + + The CA file to configure depends on how the local cluster is set up: + + * If the local cluster uses the default transport certificates, and both the local and remote clusters belong to the same cloud provided and region on {{ecloud}}, you can use the `internal_tls_ca.crt` file that already exist in your cluster. No additional upload is required. + + * If the local cluster uses the default transport certificates, but the remote cluster belongs to a different {{ecloud}} provider or region, you must download the local cluster transport CA and upload it to the remote deployment as a bundle. To do that: + 1. Open your deployment management page in the Elastic Cloud UI and go to **Security**. + 1. Under **CA certificates**, select the download icon to save the CA into a local file. + 1. Add the CA certificate [as a ZIP bundle](/deploy-manage/deploy/elastic-cloud/upload-custom-plugins-bundles.md) in your remote deployment, and reference the file in the `cluster.remote.signing.certificate_authorities` setting. + + * If you use custom certificates in the local cluster, upload the associated CA to the remote cluster [as a ZIP bundle](/deploy-manage/deploy/elastic-cloud/upload-custom-plugins-bundles.md), and reference the file in the `cluster.remote.signing.certificate_authorities` setting. + +1. When creating the cross-cluster API key on the remote cluster, you must specify a `certificate_identity` pattern that matches the Distinguished Name (DN) of the certificate used by the local cluster. + + :::{tip} + In {{ecloud}}, the certificates of all {{es}} nodes follow this Distinguished Name (DN) format: + `CN=.node..cluster.`. + + * The {{es}} `cluster_id` of your deployment can be found on the deployment page in the {{ecloud}} UI by selecting **Copy cluster ID**. + * The `scope_id` corresponds to the {{ecloud}} organization ID. + ::: + + This example creates a cross-cluster API key with a `certificate_identity` pattern that matches the default {{ecloud}} transport certificates for a specific `cluster_id`: + + ```console + POST /_security/cross_cluster/api_key + { + "name": "my-cross-cluster-api-key", + "access": { + "search": [ + { + "names": ["logs-*"] + } + ] + }, + "certificate_identity": "CN=.*.node..cluster.*" <1> + } + ``` + 1. If the local cluster uses custom certificates, adjust the pattern to match their DN instead. + + The `certificate_identity` field supports regular expressions that are matched against the certificate DN. For example: + + * `"CN=.*.example.com,O=Example Corp,C=US"` matches any certificate whose DN starts with a CN that ends in `example.com` and includes `O=Example Corp,C=US`. + * `"CN=local-cluster.*,O=Example Corp,C=US"` matches any certificate whose DN starts with `CN=local-cluster` and includes `O=Example Corp,C=US`. + * `"CN=.*.node..cluster.*"` matches the {{ecloud}} transport certificates for a given `cluster_id`. + * `"CN=.*.node.*.cluster."` matches the {{ecloud}} transport certificates for all clusters in a given ECH organization. diff --git a/deploy-manage/remote-clusters/remote-clusters-api-key.md b/deploy-manage/remote-clusters/remote-clusters-api-key.md index 96aaff2dd4..0b0f8b63b6 100644 --- a/deploy-manage/remote-clusters/remote-clusters-api-key.md +++ b/deploy-manage/remote-clusters/remote-clusters-api-key.md @@ -269,37 +269,28 @@ cluster: ## Strong identity verification [remote-cluster-strong-verification] ```{applies_to} -deployment: - stack: preview 9.3 +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. +::::{include} _snippets/rcs_strong_identity_intro.md +:::: ### 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. +::::{include} _snippets/rcs_strong_identity_how.md +:::: ### 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`. +:::{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}}](./ec-remote-cluster-strong-identity.md). +::: + #### 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. diff --git a/deploy-manage/remote-clusters/security-models.md b/deploy-manage/remote-clusters/security-models.md index 0ad90f5244..dba62139db 100644 --- a/deploy-manage/remote-clusters/security-models.md +++ b/deploy-manage/remote-clusters/security-models.md @@ -46,6 +46,27 @@ Mutual TLS is not required in this model. Refer to [Remote cluster setup](../remote-clusters.md#setup) for configuration guidance across all deployment types. +### Strong identity verification [remote-cluster-strong-verification] +```{applies_to} +stack: preview 9.3 +``` + +::::{include} _snippets/rcs_strong_identity_intro.md +:::: + +#### How strong identity verification works [_how_strong_verification_works] + +::::{include} _snippets/rcs_strong_identity_how.md +:::: + +#### Configure strong identity verification + +To configure strong identity verification for remote clusters, refer to the appropriate guide for your deployment type: +- [Configure strong identity verification on {{ech}} deployments](./ec-remote-cluster-strong-identity.md) +- [Configure strong identity verification in self-managed clusters](./remote-clusters-api-key.md#remote-cluster-strong-verification) + +The self-managed configuration procedure can be adapted to other deployment types, such as {{ece}} and {{eck}}, using the platform-specific methods to apply the required configuration. + ## TLS certificate authentication ```{applies_to} stack: deprecated 9.0 diff --git a/deploy-manage/toc.yml b/deploy-manage/toc.yml index 324cdedffd..92adde0629 100644 --- a/deploy-manage/toc.yml +++ b/deploy-manage/toc.yml @@ -648,6 +648,7 @@ toc: - file: remote-clusters/ec-remote-cluster-ece.md - file: remote-clusters/ec-remote-cluster-self-managed.md - file: remote-clusters/ec-enable-ccs-for-eck.md + - file: remote-clusters/ec-remote-cluster-strong-identity.md - file: remote-clusters/ec-edit-remove-trusted-environment.md - file: remote-clusters/ec-migrate-ccs.md - file: remote-clusters/ece-enable-ccs.md