Updates documentation

Signed-off-by: Darshit Chanpura <dchanp@amazon.com>

Author: DarshitChanpura

RESOURCE_ACCESS_CONTROL_FOR_PLUGINS.md

@@ -16,9 +16,9 @@ This feature ensures **secure** and **controlled** access to shareableResources
 This feature introduces **one primary component** for plugin developers:
 
 ### **1. `opensearch-security-spi`**
-- A **Service Provider Interface (SPI)** that plugins must implement to declare themselves as **Resource Plugins**.
+- A **Service Provider Interface (SPI)** that provides `ResourceSharingExtension` interface that plugins must implement to declare themselves as **Resource Plugins**.
 - The security plugin keeps track of these plugins (similar to how JobScheduler tracks `JobSchedulerExtension`).
-- Allows resource plugins to utilize a **service provider client** to implement access control.
+- Provides resource plugins with a **client** to implement access control.
 
 ### **Plugin Implementation Requirements:**
 
@@ -42,16 +42,14 @@ opensearchplugin {
 }
 ```
 - **Implement** the `ResourceSharingExtension` class.
-- **Ensure** that its declared resources implement the `Resource` interface.
 - **Ensure** that each resource index only contains 1 type of resource.
-- **Provide a resource parser**, which the security plugin uses to extract resource details from the resource index.
 - **Register itself** in `META-INF/services` by creating the following file:
   ```
   src/main/resources/META-INF/services/org.opensearch.security.spi.ResourceSharingExtension
   ```
     - This file must contain a **single line** specifying the **fully qualified class name** of the plugin’s `ResourceSharingExtension` implementation, e.g.:
       ```
-      org.opensearch.sample.SampleResourcePlugin
+      org.opensearch.sample.SampleResourceSharingExtension
       ```
 
 ---
@@ -180,45 +178,10 @@ Each **action-group** entry contains the following access definitions:
 ### **Declaring a Plugin as a Resource Plugin**
 To integrate with the security plugin, your plugin must:
 1. Extend `ResourceSharingExtension` and implement required methods.
-2. Implement the `ShareableResource` interface for resource declaration.
-3. Implement a resource parser to extract resource details.
-4. Implement a client accessor to utilize `ResourceSharingClient`.
+2. Implement a client accessor to utilize `ResourceSharingClient`.
 
 [`opensearch-security-spi` README.md](./spi/README.md) is a great resource to learn more about the components of SPI and how to set up.
 
-Tip: Refer to the `org.opensearch.sample.SampleResourcePlugin` class to understand the setup in further detail.
-
-Example usage:
-```java
-public class SampleResourcePlugin extends Plugin implements SystemIndexPlugin, ResourceSharingExtension {
-
-    // Override required methods
-
-    @Override
-    public Collection<SystemIndexDescriptor> getSystemIndexDescriptors(Settings settings) {
-        final SystemIndexDescriptor systemIndexDescriptor = new SystemIndexDescriptor(RESOURCE_INDEX_NAME, "Sample index with resources");
-        return Collections.singletonList(systemIndexDescriptor);
-    }
-
-    @Override
-    public Set<ResourceProvider> getResourceProviders() {
-        return Set.of(
-                new ResourceProvider(
-                        SampleResource.class.getCanonicalName(), // class-name of the resource
-                        RESOURCE_INDEX_NAME,                     // the index that stores resource, **must only store the type of resource defined in the line above**
-                        new SampleResourceParser()               // parser to parse the resource
-                )
-        );
-    }
-
-    @Override
-    public void assignResourceSharingClient(ResourceSharingClient resourceSharingClient) {
-        ResourceSharingClientAccessor.setResourceSharingClient(resourceSharingClient);
-    }
-}
-```
-
-
 ### **Calling Access Control Methods from the ResourceSharingClient Client**
 The client provides **four access control methods** for plugins. For detailed usage and implementation, refer to the [`opensearch-security-spi` README.md](./spi/README.md#available-java-apis)
 
@@ -230,20 +193,20 @@ The client provides **four access control methods** for plugins. For detailed us
 void verifyResourceAccess(String resourceId, String resourceIndex, ActionListener<Boolean> listener);
 ```
 
