Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions deploy-manage/remote-clusters.md
Original file line number Diff line number Diff line change
Expand Up @@ -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}
Expand All @@ -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:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Original file line number Diff line number Diff line change
@@ -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.
Original file line number Diff line number Diff line change
@@ -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.
:::
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,9 @@
:::{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.

Check notice on line 40 in deploy-manage/remote-clusters/ec-remote-cluster-other-ess.md

View workflow job for this annotation

GitHub Actions / preview / vale

Elastic.Wordiness: Consider using 'also' instead of 'in addition'.
:::

### Prerequisites and limitations [ec_prerequisites_and_limitations_2]

Expand Down
3 changes: 3 additions & 0 deletions deploy-manage/remote-clusters/ec-remote-cluster-same-ess.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,9 @@
:::{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.

Check notice on line 40 in deploy-manage/remote-clusters/ec-remote-cluster-same-ess.md

View workflow job for this annotation

GitHub Actions / preview / vale

Elastic.Wordiness: Consider using 'also' instead of 'in addition'.
:::

### Prerequisites and limitations [ec_prerequisites_and_limitations]

Expand Down
105 changes: 105 additions & 0 deletions deploy-manage/remote-clusters/ec-remote-cluster-strong-identity.md
Original file line number Diff line number Diff line change
@@ -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.<my_remote_cluster>.signing.certificate: "node.crt" <1>
cluster.remote.<my_remote_cluster>.signing.key: "node.key" <1>
```
1. Replace `<my_remote_cluster>` 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.<my_remote_cluster>.signing.certificate: "/app/config/<bundle-zip-directory>/<signing-cert.crt>" <1>
cluster.remote.<my_remote_cluster>.signing.key: "/app/config/<bundle-zip-directory>/<signing-key.key>" <1>
```
1. Replace `<my_remote_cluster>` 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_id>.node.<cluster_id>.cluster.<scope_id>`.

* 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-id>.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-id>.cluster.*"` matches the {{ecloud}} transport certificates for a given `cluster_id`.
* `"CN=.*.node.*.cluster.<org-id>"` matches the {{ecloud}} transport certificates for all clusters in a given ECH organization.
31 changes: 11 additions & 20 deletions deploy-manage/remote-clusters/remote-clusters-api-key.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
21 changes: 21 additions & 0 deletions deploy-manage/remote-clusters/security-models.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions deploy-manage/toc.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading