Skip to content
Merged
Changes from 7 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
84 changes: 83 additions & 1 deletion deploy-manage/remote-clusters/remote-clusters-api-key.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,10 +23,12 @@ 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)


If you run into any issues, refer to [Troubleshooting](/troubleshoot/elasticsearch/remote-clusters.md).

## Prerequisites [remote-clusters-prerequisites-api-key]
Expand Down Expand Up @@ -424,3 +426,83 @@ 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]

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are a lot more settings specified in your reference PR. how does someone know from this procedure when to use those additional settings?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point, I wasn't sure if it made sense to include all settings. This is the most basic configuration to keep it simple, would it make sense to link the other settings here you think?

This is a setup the mirrors our SSL configuration so I could either copy some of the instructions from there or link that too? WDYT?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Including just some settings in the configuration guide should be ok, but probably we should include all settings we want users to know in the Elasticsearch reference docs. Somewhere like here: https://www.elastic.co/docs/reference/elasticsearch/configuration-reference/remote-clusters, or here: https://www.elastic.co/docs/reference/elasticsearch/configuration-reference/networking-settings#remote-cluster-network-settings (we have settings in 2 places).

We have an opened internal issue to review these settings as some of them (remote_cluster_client) are missing in the reference docs.

For your consideration.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Update: I see you have created elastic/elasticsearch#137822! So I'd just wait until the Elasticsearch PR is merged first and then in this PR just link to the reference doc for reference about all available settings, with something like:

For a full list of available strong verification settings for remote clusters, refer to xxxxx.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see that the improved functionlity is named "strong verification", while we (I?) generally use "strong identity verification" elsewhere.

Was there a discussion about that?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, this is an oversight from me. I'll update it! Thanks for reviewing!

```{applies_to}
deployment:
self: preview 9.3
Comment thread
jfreden marked this conversation as resolved.
Outdated
```

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]

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.
Comment thread
jfreden marked this conversation as resolved.
Outdated

```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"
```

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would explicitly mention that the private key can be encrypted and the password must be stored securely in the keystore. People may be wondering otherwise.

::::{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)
Comment thread
jfreden marked this conversation as resolved.
Outdated
Loading