-### **2. `shareResource`**
+### **2. `share`**
 
 **Grants access to a resource for specified users, roles, and backend roles.**
 
 ```
-void shareResource(String resourceId, String resourceIndex, SharedWithActionGroup.ActionGroupRecipients recipients, ActionListener<ResourceSharing> listener);
+void share(String resourceId, String resourceIndex, SharedWithActionGroup.ActionGroupRecipients recipients, ActionListener<ResourceSharing> listener);
 ```
 
-### **3. `revokeResourceAccess`**
+### **3. `revoke`**
 
 **Removes access permissions for specified users, roles, and backend roles.**
 
 ```
-void revokeResourceAccess(String resourceId, String resourceIndex, SharedWithActionGroup.ActionGroupRecipients entitiesToRevoke, ActionListener<ResourceSharing> listener);
+void revoke(String resourceId, String resourceIndex, SharedWithActionGroup.ActionGroupRecipients entitiesToRevoke, ActionListener<ResourceSharing> listener);
 ```
 
 ### **4. `getAccessibleResourceIds`**
@@ -271,7 +234,7 @@ protected void doExecute(Task task, ShareResourceRequest request, ActionListener
     }
 
     ResourceSharingClient resourceSharingClient = ResourceSharingClientAccessor.getResourceSharingClient();
