Make migrate api require default access level to be supplied and updates documentations + tests

Signed-off-by: Darshit Chanpura <[email protected]>

Author: DarshitChanpura

RESOURCE_SHARING_AND_ACCESS_CONTROL.md

@@ -75,6 +75,7 @@ opensearchplugin {
 ```
 - **Implement** the `ResourceSharingExtension` interface. For guidance, refer [SPI README.md](./spi/README.md#4-implement-the-resourcesharingextension-interface).
 - **Implement** the `ResourceSharingClientAccessor` wrapper class to access ResourceSharingClient. Refer [SPI README.md](./spi/README.md#5-implement-the-resourcesharingclientaccessor-class).
+- If plugin implements search, add a **plugin client** if not already present. Can be copied from sample-plugin's [PluginClient.java](./sample-resource-plugin/src/main/java/org/opensearch/sample/utils/PluginClient.java).
 - **Ensure** that each resource index only contains 1 type of resource.
 - **Register itself** in `META-INF/services` by creating the following file:
   ```
@@ -129,10 +130,28 @@ resource_types:
         - "cluster:admin/sample-resource-plugin/*"
         - "cluster:admin/security/resource/share"
 ```
+- If your plugin enabled testing with security, add the following to you node-setup for `integTest` task:
+```build.gradle
+integTest {
+    ...
+    systemProperty "resource_sharing.enabled", System.getProperty("resource_sharing.enabled")
+    ...
+}
+...
+<test-cluster-setup-task> {
+    ...
+    node.setting("plugins.security.system_indices.enabled", "true")
+    if (System.getProperty("resource_sharing.enabled") == "true") {
+        node.setting("plugins.security.experimental.resource_sharing.enabled", "true")
+        node.setting("plugins.security.experimental.resource_sharing.protected_types", "[\"anomaly-detector\", \"forecaster\"]")
+    }
+    ...
+}
+```
 
 ## **3. Resource Sharing API Design**
 
-### **Resource Sharing Index **
+### **Resource Sharing Index**
 
 Each plugin receives its own sharing index, centrally managed by security plugin, which stores **resource access metadata**, mapping **resources to their access control policies**.
 
@@ -323,44 +342,21 @@ void revoke(String resourceId, String resourceIndex, ShareWith target, ActionLis
 void getAccessibleResourceIds(String resourceIndex, ActionListener<Set<String>> listener);
 ```
 
-Example usage:
-```java
-@Inject
-public ShareResourceTransportAction(
-        TransportService transportService,
-        ActionFilters actionFilters,
-        SampleResourceExtension sampleResourceExtension
-) {
-    super(ShareResourceAction.NAME, transportService, actionFilters, ShareResourceRequest::new);
-    this.resourceSharingClient = sampleResourceExtension == null ? null : sampleResourceExtension.getResourceSharingClient();
-}
+### **5. `isFeatureEnabledForType`**
 
-@Override
-protected void doExecute(Task task, ShareResourceRequest request, ActionListener<ShareResourceResponse> listener) {
-    if (request.getResourceId() == null || request.getResourceId().isEmpty()) {
-        listener.onFailure(new IllegalArgumentException("Resource ID cannot be null or empty"));
-        return;
-    }
+**Add as code-control to execute resource-sharing code only if the feature is enabled for the given type.**
 
-    if (resourceSharingClient == null) {
-        listener.onFailure(
-                new OpenSearchStatusException(
-                        "Resource sharing is not enabled. Cannot share resource " + request.getResourceId(),
-                        RestStatus.NOT_IMPLEMENTED
-                )
-        );
-        return;
-    }
-    ShareWith shareWith = request.getShareWith();
-    resourceSharingClient.share(request.getResourceId(), RESOURCE_INDEX_NAME, shareWith, ActionListener.wrap(sharing -> {
-        ShareWith finalShareWith = sharing == null ? null : sharing.getShareWith();
-        ShareResourceResponse response = new ShareResourceResponse(finalShareWith);
-        log.debug("Shared resource: {}", response.toString());
-        listener.onResponse(response);
-    }, listener::onFailure));
-}
+```
+boolean isFeatureEnabledForType(String resourceType);
 ```
 
+Example usage `isFeatureEnabledForType()`:
+```java
+public static boolean shouldUseResourceAuthz(String resourceType) {
+    var client = ResourceSharingClientAccessor.getInstance().getResourceSharingClient();
+    return client != null && client.isFeatureEnabledForType(resourceType);
+}
+```
 
 > For more details, refer [spi/README.md](./spi/README.md#available-java-apis)
 
@@ -396,15 +392,18 @@ sequenceDiagram
       Plugin ->> SPI: getAccessibleResourceIds (noop)
       SPI -->> Plugin: Error 501 Not Implemented
 
+      Plugin ->> SPI: isFeatureEnabledForType (noop)
+      SPI -->> Plugin: Disabled
+
     else Security Plugin Enabled
     %% Step 3: Plugin calls Java APIs declared by ResourceSharingClient
-      Plugin ->> SPI: Calls Java API (`verifyAccess`, `share`, `revoke`, `getAccessibleResourceIds`)
+      Plugin ->> SPI: Calls Java API (`verifyAccess`, `share`, `revoke`, `getAccessibleResourceIds`, `isFeatureEnabledForType`)
 
     %% Step 4: Request is sent to Security Plugin
       SPI ->> Security: Sends request to Security Plugin for processing
 
     %% Step 5: Security Plugin handles request and returns response
-      Security -->> SPI: Response (Access Granted or Denied / Resource Shared or Revoked / List Resource IDs )
+      Security -->> SPI: Response (Access Granted or Denied / Resource Shared or Revoked / List Resource IDs / Feature Enabled or Disabled for Resource Type)
 
     %% Step 6: Security SPI sends response back to Plugin
       SPI -->> Plugin: Passes processed response back to Plugin
@@ -628,19 +627,19 @@ Read documents from a plugin’s index and migrate ownership and backend role-ba
 
 **Request Body**
 
-| Parameter              | Type    | Required | Description                                                                 |
-|------------------------|---------|----|-----------------------------------------------------------------------------|
-| `source_index`         | string  | yes | Name of the plugin index containing the existing resource documents        |
-| `username_path`        | string  | yes | JSON Pointer to the username field inside each document (e.g., `/owner`)   |
-| `backend_roles_path`   | string  | yes | JSON Pointer to the backend_roles field (must point to a JSON array)       |
-| `default_access_level` | string  | no | Default access level to assign migrated backend_roles (default: `"default"`) |
+| Parameter              | Type    | Required | Description                                                             |
+|------------------------|---------|----------|-------------------------------------------------------------------------|
+| `source_index`         | string  | yes      | Name of the plugin index containing the existing resource documents     |
+| `username_path`        | string  | yes      | JSON Pointer to the username field inside each document                 |
+| `backend_roles_path`   | string  | yes      | JSON Pointer to the backend_roles field (must point to a JSON array)    |
+| `default_access_level` | string  | yes      | Default access level to assign migrated backend_roles                   |
 
 **Example Request**
 `POST /_plugins/_security/api/resources/migrate`
 **Request Body:**
 ```json
 {
-  "source_index": "sample_plugin_index",
+  "source_index": ".sample_resource",
   "username_path": "/owner",
   "backend_roles_path": "/access/backend_roles",
   "default_access_level": "read_only"

sample-resource-plugin/src/integrationTest/java/org/opensearch/sample/resource/TestUtils.java

@@ -148,46 +148,60 @@ public static String migrationPayload_valid() {
             "source_index": "%s",
             "username_path": "%s",
             "backend_roles_path": "%s"
+            "default_access_level": "%s"
             }
-            """.formatted(RESOURCE_INDEX_NAME, "user/name", "user/backend_roles");
+            """.formatted(RESOURCE_INDEX_NAME, "user/name", "user/backend_roles", "sample_read_only");
     }
 
-    public static String migrationPayload_valid_withSpecifiedAccessLevel() {
+    public static String migrationPayload_valid_withSpecifiedAccessLevel(String accessLevel) {
         return """
             {
             "source_index": "%s",
             "username_path": "%s",
             "backend_roles_path": "%s",
             "default_access_level": "%s"
             }
-            """.formatted(RESOURCE_INDEX_NAME, "user/name", "user/backend_roles", "read_only");
+            """.formatted(RESOURCE_INDEX_NAME, "user/name", "user/backend_roles", accessLevel);
     }
 
     public static String migrationPayload_missingSourceIndex() {
         return """
             {
             "username_path": "%s",
-            "backend_roles_path": "%s"
+            "backend_roles_path": "%s",
+            "default_access_level": "%s"
             }
-            """.formatted("user/name", "user/backend_roles");
+            """.formatted("user/name", "user/backend_roles", "sample_read_only");
     }
 
     public static String migrationPayload_missingUserName() {
         return """
             {
             "source_index": "%s",
-            "backend_roles_path": "%s"
+            "backend_roles_path": "%s",
+            "default_access_level": "%s"
             }
-            """.formatted(RESOURCE_INDEX_NAME, "user/backend_roles");
+            """.formatted(RESOURCE_INDEX_NAME, "user/backend_roles", "sample_read_only");
     }
 
     public static String migrationPayload_missingBackendRoles() {
         return """
             {
             "source_index": "%s",
-            "username_path": "%s"
+            "username_path": "%s",
+            "default_access_level": "%s"
             }
-            """.formatted(RESOURCE_INDEX_NAME, "user/name");
+            """.formatted(RESOURCE_INDEX_NAME, "user/name", "sample_read_only");
+    }
+
+    public static String migrationPayload_missingDefaultAccessLevel() {
+        return """
+            {
+            "source_index": "%s",
+            "username_path": "%s",
+            "backend_roles_path": "%s"
+            }
+            """.formatted(RESOURCE_INDEX_NAME, "user/name", "user/backend_roles");
     }
 
     public static String putSharingInfoPayload(

sample-resource-plugin/src/integrationTest/java/org/opensearch/sample/resource/securityapis/MigrateApiTests.java

@@ -41,6 +41,7 @@
 import static org.opensearch.sample.resource.TestUtils.SAMPLE_RESOURCE_CREATE_ENDPOINT;
 import static org.opensearch.sample.resource.TestUtils.SAMPLE_RESOURCE_GET_ENDPOINT;
 import static org.opensearch.sample.resource.TestUtils.migrationPayload_missingBackendRoles;
+import static org.opensearch.sample.resource.TestUtils.migrationPayload_missingDefaultAccessLevel;
 import static org.opensearch.sample.resource.TestUtils.migrationPayload_missingSourceIndex;
 import static org.opensearch.sample.resource.TestUtils.migrationPayload_missingUserName;
 import static org.opensearch.sample.resource.TestUtils.migrationPayload_valid;
@@ -125,9 +126,9 @@ public void testMigrateAPIWithRestAdmin_valid() {
             TestRestClient.HttpResponse sharingResponse = client.get(RESOURCE_SHARING_INDEX + "/_search");
             sharingResponse.assertStatusCode(HttpStatus.SC_OK);
             assertThat(sharingResponse.bodyAsJsonNode().get("hits").get("hits").size(), equalTo(1)); // 1 of 2 entries was skipped
-            assertThat(sharingResponse.bodyAsJsonNode().get("hits").get("hits"), equalTo(expectedHits(resourceId, "default"))); // with
-                                                                                                                                // default
-                                                                                                                                // access-level
+            assertThat(sharingResponse.bodyAsJsonNode().get("hits").get("hits"), equalTo(expectedHits(resourceId, "sample_read_only"))); // with
+            // default
+            // access-level
         }
     }
 
@@ -140,7 +141,7 @@ public void testMigrateAPIWithRestAdmin_valid_withSpecifiedAccessLevel() {
         try (TestRestClient client = cluster.getRestClient(cluster.getAdminCertificate())) {
             TestRestClient.HttpResponse migrateResponse = client.postJson(
                 RESOURCE_SHARING_MIGRATION_ENDPOINT,
-                migrationPayload_valid_withSpecifiedAccessLevel()
+                migrationPayload_valid_withSpecifiedAccessLevel("sample_read_write")
             );
             migrateResponse.assertStatusCode(HttpStatus.SC_OK);
             assertThat(migrateResponse.bodyAsMap().get("summary"), equalTo("Migration complete. migrated 1; skippedNoUser 1; failed 0"));
@@ -149,9 +150,9 @@ public void testMigrateAPIWithRestAdmin_valid_withSpecifiedAccessLevel() {
             TestRestClient.HttpResponse sharingResponse = client.get(RESOURCE_SHARING_INDEX + "/_search");
             sharingResponse.assertStatusCode(HttpStatus.SC_OK);
             assertThat(sharingResponse.bodyAsJsonNode().get("hits").get("hits").size(), equalTo(1)); // 1 of 2 entries was skipped
-            assertThat(sharingResponse.bodyAsJsonNode().get("hits").get("hits"), equalTo(expectedHits(resourceId, "read_only"))); // with
-                                                                                                                                  // custom
-                                                                                                                                  // access-level
+            assertThat(sharingResponse.bodyAsJsonNode().get("hits").get("hits"), equalTo(expectedHits(resourceId, "sample_read_write"))); // with
+            // custom
+            // access-level
         }
     }
 
@@ -194,6 +195,19 @@ public void testMigrateAPIWithRestAdmin_noSourceIndex() {
         }
     }
 
+    @Test
+    public void testMigrateAPIWithRestAdmin_noDefaultAccessLevel() {
+        createSampleResource();
+
+        try (TestRestClient client = cluster.getRestClient(cluster.getAdminCertificate())) {
+            TestRestClient.HttpResponse migrateResponse = client.postJson(
+                RESOURCE_SHARING_MIGRATION_ENDPOINT,
+                migrationPayload_missingDefaultAccessLevel()
+            );
+            assertThat(migrateResponse, RestMatchers.isBadRequest("/missing_mandatory_keys/keys", "default_access_level"));
+        }
+    }
+
     private String createSampleResource() {
         try (TestRestClient client = cluster.getRestClient(MIGRATION_USER)) {
             String sampleResource = """

spi/README.md

@@ -349,6 +349,25 @@ resourceSharingClient.getAccessibleResourceIds(RESOURCE_INDEX_NAME, ActionListen
 ```
 > **Use Case:** Helps a user identify **which shareableResources they can interact with**.
 
+---
+
+#### **5. `isFeatureEnabledForType`**
+**Add as code-control to execute resource-sharing code only if the feature is enabled for the given type.**
+
+##### **Method Signature:**
+```java
+void isFeatureEnabledForType(String resourceIndex, ActionListener<Set<String>> listener);
+```
+
+##### **Example Usage:**
+```java
+public static boolean shouldUseResourceAuthz(String resourceType) {
+    var client = ResourceSharingClientAccessor.getInstance().getResourceSharingClient();
+    return client != null && client.isFeatureEnabledForType(resourceType);
+}
+```
+> **Use Case:** Helps control code-path for cases where global feature flag is enabled but given resource-type is (not) marked as protected**.
+
 ##### **Sample Request Flow:**
 
 ```mermaid

src/main/java/org/opensearch/security/resources/migrate/MigrateResourceSharingInfoApiAction.java

@@ -76,7 +76,7 @@
  *          source_index: "abc",                                    // name of plugin index
  *          username_path: "/path/to/username/node",               // path to user-name in resource document in the plugin index
  *          backend_roles_path: "/path/to/user_backend-roles/node"  // path to backend-roles in resource document in the plugin index
- *          default_access_level: "<some-default-access-level>"     // default value that should replace the otherwise ResourceAccessLevels.PLACE_HOLDER assigned to the new ResourceSharing object
+ *          default_access_level: "<some-default-access-level>"     // default access-level at which sharing records should be created
  *      }
  *   - Response:
  *      200 OK Migration Complete. Migrate X, skippedNoUser Y, failed Z // migrate -> successful migration count, skippedNoUser -> records with no creator info, failed -> records that failed to migrate
@@ -140,7 +140,7 @@ private ValidationResult<Triple<String, String, List<SourceDoc>>> loadCurrentSha
         String sourceIndex = body.get("source_index").asText();
         String userNamePath = body.get("username_path").asText();
         String backendRolesPath = body.get("backend_roles_path").asText();
-        String defaultAccessLevel = body.has("default_access_level") ? body.get("default_access_level").asText() : "default";
+        String defaultAccessLevel = body.get("default_access_level").asText();
 
         List<SourceDoc> results = new ArrayList<>();
 
@@ -307,7 +307,7 @@ public Settings settings() {
 
                     @Override
                     public Set<String> mandatoryKeys() {
-                        return ImmutableSet.of("source_index", "username_path", "backend_roles_path");
+                        return ImmutableSet.of("source_index", "username_path", "backend_roles_path", "default_access_level");
                     }
 
                     @Override