From 5df4d3e2534a1b6848d9182fd206ae1e7f626a03 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Mon, 26 Oct 2026 12:29:29 +0100 Subject: [PATCH 1/5] Document SAML signing files in ECE bundles AI-Assisted: Cursor GPT-5.6 Sol Co-authored-by: Cursor --- .../add-custom-bundles-plugins.md | 70 +++++++++++-------- 1 file changed, 40 insertions(+), 30 deletions(-) diff --git a/deploy-manage/plugins-and-custom-configuration-files/cloud-enterprise/add-custom-bundles-plugins.md b/deploy-manage/plugins-and-custom-configuration-files/cloud-enterprise/add-custom-bundles-plugins.md index fa1664febb7..536ae0d9b05 100644 --- a/deploy-manage/plugins-and-custom-configuration-files/cloud-enterprise/add-custom-bundles-plugins.md +++ b/deploy-manage/plugins-and-custom-configuration-files/cloud-enterprise/add-custom-bundles-plugins.md @@ -104,8 +104,8 @@ Custom plugins can include the official {{es}} plugins not provided with {{ece}} This example adds a custom LDAP bundle for deployment level role-based access control (RBAC). To set platform level RBAC, check [](/deploy-manage/users-roles/cloud-enterprise-orchestrator/manage-users-roles.md). -1. Prepare a custom bundle as a ZIP file that contains your keystore file with the private key and certificate inside of a `truststore` folder. This bundle allows all {{es}} containers to access the same keystore file through your `ssl.truststore` settings. -2. In the [advanced configuration editor](/deploy-manage/deploy/cloud-enterprise/advanced-cluster-configuration.md), update your new {{es}} cluster with the custom bundle you have created. Modify the `user_bundles` JSON attribute of **each** {{es}} instance type as shown in the following example: +1. Prepare a custom bundle as a ZIP file that contains a trust store with the LDAP server certificate or its issuing Certificate Authority (CA) certificate inside a `truststore` folder. This bundle allows all {{es}} containers to access the same trust store through your `ssl.truststore` settings. +2. In the [advanced configuration editor](/deploy-manage/deploy/cloud-enterprise/advanced-cluster-configuration.md), update your new {{es}} cluster with the custom bundle you have created. Modify the `user_bundles` JSON attribute as shown in the following example: ```sh { @@ -128,9 +128,9 @@ This example adds a custom LDAP bundle for deployment level role-based access co ... ``` - 1. The URLs for the bundle ZIP files (`ldapcert.zip`) must be always available. Make sure you host the plugin artifacts internally in a highly available environment. + 1. The URL for the bundle ZIP file (`ldapcert.zip`) must always be available. Host the bundle internally in a highly available environment. -3. Note where the bundle contents are placed, so that you can reference the keystore in your `ssl.truststore` settings. +3. Note where the bundle contents are placed, so that you can reference the trust store in your `ssl.truststore` settings. ```sh $ tree . @@ -139,19 +139,33 @@ This example adds a custom LDAP bundle for deployment level role-based access co └── keystore.ks ``` - In this example, the unzipped keystore file gets placed under `/app/config/truststore/keystore.ks`. + In this example, the unzipped trust store file gets placed under `/app/config/truststore/keystore.ks`. ## Example: Add a custom SAML bundle [ece-add-custom-bundle-example-SAML] -This example adds a custom SAML bundle for deployment level role-based access control (RBAC). To set platform level RBAC, check [](/deploy-manage/users-roles/cloud-enterprise-orchestrator/manage-users-roles.md). +This example adds a custom SAML bundle for deployment-level role-based access control (RBAC). To configure platform-level RBAC, refer to [](/deploy-manage/users-roles/cloud-enterprise-orchestrator/manage-users-roles.md). -In this example, we assume the Identity Provider does not publish its SAML metadata at an HTTP URL, so we provide it through a custom bundle. +We assume that the Identity Provider does not publish its SAML metadata at an HTTP URL, so the bundle contains the metadata file required to configure the realm. The example also shows how to optionally include and configure a signing certificate and key for [signing outgoing SAML messages](/deploy-manage/users-roles/cluster-or-deployment-auth/saml.md#saml-enc-sign) when required by the Identity Provider or your organization. -1. Prepare a ZIP file with a custom bundle that contains your Identity Provider’s metadata (`metadata.xml`). Place the file inside a `saml` folder within the ZIP (`saml/metadata.xml`). +1. Prepare a ZIP file that contains the Identity Provider metadata at `saml/metadata.xml`. - This bundle will allow all {{es}} containers to access the metadata file. + If you configure signing, follow [Configure SAML signing and encryption](/deploy-manage/users-roles/cluster-or-deployment-auth/saml-signing-encryption.md) to generate a signing certificate and key. Add `saml-sign.crt` and `saml-sign.key` to the same `saml` folder. -2. In the [advanced configuration editor](/deploy-manage/deploy/cloud-enterprise/advanced-cluster-configuration.md), update your {{es}} cluster configuration with the bundle you prepared in the previous step. Modify the `user_bundles` JSON attribute of **each** {{es}} instance type as shown in the following example: + If the signing private key is protected with a passphrase, you must add the passphrase as a secure setting before you configure the realm in step 3. + + Structure the files in the ZIP as follows: + + ```text + $ tree . + . + └── saml + ├── metadata.xml + ├── saml-sign.crt <1> + └── saml-sign.key <1> + ``` + 1. Include the signing certificate and key when you configure signing for outgoing SAML messages. + +2. In the [advanced configuration editor](/deploy-manage/deploy/cloud-enterprise/advanced-cluster-configuration.md), update your {{es}} cluster configuration with the bundle you prepared in the previous step. Modify the `user_bundles` JSON attribute as shown in the following example: ```text { @@ -165,8 +179,8 @@ In this example, we assume the Identity Provider does not publish its SAML metad ... "user_bundles": [ { - "name": "saml-metadata", - "url": "/saml-metadata.zip", <1> + "name": "saml-files", + "url": "/saml-files.zip", <1> "elasticsearch_version": "*" } ] @@ -174,28 +188,24 @@ In this example, we assume the Identity Provider does not publish its SAML metad ... ``` - 1. The URL for the bundle ZIP file must be always available. Make sure you host the plugin artifacts internally in a highly available environment. - - These file locations are needed in the next step. + 1. The URL for the bundle ZIP file must always be available. Host the bundle internally in a highly available environment. - In this example, the SAML metadata file is located in the path `/app/config/saml/metadata.xml`: +3. After the bundle is associated with the deployment, its files are available under `/app/config` on every {{es}} node. Follow [SAML authentication](/deploy-manage/users-roles/cluster-or-deployment-auth/saml.md) to configure the realm. In [](/deploy-manage/deploy/cloud-enterprise/edit-stack-settings.md), reference the metadata file from the bundle: - ```sh - $ tree . - . - └── saml - └── metadata.xml + ```yaml + idp.metadata.path: /app/config/saml/metadata.xml ``` -3. Adjust your `saml` realm configuration accordingly through [](/deploy-manage/deploy/cloud-enterprise/edit-stack-settings.md): + If you prepared the signing certificate and key, add their paths to the same realm configuration: - ```sh - idp.metadata.path: /app/config/saml/metadata.xml <1> + ```yaml + signing.certificate: /app/config/saml/saml-sign.crt + signing.key: /app/config/saml/saml-sign.key ``` - 1. The path to the SAML metadata file that was uploaded + If the signing private key is protected with a passphrase, store the passphrase as the `xpack.security.authc.realms.saml..signing.secure_key_passphrase` [secure setting](/deploy-manage/security/secure-settings.md) before you apply this realm configuration. - Refer to [](/deploy-manage/users-roles/cluster-or-deployment-auth/saml.md) for more details on SAML authentication. + Provide the signing certificate to your Identity Provider so that it can verify the signed messages. ## Example: Add a custom JVM trust store bundle [ece-add-custom-bundle-example-cacerts] @@ -254,7 +264,7 @@ To import a JVM trust store: A bundle may contain other contents beyond the trust store if you prefer, but we recommend creating separate bundles for different purposes. :::: -3. In the [advanced configuration editor](/deploy-manage/deploy/cloud-enterprise/advanced-cluster-configuration.md), update your {{es}} cluster configuration with the bundle you prepared in the previous step. Modify the `user_bundles` JSON attribute of **each** {{es}} instance type as shown in the following example: +3. In the [advanced configuration editor](/deploy-manage/deploy/cloud-enterprise/advanced-cluster-configuration.md), update your {{es}} cluster configuration with the bundle you prepared in the previous step. Modify the `user_bundles` JSON attribute as shown in the following example: ```sh { @@ -276,7 +286,7 @@ To import a JVM trust store: } ... ``` - 1. The URL for the bundle ZIP file must be always available. Make sure you host the plugin artefacts internally in a highly available environment. + 1. The URL for the bundle ZIP file must always be available. Host the bundle internally in a highly available environment. 2. Wildcards are allowed here, since the certificates are independent from the {{es}} version. 4. (Optional) If you prefer to use a different file name and/or password for the trust store, you also need to add an additional configuration section to the cluster metadata before adding the bundle. This configuration should be added to the `Elasticsearch cluster data` section of the [advanced configuration](/deploy-manage/deploy/cloud-enterprise/advanced-cluster-configuration.md) page: @@ -309,7 +319,7 @@ To import a JVM trust store: ``` 2. Copy the ZIP file to a webserver that is reachable from any allocator in your environment. -3. In the [advanced configuration editor](/deploy-manage/deploy/cloud-enterprise/advanced-cluster-configuration.md), update your {{es}} cluster configuration with the bundle you prepared in the previous step. Modify the `user_bundles` JSON attribute of **each** {{es}} instance type as shown in the following example. +3. In the [advanced configuration editor](/deploy-manage/deploy/cloud-enterprise/advanced-cluster-configuration.md), update your {{es}} cluster configuration with the bundle you prepared in the previous step. Modify the `user_bundles` JSON attribute as shown in the following example. ```sh { @@ -359,7 +369,7 @@ To import a JVM trust store: ``` 2. Copy the ZIP file to a webserver that is reachable from any allocator in your environment. -3. In the [advanced configuration editor](/deploy-manage/deploy/cloud-enterprise/advanced-cluster-configuration.md), update your {{es}} cluster configuration with the bundle you prepared in the previous step. Modify the `user_bundles` JSON attribute of **each** {{es}} instance type as shown in the following example. +3. In the [advanced configuration editor](/deploy-manage/deploy/cloud-enterprise/advanced-cluster-configuration.md), update your {{es}} cluster configuration with the bundle you prepared in the previous step. Modify the `user_bundles` JSON attribute as shown in the following example. ```sh { From f5c2f3d7866b2eaaca9a6055e53871cf327be47d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Mon, 26 Oct 2026 12:31:11 +0100 Subject: [PATCH 2/5] Link ECE bundle example to SAML metadata guidance AI-Assisted: Cursor GPT-5.6 Sol Co-authored-by: Cursor --- .../cloud-enterprise/add-custom-bundles-plugins.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deploy-manage/plugins-and-custom-configuration-files/cloud-enterprise/add-custom-bundles-plugins.md b/deploy-manage/plugins-and-custom-configuration-files/cloud-enterprise/add-custom-bundles-plugins.md index 536ae0d9b05..fcf5ef816c4 100644 --- a/deploy-manage/plugins-and-custom-configuration-files/cloud-enterprise/add-custom-bundles-plugins.md +++ b/deploy-manage/plugins-and-custom-configuration-files/cloud-enterprise/add-custom-bundles-plugins.md @@ -145,7 +145,7 @@ This example adds a custom LDAP bundle for deployment level role-based access co This example adds a custom SAML bundle for deployment-level role-based access control (RBAC). To configure platform-level RBAC, refer to [](/deploy-manage/users-roles/cloud-enterprise-orchestrator/manage-users-roles.md). -We assume that the Identity Provider does not publish its SAML metadata at an HTTP URL, so the bundle contains the metadata file required to configure the realm. The example also shows how to optionally include and configure a signing certificate and key for [signing outgoing SAML messages](/deploy-manage/users-roles/cluster-or-deployment-auth/saml.md#saml-enc-sign) when required by the Identity Provider or your organization. +We assume that the Identity Provider does not publish its [SAML metadata](/deploy-manage/users-roles/cluster-or-deployment-auth/saml.md#saml-guide-idp) at an HTTPS URL, so the bundle contains the metadata file required to configure the realm. The example also shows how to optionally include and configure a signing certificate and key for [signing outgoing SAML messages](/deploy-manage/users-roles/cluster-or-deployment-auth/saml.md#saml-enc-sign) when required by the Identity Provider or your organization. 1. Prepare a ZIP file that contains the Identity Provider metadata at `saml/metadata.xml`. From da1874720a880f8d389108dde0bf905b95babb7f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Mon, 26 Oct 2026 12:33:25 +0100 Subject: [PATCH 3/5] Clarify SAML signing configuration order AI-Assisted: Cursor GPT-5.6 Sol Co-authored-by: Cursor --- .../cloud-enterprise/add-custom-bundles-plugins.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/deploy-manage/plugins-and-custom-configuration-files/cloud-enterprise/add-custom-bundles-plugins.md b/deploy-manage/plugins-and-custom-configuration-files/cloud-enterprise/add-custom-bundles-plugins.md index fcf5ef816c4..0db36df30be 100644 --- a/deploy-manage/plugins-and-custom-configuration-files/cloud-enterprise/add-custom-bundles-plugins.md +++ b/deploy-manage/plugins-and-custom-configuration-files/cloud-enterprise/add-custom-bundles-plugins.md @@ -196,17 +196,13 @@ We assume that the Identity Provider does not publish its [SAML metadata](/deplo idp.metadata.path: /app/config/saml/metadata.xml ``` - If you prepared the signing certificate and key, add their paths to the same realm configuration: + If you prepared the signing certificate and key, configure signing in the same realm. If the private key is protected with a passphrase, first store the passphrase as the `xpack.security.authc.realms.saml..signing.secure_key_passphrase` [secure setting](/deploy-manage/security/secure-settings.md). Then add the following settings: ```yaml signing.certificate: /app/config/saml/saml-sign.crt signing.key: /app/config/saml/saml-sign.key ``` - If the signing private key is protected with a passphrase, store the passphrase as the `xpack.security.authc.realms.saml..signing.secure_key_passphrase` [secure setting](/deploy-manage/security/secure-settings.md) before you apply this realm configuration. - - Provide the signing certificate to your Identity Provider so that it can verify the signed messages. - ## Example: Add a custom JVM trust store bundle [ece-add-custom-bundle-example-cacerts] If you are using SSL certificates signed by non-public certificate authorities, {{es}} is not able to communicate with the services using those certificates unless you import a custom JVM trust store containing the certificates of your signing authority into your {{ece}} installation. You’ll need the trust store to access snapshot repositories like MinIO, for your {{ece}} proxy, or to reindex from remote. From 0ddf1e9d429825f44775175ced61f28988188ba0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Mon, 26 Oct 2026 12:39:13 +0100 Subject: [PATCH 4/5] Limit LDAP edits to bundle terminology AI-Assisted: Cursor GPT-5.6 Sol Co-authored-by: Cursor --- .../cloud-enterprise/add-custom-bundles-plugins.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/deploy-manage/plugins-and-custom-configuration-files/cloud-enterprise/add-custom-bundles-plugins.md b/deploy-manage/plugins-and-custom-configuration-files/cloud-enterprise/add-custom-bundles-plugins.md index 0db36df30be..ae16786e52d 100644 --- a/deploy-manage/plugins-and-custom-configuration-files/cloud-enterprise/add-custom-bundles-plugins.md +++ b/deploy-manage/plugins-and-custom-configuration-files/cloud-enterprise/add-custom-bundles-plugins.md @@ -104,8 +104,8 @@ Custom plugins can include the official {{es}} plugins not provided with {{ece}} This example adds a custom LDAP bundle for deployment level role-based access control (RBAC). To set platform level RBAC, check [](/deploy-manage/users-roles/cloud-enterprise-orchestrator/manage-users-roles.md). -1. Prepare a custom bundle as a ZIP file that contains a trust store with the LDAP server certificate or its issuing Certificate Authority (CA) certificate inside a `truststore` folder. This bundle allows all {{es}} containers to access the same trust store through your `ssl.truststore` settings. -2. In the [advanced configuration editor](/deploy-manage/deploy/cloud-enterprise/advanced-cluster-configuration.md), update your new {{es}} cluster with the custom bundle you have created. Modify the `user_bundles` JSON attribute as shown in the following example: +1. Prepare a custom bundle as a ZIP file that contains your keystore file with the private key and certificate inside of a `truststore` folder. This bundle allows all {{es}} containers to access the same keystore file through your `ssl.truststore` settings. +2. In the [advanced configuration editor](/deploy-manage/deploy/cloud-enterprise/advanced-cluster-configuration.md), update your new {{es}} cluster with the custom bundle you have created. Modify the `user_bundles` JSON attribute of **each** {{es}} instance type as shown in the following example: ```sh { @@ -130,7 +130,7 @@ This example adds a custom LDAP bundle for deployment level role-based access co 1. The URL for the bundle ZIP file (`ldapcert.zip`) must always be available. Host the bundle internally in a highly available environment. -3. Note where the bundle contents are placed, so that you can reference the trust store in your `ssl.truststore` settings. +3. Note where the bundle contents are placed, so that you can reference the keystore in your `ssl.truststore` settings. ```sh $ tree . @@ -139,7 +139,7 @@ This example adds a custom LDAP bundle for deployment level role-based access co └── keystore.ks ``` - In this example, the unzipped trust store file gets placed under `/app/config/truststore/keystore.ks`. + In this example, the unzipped keystore file gets placed under `/app/config/truststore/keystore.ks`. ## Example: Add a custom SAML bundle [ece-add-custom-bundle-example-SAML] From 0690d58da5bda94958937fc5cf1ebe90f9ff76b4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Mon, 26 Oct 2026 12:57:28 +0100 Subject: [PATCH 5/5] Restructure custom bundle examples Co-authored-by: Cursor --- .../cloud-enterprise/add-custom-bundles-plugins.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/deploy-manage/plugins-and-custom-configuration-files/cloud-enterprise/add-custom-bundles-plugins.md b/deploy-manage/plugins-and-custom-configuration-files/cloud-enterprise/add-custom-bundles-plugins.md index ae16786e52d..c8e2f89481f 100644 --- a/deploy-manage/plugins-and-custom-configuration-files/cloud-enterprise/add-custom-bundles-plugins.md +++ b/deploy-manage/plugins-and-custom-configuration-files/cloud-enterprise/add-custom-bundles-plugins.md @@ -100,7 +100,11 @@ Custom plugins can include the official {{es}} plugins not provided with {{ece}} 6. To verify that all nodes have the plugins installed, use one of these commands: `GET /_nodes/plugins?filter_path=nodes.*.plugins` or `GET _cat/plugins?v` -## Example: Add a custom LDAP bundle [ece-add-custom-bundle-example-LDAP] +## Examples [ece-custom-bundle-examples] + +The following examples show how to use custom bundles to make additional files available to {{es}} deployments. + +### Add a custom LDAP bundle [ece-add-custom-bundle-example-LDAP] This example adds a custom LDAP bundle for deployment level role-based access control (RBAC). To set platform level RBAC, check [](/deploy-manage/users-roles/cloud-enterprise-orchestrator/manage-users-roles.md). @@ -141,7 +145,7 @@ This example adds a custom LDAP bundle for deployment level role-based access co In this example, the unzipped keystore file gets placed under `/app/config/truststore/keystore.ks`. -## Example: Add a custom SAML bundle [ece-add-custom-bundle-example-SAML] +### Add a custom SAML bundle [ece-add-custom-bundle-example-SAML] This example adds a custom SAML bundle for deployment-level role-based access control (RBAC). To configure platform-level RBAC, refer to [](/deploy-manage/users-roles/cloud-enterprise-orchestrator/manage-users-roles.md). @@ -203,7 +207,7 @@ We assume that the Identity Provider does not publish its [SAML metadata](/deplo signing.key: /app/config/saml/saml-sign.key ``` -## Example: Add a custom JVM trust store bundle [ece-add-custom-bundle-example-cacerts] +### Add a custom JVM trust store bundle [ece-add-custom-bundle-example-cacerts] If you are using SSL certificates signed by non-public certificate authorities, {{es}} is not able to communicate with the services using those certificates unless you import a custom JVM trust store containing the certificates of your signing authority into your {{ece}} installation. You’ll need the trust store to access snapshot repositories like MinIO, for your {{ece}} proxy, or to reindex from remote. @@ -301,7 +305,7 @@ To import a JVM trust store: * You do not need to do this step if you are using default filename and password (`cacerts` and `changeit` respectively) in your bundle. :::: -## Example: Add a custom GeoIP database bundle [ece-add-custom-bundle-example-geoip] +### Add a custom GeoIP database bundle [ece-add-custom-bundle-example-geoip] 1. Prepare a ZIP file with a custom bundle that contains a: [GeoLite2 database](https://dev.maxmind.com/geoip/geoip2/geolite2). The folder has to be named `ingest-geoip`, and the file name can be anything that is appended `-(City|Country|ASN)` with the `mmdb` file extension, and it must have a different name than the original name `GeoLite2-City.mmdb`. @@ -351,7 +355,7 @@ To import a JVM trust store: ... ``` -## Example: Add a custom synonyms bundle [ece-add-custom-bundle-example-synonyms] +### Add a custom synonyms bundle [ece-add-custom-bundle-example-synonyms] 1. Prepare a ZIP file with a custom bundle that contains a dictionary of synonyms in a text file.