-    resourceSharingClient.shareResource(
+    resourceSharingClient.share(
             request.getResourceId(),
             RESOURCE_INDEX_NAME,
             request.getShareWith(),
@@ -307,23 +270,23 @@ sequenceDiagram
       SPI -->> Plugin: Response: Access Granted
 
     %% For share, revoke, and list: return 501 Not Implemented
-      Plugin ->> SPI: shareResource (noop)
+      Plugin ->> SPI: share (noop)
       SPI -->> Plugin: Error 501 Not Implemented
 
-      Plugin ->> SPI: revokeResourceAccess (noop)
+      Plugin ->> SPI: revoke (noop)
       SPI -->> Plugin: Error 501 Not Implemented
 
-      Plugin ->> SPI: listAccessibleResources (noop)
+      Plugin ->> SPI: getAccessibleResourceIds (noop)
       SPI -->> Plugin: Error 501 Not Implemented
     else Security Plugin Enabled
     %% Step 3: Plugin calls Java APIs declared by ResourceSharingClient
-      Plugin ->> SPI: Calls Java API (`verifyResourceAccess`, `shareResource`, `revokeResourceAccess`, `listAccessibleResources`)
+      Plugin ->> SPI: Calls Java API (`verifyResourceAccess`, `share`, `revoke`, `getAccessibleResourceIds`)
 
     %% 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 Resources )
+      Security -->> SPI: Response (Access Granted or Denied / Resource Shared or Revoked / List Resource IDs )
 
     %% Step 6: Security SPI sends response back to Plugin
       SPI -->> Plugin: Passes processed response back to Plugin
@@ -465,7 +428,6 @@ sample_read_access:
 ### **For Plugin Developers**
 - **Declare resources properly** in the `ResourceSharingExtension`.
 - **Use the resource sharing client** instead of direct index queries to check access.
-- **Implement a resource parser** to ensure correct resource extraction.
 
 ### **For Users & Admins**
 - **Keep system index protection enabled** for better security.

spi/README.md

@@ -5,49 +5,19 @@ This **Service Provider Interface (SPI)** provides the necessary **interfaces an
 
 ### **Resource Sharing and Access Control Extension**
 
-This **Service Provider Interface (SPI)** provides an extension point to implement **Resource Sharing and Access Control** in OpenSearch.
+This extension point provides extending plugins with interfaces necessary to implement **Resource Sharing and Access Control** in OpenSearch.
 
 ---
 
 ### **Usage**
 
 A plugin that **defines a resource** and aims to implement **access control** over that resource must **extend** the `ResourceSharingExtension` class to register itself as a **Resource Plugin**.
 
-#### **Example: Implementing a Resource Plugin**
-```java
-public class SampleResourcePlugin extends Plugin implements SystemIndexPlugin, ResourceSharingExtension {
-
-    // Override required methods
-
-    @Override
-    public Collection<SystemIndexDescriptor> getSystemIndexDescriptors(Settings settings) {
-      final SystemIndexDescriptor systemIndexDescriptor = new SystemIndexDescriptor(RESOURCE_INDEX_NAME, "Sample index with resources");
-      return Collections.singletonList(systemIndexDescriptor);
-    }
-
-    @Override
-    public Set<ResourceProvider> getResourceProviders() {
-      return Set.of(
-              new ResourceProvider(
-                      SampleResource.class.getCanonicalName(), // class-name of the resource
-                      RESOURCE_INDEX_NAME,                     // the index that stores resource, **must only store the type of resource defined in the line above**
-                      new SampleResourceParser()               // parser to parse the resource
-              )
-      );
-    }
-
-    @Override
-    public void assignResourceSharingClient(ResourceSharingClient resourceSharingClient) {
-      ResourceSharingClientAccessor.setResourceSharingClient(resourceSharingClient);
-    }
-}
-```
-
 ---
 
-### **Checklist for Implementing a Resource Plugin**
+### **Checklist for plugins aiming to implement Resource Access Control**
 
-To properly integrate with the **Resource Sharing and Access Control SPI**, follow these steps:
+To properly integrate with the **Resource Sharing and Access Control Extension**, follow these steps:
 
 #### **1. Add Required Dependencies**
 Include **`opensearch-security-spi`** in your **`build.gradle`** file.
@@ -57,62 +27,80 @@ dependencies {
     compileOnly group: 'org.opensearch', name:'opensearch-security-spi', version:"${opensearch_build_version}"
 }
 ```
-
 ---
 
-#### **2. Register the Plugin Using the Java SPI Mechanism**
-- Navigate to your plugin's `src/main/resources` folder.
-- Locate or create the `META-INF/services` directory.
-- Inside `META-INF/services`, create a file named:
-  ```
-  org.opensearch.security.spi.resources.ResourceSharingExtension
-  ```
-- Edit the file and add a **single line** containing the **fully qualified class name** of your plugin implementation.
-  Example:
-  ```
-  org.opensearch.sample.SampleResourcePlugin
-  ```
-  > This step ensures that OpenSearch **dynamically loads your plugin** as a resource-sharing extension.
-
----
-
-#### **3. Declare a Resource Class**
-Each plugin must define a **resource class** that implements the `Resource` interface.
+#### **2. Declare a Resource Class**
+Each plugin must define a **resource class** .
 Example:
 ```java
-public class SampleResource implements ShareableResource {
+public class SampleResource {
     private String id;
     private String owner;
 
     // Constructor, getters, setters, etc.
-
-    @Override
-    public String getName() {
-      return name;
-    }
 }
 ```
 
 ---
 
-#### **4. Implement a Resource Parser**
-A **`ResourceParser`** is required to convert **resource data** from OpenSearch indices.
+#### **3. Declare Resource Index as System index**
+**Important:** Mark the resource **index as a system index** to enforce security protections.
+
 Example:
 ```java
-public class SampleResourceParser implements ShareableResourceParser<SampleResource> {
+public class SampleResourcePlugin extends Plugin implements SystemIndexPlugin {
+
+    // Override required methods
+
     @Override
-    public SampleResource parseXContent(XContentParser parser) throws IOException {
-      return SampleResource.fromXContent(parser);
+    public Collection<SystemIndexDescriptor> getSystemIndexDescriptors(Settings settings) {
+        final SystemIndexDescriptor systemIndexDescriptor = new SystemIndexDescriptor(RESOURCE_INDEX_NAME, "Sample index with resources");
+        return Collections.singletonList(systemIndexDescriptor);
     }
 }
 ```
 
 ---
 
-#### **5. Implement the `ResourceSharingExtension` Interface**
+#### **4. Implement the `ResourceSharingExtension` Interface**
 Ensure that your **plugin declaration class** implements `ResourceSharingExtension` and provides **all required methods**.
 
-**Important:** Mark the resource **index as a system index** to enforce security protections.
+```java
+// Create a new extension point to register itself of a resource access control plugin
+public class SampleResourceSharingExtension implements ResourceSharingExtension {
+
+    @Override
+    public Set<ResourceProvider> getResourceProviders() {
+      return Set.of(
+              new ResourceProvider(
+                      SampleResource.class.getCanonicalName(), // class-name of the resource
+                      RESOURCE_INDEX_NAME                     // the index that stores resource, **must only store the type of resource defined in the line above**
+              )
+      );
+    }
+
+    @Override
+    public void assignResourceSharingClient(ResourceSharingClient resourceSharingClient) {
+      ResourceSharingClientAccessor.setResourceSharingClient(resourceSharingClient);
+    }
+}
+```
+
+---
+
+#### **5. Register the Plugin Using the Java SPI Mechanism**
+- Navigate to your plugin's `src/main/resources` folder.
+- Locate or create the `META-INF/services` directory.
+- Inside `META-INF/services`, create a file named:
+  ```
+  org.opensearch.security.spi.resources.ResourceSharingExtension
+  ```
+- Edit the file and add a **single line** containing the **fully qualified class name** of your resource sharing extension implementation class.
+  Example:
+  ```
+  org.opensearch.sample.SampleResourceSharingExtension
+  ```
+  > This step ensures that OpenSearch **dynamically loads your plugin** as a resource-sharing extension.
 
 ---
 
@@ -168,31 +156,31 @@ protected void doExecute(Task task, DeleteResourceRequest request, ActionListene
   // Check permission to resource
   ResourceSharingClient resourceSharingClient = ResourceSharingClientAccessor.getResourceSharingClient();
   resourceSharingClient.verifyResourceAccess(resourceId, RESOURCE_INDEX_NAME, ActionListener.wrap(isAuthorized -> {
-    if (!isAuthorized) {
-      listener.onFailure(
-              new OpenSearchStatusException("Current user is not authorized to delete resource: " + resourceId, RestStatus.FORBIDDEN)
-      );
-      return;
-    }
-
-    // Authorization successful, proceed with deletion
-    ThreadContext threadContext = transportService.getThreadPool().getThreadContext();
-    try (ThreadContext.StoredContext ignored = threadContext.stashContext()) {
-      deleteResource(resourceId, ActionListener.wrap(deleteResponse -> {
-        if (deleteResponse.getResult() == DocWriteResponse.Result.NOT_FOUND) {
-          listener.onFailure(new ResourceNotFoundException("Resource " + resourceId + " not found."));
-        } else {
-          listener.onResponse(new DeleteResourceResponse("Resource " + resourceId + " deleted successfully."));
-        }
-      }, exception -> {
-        log.error("Failed to delete resource: " + resourceId, exception);
-        listener.onFailure(exception);
-      }));
-    }
-  }, exception -> {
-    log.error("Failed to verify resource access: " + resourceId, exception);
-    listener.onFailure(exception);
-  }));
+      if (!isAuthorized) {
+        listener.onFailure(
+                new OpenSearchStatusException("Current user is not authorized to delete resource: " + resourceId, RestStatus.FORBIDDEN)
+        );
+        return;
+      }
+
+      // Authorization successful, proceed with deletion
+      ThreadContext threadContext = transportService.getThreadPool().getThreadContext();
+      try (ThreadContext.StoredContext ignored = threadContext.stashContext()) {
+        deleteResource(resourceId, ActionListener.wrap(deleteResponse -> {
+          if (deleteResponse.getResult() == DocWriteResponse.Result.NOT_FOUND) {
+            listener.onFailure(new ResourceNotFoundException("Resource " + resourceId + " not found."));
+          } else {
+            listener.onResponse(new DeleteResourceResponse("Resource " + resourceId + " deleted successfully."));
+          }
+        }, exception -> {
+          log.error("Failed to delete resource: " + resourceId, exception);
+          listener.onFailure(exception);
+        }));
+      }
+    }, exception -> {
+      log.error("Failed to verify resource access: " + resourceId, exception);
+      listener.onFailure(exception);
+    }));
 }
 
 private void deleteResource(String resourceId, ActionListener<DeleteResponse> listener) {