Skip to content

Commit 9ecc495

Browse files
committed
Add RCS Strong Verification Documentation
1 parent e87b8a3 commit 9ecc495

File tree

1 file changed

+70
-0
lines changed

1 file changed

+70
-0
lines changed

deploy-manage/remote-clusters/remote-clusters-api-key.md

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ To add a remote cluster using API key authentication:
2626
2. [Establish trust with a remote cluster](#remote-clusters-security-api-key)
2727
3. [Connect to a remote cluster](#remote-clusters-connect-api-key)
2828
4. [Configure roles and users](#remote-clusters-privileges-api-key)
29+
5. (Optional) [Configure remote cluster strong verification](#remote-cluster-strong-verification) for additional security
2930

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

@@ -405,3 +406,72 @@ POST /_security/user/cross-search-user
405406
```
406407

407408
Note that you only need to create this user on the local cluster.
409+
410+
411+
## Remote cluster strong verification [remote-cluster-strong-verification]
412+
preview::[]
413+
414+
Cross-cluster API keys can be configured with strong verification to provide an additional layer of security. To enable this feature,
415+
the cross-cluster API key is created with a certificate identity pattern. The local cluster is then required to be configured to sign
416+
the API key for every request to the remote cluster and provide a trusted certificate with a subject matching the certificate identity
417+
pattern that was used when the cross-cluster API key was created.
418+
419+
### How strong verification works [_how_strong_verification_works]
420+
421+
When a local cluster makes a request to a remote cluster using a cross-cluster API key:
422+
423+
1. The local cluster signs the request headers with its configured private key and sends the signature and certificate chain as header
424+
in the request to the remote cluster
425+
2. The remote cluster verifies that the API key is valid
426+
3. If the API key has a certificate identity pattern configured, the remote cluster extracts the Distinguished Name (DN) from the
427+
certificate chain's leaf certificate and matches it against the certificate identity pattern
428+
4. The remote cluster validates that the provided certificate chain is trusted
429+
5. The remote cluster validates the signature and checks that the certificate is not expired
430+
431+
If any of these validation steps fail, the request is rejected.
432+
433+
### Configure strong verification [_configure_strong_verification]
434+
435+
To use certificate identity validation, the local and remote clusters must be configured to sign request headers and to verify request
436+
headers.
437+
438+
#### On the local cluster [_certificate_identity_local_cluster]
439+
440+
The local cluster must be configured to sign cross-cluster requests with a certificate-private key pair.
441+
442+
```yaml
443+
cluster.remote.my_remote_cluster.signing.certificate: "path/to/signing/certificate.crt"
444+
cluster.remote.my_remote_cluster.signing.key: "path/to/signing/key.key"
445+
```
446+
447+
#### On the remote cluster [_certificate_identity_remote_cluster]
448+
449+
The remote cluster must be configured with a certificate authority that trusts the certificate that was used to sign the request headers.
450+
451+
```yaml
452+
cluster.remote.signing.certificate_authorities: "path/to/signing/certificate_authorities.crt"
453+
```
454+
455+
When creating a cross-cluster API key on the remote cluster, specify a `certificate_identity` pattern that matches the Distinguished
456+
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:
457+
458+
```console
459+
POST /_security/cross_cluster/api_key
460+
{
461+
"name": "my-cross-cluster-api-key",
462+
"access": {
463+
"search": [
464+
{
465+
"names": ["logs-*"]
466+
}
467+
]
468+
},
469+
"certificate_identity": "CN=local-cluster.example.com,O=Example Corp,C=US"
470+
}
471+
```
472+
473+
The `certificate_identity` field supports regular expressions. For example:
474+
475+
* `"CN=.*.example.com,O=Example Corp,C=US"` matches any certificate with a CN starting with any subdomain of example.com
476+
* `"CN=local-cluster.*,O=Example Corp,C=US"` matches any certificate with a CN starting with "local-cluster"
477+
* `"CN=.*"` matches any certificate (not recommended for production)

0 commit comments

Comments
 (0)