From 131c220c2d37b1a2ceb60ecc0ab8998e94aedd15 Mon Sep 17 00:00:00 2001 From: Divyanshi Chouksey Date: Mon, 23 Jun 2025 03:48:11 -0700 Subject: [PATCH 1/7] Added documentation for Security Configuration Versioning and Rollback API Signed-off-by: Divyanshi Chouksey --- .../versioning-for-security-configurations.md | 59 +++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 _security/configuration/versioning-for-security-configurations.md diff --git a/_security/configuration/versioning-for-security-configurations.md b/_security/configuration/versioning-for-security-configurations.md new file mode 100644 index 00000000000..d027ff626e4 --- /dev/null +++ b/_security/configuration/versioning-for-security-configurations.md @@ -0,0 +1,59 @@ +# Security Configuration Versioning and Rollback API + +## Overview + +OpenSearch now supports **versioning of security configurations** to improve traceability, auditability, and operational safety. Each update to critical security configurations is tracked as a new version, and users can view or roll back to any previous version via the dedicated APIs. + +This documentation covers: +- How versioning works +- How to use the View API to inspect past versions +- How to use the Rollback API to restore configurations + +--- + +## 1. Versioning Overview + +### What is versioned? + +Any supported security configuration update is captured as a new version. A version includes: +- Snapshot of the full security configuration at that time +- A unique version ID (e.g., `v1`, `v2`, ...) +- Timestamp of creation +- User who performed the update + +### When is a new version created? + +A new version is created **only when a change is detected** compared to the latest saved version. This prevents redundant versions and ensures meaningful version history. + +--- + +## 2. View Version API + +Purpose: View the complete history of security configuration changes, or any specific version of the security configurations. + +### Endpoint: +- To view all the versions : GET /_plugins/_security/api/versions +- To view a specific version : GET /_plugins/_security/api/version/{versionId} + +Access Control: Admin/Security Manager permissions required + +## 3. Rollback Version API + +Purpose : Allows rollback to immediate or any desired version of security + +### Endpoint: +- To rollback to immediate previous version : POST /_plugins/_security/api/version/rollback +- To rollback to a specific version : POST /_plugins/_security/api/version/rollback/{versionID} + +Access Control: Admin/Security Manager permissions required + +## 4. Enabling the Feature + +* To enable this feature, add the following setting to your `opensearch.yml` file: +```bash +plugins.security.configurations_versions.enabled: true +``` +* Optional: Control how many versions are retained using: +```bash +plugins.security.config_version.retention_count: 10 +``` \ No newline at end of file From 2c993b84d080dc7c2557cff230f3566eef7157ef Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Wed, 1 Oct 2025 15:30:38 -0400 Subject: [PATCH 2/7] Doc review Signed-off-by: Fanit Kolchina --- .../versioning-for-security-configurations.md | 59 ----- _security/configuration/versioning.md | 228 ++++++++++++++++++ 2 files changed, 228 insertions(+), 59 deletions(-) delete mode 100644 _security/configuration/versioning-for-security-configurations.md create mode 100644 _security/configuration/versioning.md diff --git a/_security/configuration/versioning-for-security-configurations.md b/_security/configuration/versioning-for-security-configurations.md deleted file mode 100644 index d027ff626e4..00000000000 --- a/_security/configuration/versioning-for-security-configurations.md +++ /dev/null @@ -1,59 +0,0 @@ -# Security Configuration Versioning and Rollback API - -## Overview - -OpenSearch now supports **versioning of security configurations** to improve traceability, auditability, and operational safety. Each update to critical security configurations is tracked as a new version, and users can view or roll back to any previous version via the dedicated APIs. - -This documentation covers: -- How versioning works -- How to use the View API to inspect past versions -- How to use the Rollback API to restore configurations - ---- - -## 1. Versioning Overview - -### What is versioned? - -Any supported security configuration update is captured as a new version. A version includes: -- Snapshot of the full security configuration at that time -- A unique version ID (e.g., `v1`, `v2`, ...) -- Timestamp of creation -- User who performed the update - -### When is a new version created? - -A new version is created **only when a change is detected** compared to the latest saved version. This prevents redundant versions and ensures meaningful version history. - ---- - -## 2. View Version API - -Purpose: View the complete history of security configuration changes, or any specific version of the security configurations. - -### Endpoint: -- To view all the versions : GET /_plugins/_security/api/versions -- To view a specific version : GET /_plugins/_security/api/version/{versionId} - -Access Control: Admin/Security Manager permissions required - -## 3. Rollback Version API - -Purpose : Allows rollback to immediate or any desired version of security - -### Endpoint: -- To rollback to immediate previous version : POST /_plugins/_security/api/version/rollback -- To rollback to a specific version : POST /_plugins/_security/api/version/rollback/{versionID} - -Access Control: Admin/Security Manager permissions required - -## 4. Enabling the Feature - -* To enable this feature, add the following setting to your `opensearch.yml` file: -```bash -plugins.security.configurations_versions.enabled: true -``` -* Optional: Control how many versions are retained using: -```bash -plugins.security.config_version.retention_count: 10 -``` \ No newline at end of file diff --git a/_security/configuration/versioning.md b/_security/configuration/versioning.md new file mode 100644 index 00000000000..0260b85a720 --- /dev/null +++ b/_security/configuration/versioning.md @@ -0,0 +1,228 @@ +--- +layout: default +title: Security configuration versioning +parent: Configuration +nav_order: 27 +--- + +# Security Configuration Versioning and Rollback API +**Introduced 3.3** +{: .label .label-purple } + +The Security Configuration Versioning and Rollback API provides version control for OpenSearch security configurations, enabling administrators to track changes, maintain audit trails, and restore previous configurations when needed. + +This API automatically creates versions when security configurations change, allowing you to track the complete history of security configuration modifications, view detailed information about any previous version, and roll back to any previous configuration version, thus maintaining operational safety. + +## How versioning works + +The system automatically creates a new version when a security configuration change is detected, the change differs from the most recent saved version, and an administrator makes modifications through supported APIs. + +Each version contains a version ID (unique identifier such as `v1`, `v2`), a configuration snapshot (complete security configuration at the time of creation), a timestamp indicating when the version was created, and user information identifying who made the change. + +A new version is created **only when a change is detected** compared to the latest saved version. This prevents redundant versions and ensures meaningful version history. + +## Enabling versioning + +To use the security configuration versioning, you must enable it in your OpenSearch configuration. Add the following setting to your `opensearch.yml` configuration file: + +```yaml +plugins.security.configurations_versions.enabled: true +``` + +Optionally, you can control the number of retained versions by specifying the following setting: + +```yaml +plugins.security.config_version.retention_count: 10 +``` + +The default retention count is versions, with a valid range of versions. When the retention limit is reached, + +After modifying `opensearch.yml`, restart your OpenSearch cluster for the changes to take effect. For more information, see [Experimental feature flags]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/experimental/). + +## Endpoints + +```json +GET /_plugins/_security/api/versions +GET /_plugins/_security/api/version/ +POST /_plugins/_security/api/version/rollback +POST /_plugins/_security/api/version/rollback/ +``` + +## Path parameters + +The following table lists the available path parameters. All path parameters are optional. + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `version_id` | String | The version identifier to view or roll back to (for example, `v1`, `v2`). Required for specific version operations. | + +## View a specific version + +Use this endpoint to retrieve the complete security configuration for a specified version. + +### Endpoint + +```json +GET /_plugins/_security/api/version/ +``` + +### Example request + +```json +GET /_plugins/_security/api/version/v2 +``` +{% include copy-curl.html %} + +### Example response + + + +```json +``` + +### Response body fields + +The following table lists all response body fields for viewing a specific version. + + + +| Field | Data type | Description | +| :--- | :--- | :--- | +| | | | + +## View all versions + +Use this endpoint to retrieve a list of all available configuration versions. + +### Endpoint + +```json +GET /_plugins/_security/api/versions +``` + +### Example request + +```json +GET /_plugins/_security/api/versions +``` +{% include copy-curl.html %} + +### Example response + + + +```json +``` + +### Response body fields + +The following table lists all response body fields for viewing all versions. + + + +| Field | Data type | Description | +| :--- | :--- | :--- | +| | | | + +## Roll back to previous version + +Use this endpoint to restore the security configuration to the immediately preceding version. + + + +### Endpoint + +```json +POST /_plugins/_security/api/version/rollback +``` + +### Example request + +```json +POST /_plugins/_security/api/version/rollback +``` +{% include copy-curl.html %} + +### Example response + + + +```json +``` + +### Response body fields + +The following table lists all response body fields for rollback operations. + + + +| Field | Data type | Description | +| :--- | :--- | :--- | +| | | | + +## Roll back to a specific version + +Use this endpoint to restore the security configuration to a specified version. + + + +### Endpoint + +```json +POST /_plugins/_security/api/version/rollback/ +``` + +### Example request + +```json +POST /_plugins/_security/api/version/rollback/v1 +``` +{% include copy-curl.html %} + +### Example response + + + +```json +``` + +### Response body fields + +The following table lists all response body fields for rollback operations. + + + +| Field | Data type | Description | +| :--- | :--- | :--- | +| | | | + +## Required permissions + +Ensure that you have the appropriate permissions for the operations you want to perform. + + + +## Limitations + + \ No newline at end of file From 11ebb12ba1ca49ff49b1cb61158acde3aa03abaa Mon Sep 17 00:00:00 2001 From: Nagaraj G Date: Thu, 9 Oct 2025 20:01:29 +0530 Subject: [PATCH 3/7] Add documentation for Experimental Security Configuration Versioning Management and its APIs Signed-off-by: Nagaraj G --- _security/configuration/versioning.md | 105 ++++++++++++++------------ 1 file changed, 58 insertions(+), 47 deletions(-) diff --git a/_security/configuration/versioning.md b/_security/configuration/versioning.md index 0260b85a720..ec053edd1d7 100644 --- a/_security/configuration/versioning.md +++ b/_security/configuration/versioning.md @@ -35,7 +35,7 @@ Optionally, you can control the number of retained versions by specifying the fo plugins.security.config_version.retention_count: 10 ``` -The default retention count is versions, with a valid range of versions. When the retention limit is reached, +The default retention count is 10 versions, with a valid range of v1 to vN versions. When the retention limit is reached, the oldest version is automatically removed to make space for new one version After modifying `opensearch.yml`, restart your OpenSearch cluster for the changes to take effect. For more information, see [Experimental feature flags]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/experimental/). @@ -75,9 +75,17 @@ GET /_plugins/_security/api/version/v2 ### Example response - - ```json +{ + "versions": [ + { + "version_id": "v2", + "timestamp": "2025-05-23T06:56:20.081933886Z", + "modified_by": "admin", + "security_configs": {...} + } + ] +} ``` ### Response body fields @@ -86,9 +94,13 @@ The following table lists all response body fields for viewing a specific versio -| Field | Data type | Description | -| :--- | :--- | :--- | -| | | | +| Field | Data type | Description | +|:-----------------|:----------|:------------------------------------------------------------------------------------------| +| versions | Array | Array of security configuration versions | +| version_id | String | Version of security configuration | +| timestamp | Datetime | Timestamp of security configuration change | +| modified_by | String | User who modified security configuration | +| security_configs | String | Security configuration for a particular version. It holds all the security configurations | ## View all versions @@ -109,9 +121,23 @@ GET /_plugins/_security/api/versions ### Example response - - ```json +{ + "versions": [ + { + "version_id": "v1", + "timestamp": "2025-05-22T08:46:11.887620466Z", + "modified_by": "admin", + "security_configs": {...} + }, + { + "version_id": "v2", + "timestamp": "2025-05-23T06:56:20.081933886Z", + "modified_by": "admin", + "security_configs": {...} + } + ] +} ``` ### Response body fields @@ -122,20 +148,16 @@ The following table lists all response body fields for viewing all versions. | Field | Data type | Description | | :--- | :--- | :--- | -| | | | +| versions | Array | Array of security configuration versions | +| version_id | String | Version of security configuration | +| timestamp | Datetime | Timestamp of security configuration change | +| modified_by | String | User who modified security configuration | +| security_configs | String | Security configuration for a particular version. It holds all the security configurations | ## Roll back to previous version Use this endpoint to restore the security configuration to the immediately preceding version. - - ### Endpoint ```json @@ -151,33 +173,28 @@ POST /_plugins/_security/api/version/rollback ### Example response - +Assuming there are 5 versions and v4 is the preceding version ```json +{ + "status" : "OK", + "message" : "config rolled back to version v4" +} ``` ### Response body fields The following table lists all response body fields for rollback operations. - - | Field | Data type | Description | | :--- | :--- | :--- | -| | | | +| status | String | Rollback status | +| message | String | Description of rollback operation | ## Roll back to a specific version Use this endpoint to restore the security configuration to a specified version. - - ### Endpoint ```json @@ -187,42 +204,36 @@ POST /_plugins/_security/api/version/rollback/ ### Example request ```json -POST /_plugins/_security/api/version/rollback/v1 +POST /_plugins/_security/api/version/rollback/v2 ``` {% include copy-curl.html %} ### Example response - - ```json +{ + "status" : "OK", + "message" : "config rolled back to version v2" +} ``` ### Response body fields The following table lists all response body fields for rollback operations. - - -| Field | Data type | Description | -| :--- | :--- | :--- | -| | | | +| Field | Data type | Description | +|:--------|:----------|:----------------------------------| +| status | String | Rollback status | +| message | String | Description of rollback operation | ## Required permissions Ensure that you have the appropriate permissions for the operations you want to perform. - - -## Limitations - - \ No newline at end of file +These API follow same [access control]({{site.url}}{{site.baseurl}}/access-control/api/#access-control-for-the-api) like any other security API. From 0f715e3466430b84b76cea2d0c5cca5019cc5a13 Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Thu, 9 Oct 2025 13:30:35 -0400 Subject: [PATCH 4/7] Doc review Signed-off-by: Fanit Kolchina --- _security/configuration/versioning.md | 48 ++++++++++----------------- 1 file changed, 17 insertions(+), 31 deletions(-) diff --git a/_security/configuration/versioning.md b/_security/configuration/versioning.md index ec053edd1d7..12b69ad3872 100644 --- a/_security/configuration/versioning.md +++ b/_security/configuration/versioning.md @@ -9,6 +9,9 @@ nav_order: 27 **Introduced 3.3** {: .label .label-purple } +This is an experimental feature and is not recommended for use in a production environment. For updates on the progress of the feature or if you want to leave feedback, join the discussion on the [OpenSearch forum](https://forum.opensearch.org/). +{: .warning} + The Security Configuration Versioning and Rollback API provides version control for OpenSearch security configurations, enabling administrators to track changes, maintain audit trails, and restore previous configurations when needed. This API automatically creates versions when security configurations change, allowing you to track the complete history of security configuration modifications, view detailed information about any previous version, and roll back to any previous configuration version, thus maintaining operational safety. @@ -35,7 +38,7 @@ Optionally, you can control the number of retained versions by specifying the fo plugins.security.config_version.retention_count: 10 ``` -The default retention count is 10 versions, with a valid range of v1 to vN versions. When the retention limit is reached, the oldest version is automatically removed to make space for new one version +The default retention count is `10` versions. When the retention limit is reached, the oldest version is automatically removed to make space for new one version After modifying `opensearch.yml`, restart your OpenSearch cluster for the changes to take effect. For more information, see [Experimental feature flags]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/experimental/). @@ -92,15 +95,13 @@ GET /_plugins/_security/api/version/v2 The following table lists all response body fields for viewing a specific version. - - | Field | Data type | Description | |:-----------------|:----------|:------------------------------------------------------------------------------------------| -| versions | Array | Array of security configuration versions | -| version_id | String | Version of security configuration | -| timestamp | Datetime | Timestamp of security configuration change | -| modified_by | String | User who modified security configuration | -| security_configs | String | Security configuration for a particular version. It holds all the security configurations | +| `versions` | Array | A list of security configuration versions. | +| `version_id` | String | The ID of the security configuration version. | +| `timestamp` | Datetime | The timestamp of the security configuration change. | +| `modified_by` | String | The user who modified the security configuration. | +| `security_configs` | String | The security configuration for a particular version that contains all security configurations. | ## View all versions @@ -142,17 +143,7 @@ GET /_plugins/_security/api/versions ### Response body fields -The following table lists all response body fields for viewing all versions. - - - -| Field | Data type | Description | -| :--- | :--- | :--- | -| versions | Array | Array of security configuration versions | -| version_id | String | Version of security configuration | -| timestamp | Datetime | Timestamp of security configuration change | -| modified_by | String | User who modified security configuration | -| security_configs | String | Security configuration for a particular version. It holds all the security configurations | +See [View a specific version response body fields](#response-body-fields). ## Roll back to previous version @@ -173,7 +164,7 @@ POST /_plugins/_security/api/version/rollback ### Example response -Assuming there are 5 versions and v4 is the preceding version +OpenSearch sends the following response when rolling back to the `v4` version from the `v5` version: ```json { @@ -188,8 +179,8 @@ The following table lists all response body fields for rollback operations. | Field | Data type | Description | | :--- | :--- | :--- | -| status | String | Rollback status | -| message | String | Description of rollback operation | +| `status` | String | The rollback status. | +| message | String | The rollback operation description. | ## Roll back to a specific version @@ -219,21 +210,16 @@ POST /_plugins/_security/api/version/rollback/v2 ### Response body fields -The following table lists all response body fields for rollback operations. - -| Field | Data type | Description | -|:--------|:----------|:----------------------------------| -| status | String | Rollback status | -| message | String | Description of rollback operation | +See [Roll back to a specific version response body fields](#response-body-fields-2). ## Required permissions Ensure that you have the appropriate permissions for the operations you want to perform. -| Operation | Required Permission | +| Operation | Required permission | | :--- | :--- | | View versions | `restapi:admin/view_version` | -| Rollback configuration | `restapi:admin/rollback_version` | +| Roll back configuration | `restapi:admin/rollback_version` | These permissions are included in the default `security_manager` and `all_access` roles. -These API follow same [access control]({{site.url}}{{site.baseurl}}/access-control/api/#access-control-for-the-api) like any other security API. +These API follow same [access control]({{site.url}}{{site.baseurl}}/access-control/api/#access-control-for-the-api) as all other Security APIs. From a21532f636bcf25a45d058b608d5d9d2d9f8d0ad Mon Sep 17 00:00:00 2001 From: Nathan Bower Date: Thu, 9 Oct 2025 13:41:32 -0400 Subject: [PATCH 5/7] Apply suggestions from code review Signed-off-by: Nathan Bower --- _security/configuration/versioning.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/_security/configuration/versioning.md b/_security/configuration/versioning.md index 12b69ad3872..d207edc34d4 100644 --- a/_security/configuration/versioning.md +++ b/_security/configuration/versioning.md @@ -38,7 +38,7 @@ Optionally, you can control the number of retained versions by specifying the fo plugins.security.config_version.retention_count: 10 ``` -The default retention count is `10` versions. When the retention limit is reached, the oldest version is automatically removed to make space for new one version +The default retention count is `10` versions. When the retention limit is reached, the oldest version is automatically removed to make space for one new version. After modifying `opensearch.yml`, restart your OpenSearch cluster for the changes to take effect. For more information, see [Experimental feature flags]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/experimental/). @@ -145,7 +145,7 @@ GET /_plugins/_security/api/versions See [View a specific version response body fields](#response-body-fields). -## Roll back to previous version +## Roll back to the preceding version Use this endpoint to restore the security configuration to the immediately preceding version. @@ -222,4 +222,4 @@ Ensure that you have the appropriate permissions for the operations you want to | Roll back configuration | `restapi:admin/rollback_version` | These permissions are included in the default `security_manager` and `all_access` roles. -These API follow same [access control]({{site.url}}{{site.baseurl}}/access-control/api/#access-control-for-the-api) as all other Security APIs. +These APIs use the same [access control]({{site.url}}{{site.baseurl}}/access-control/api/#access-control-for-the-api) as all other Security APIs. From ac25dd4f78ac1afdd91d08d79600dfab75f82f82 Mon Sep 17 00:00:00 2001 From: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Date: Thu, 9 Oct 2025 13:52:05 -0400 Subject: [PATCH 6/7] Apply suggestions from code review Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> --- _security/configuration/versioning.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/configuration/versioning.md b/_security/configuration/versioning.md index d207edc34d4..9deff4a2847 100644 --- a/_security/configuration/versioning.md +++ b/_security/configuration/versioning.md @@ -222,4 +222,4 @@ Ensure that you have the appropriate permissions for the operations you want to | Roll back configuration | `restapi:admin/rollback_version` | These permissions are included in the default `security_manager` and `all_access` roles. -These APIs use the same [access control]({{site.url}}{{site.baseurl}}/access-control/api/#access-control-for-the-api) as all other Security APIs. +These APIs use the same [access control]({{site.url}}{{site.baseurl}}/security/access-control/api/#access-control-for-the-api) as all other Security APIs. From 234d8c4ea1b066be2a74b6aa8dcfe5ae7014248b Mon Sep 17 00:00:00 2001 From: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Date: Fri, 10 Oct 2025 09:35:40 -0400 Subject: [PATCH 7/7] Update _security/configuration/versioning.md Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> --- _security/configuration/versioning.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/configuration/versioning.md b/_security/configuration/versioning.md index 9deff4a2847..265615274ba 100644 --- a/_security/configuration/versioning.md +++ b/_security/configuration/versioning.md @@ -57,7 +57,7 @@ The following table lists the available path parameters. All path parameters are | Parameter | Data type | Description | | :--- | :--- | :--- | -| `version_id` | String | The version identifier to view or roll back to (for example, `v1`, `v2`). Required for specific version operations. | +| `version_id` | String | The version identifier to view or roll back to. Must start with `v` followed by a number (for example, `v1` or `v2`). Required for specific version operations. | ## View a specific version