audit logging tests, named routes

.github/actions/create-bwc-build/action.yaml

@@ -35,7 +35,7 @@ runs:
     - name: Build
       uses: gradle/gradle-build-action@v2
       with:
-        arguments: assemble -Dbuild.snapshot=false
+        arguments: assemble
         build-root-directory: ${{ inputs.plugin-branch }}
 
     - id: get-opensearch-version
@@ -46,5 +46,5 @@ runs:
     - name: Copy current distro into the expected folder
       run: |
         mkdir -p ./bwc-test/src/test/resources/${{ steps.get-opensearch-version.outputs.version }}
-        cp ${{ inputs.plugin-branch }}/build/distributions/opensearch-security-${{ steps.get-opensearch-version.outputs.version }}.zip ./bwc-test/src/test/resources/${{ steps.get-opensearch-version.outputs.version }}
+        cp ${{ inputs.plugin-branch }}/build/distributions/opensearch-security-${{ steps.get-opensearch-version.outputs.version }}-SNAPSHOT.zip ./bwc-test/src/test/resources/${{ steps.get-opensearch-version.outputs.version }}
       shell: bash

.github/dependabot.yml

@@ -0,0 +1,8 @@
+version: 2
+updates:
+  - package-ecosystem: "gradle"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "dependabot:"

.github/workflows/backport.yml

@@ -22,7 +22,9 @@ jobs:
           installation_id: 22958780
 
       - name: Backport
-        uses: VachaShah/backport@v1.1.4
+        uses: VachaShah/backport@v2.2.0
         with:
           github_token: ${{ steps.github_app_token.outputs.token }}
           branch_name: backport/backport-${{ github.event.number }}
+          head_template: backport/backport-<%= number %>-to-<%= base %>
+          failure_labels: backport-failed

DEVELOPER_GUIDE.md

@@ -10,6 +10,7 @@ So you want to contribute code to OpenSearch Security? Excellent! We're glad you
   - [Running integration tests](#running-integration-tests)
     - [Bulk test runs](#bulk-test-runs)
     - [Checkstyle Violations](#checkstyle-violations)
+  - [Authorization in REST Layer](#authorization-in-rest-layer)
   - [Submitting Changes](#submitting-changes)
   - [Backports](#backports)
 
@@ -78,6 +79,51 @@ mv config/* $OPENSEARCH_HOME/config/opensearch-security/
 rm -rf config/
 ```
 
+### Installing demo extension users and roles
+
+If you are working with an extension and want to set up demo users for the Hello-World extension, append following items to files inside `$OPENSEARCH_HOME/config/opensearch-security/`:
+1. In **internal_users.yml**
+```yaml
+hw-user:
+  hash: "$2a$12$VcCDgh2NDk07JGN0rjGbM.Ad41qVR/YFJcgHp0UGns5JDymv..TOG"
+  reserved: true
+  description: "Demo user for ext-test"
+```
+
+2. In **roles.yml**
+```yaml
+extension_hw_greet:
+  reserved: true
+  cluster_permissions:
+    - 'hw:greet'
+
+extension_hw_full:
+  reserved: true
+  cluster_permissions:
+    - 'hw:goodbye'
+    - 'hw:greet'
+    - 'hw:greet_with_adjective'
+    - 'hw:greet_with_name'
+
+legacy_hw_greet_with_name:
+  reserved: true
+  cluster_permissions:
+    - 'cluster:admin/opensearch/hw/greet_with_name'
+```
+
+3. In **roles_mapping.yml**
+```yaml
+legacy_hw_greet_with_name:
+  reserved: true
+  users:
+    - "hw-user"
+
+extension_hw_greet:
+  reserved: true
+  users:
+    - "hw-user"
+```
+
 To install the demo certificates and default configuration, answer `y` to the first two questions and `n` to the last one. The log should look like below:
 
 ```bash
@@ -188,6 +234,11 @@ Checkstyle enforces several rules within this codebase. Sometimes it will be nec
   // CS-ENFORCE-ALL
 ```
 
+## Authorization in REST Layer
+
+See [REST_AUTHZ_FOR_PLUGINS](REST_AUTHZ_FOR_PLUGINS.md).
+
+
 ## Submitting Changes
 
 See [CONTRIBUTING](CONTRIBUTING.md).

REST_AUTHZ_FOR_PLUGINS.md

@@ -0,0 +1,136 @@
+# Authorization at REST Layer for plugins
+
+This feature is introduced as an added layer of security on top of existing TransportLayer authorization framework. In order to leverage these feature some core changes need to be made at Route registration level. This document talks about how you can achieve this.
+
+**NOTE:** This doesn't replace Transport Layer Authorization. Plugin developers may choose to skip creating transport actions for APIs that do not need interaction with the Transport Layer.
+
+## Pre-requisites
+
+The security plugin must be installed and operational in your OpenSearch cluster for this feature to work.
+
+### How does NamedRoute authorization work?
+
+Once the routes are defined as NamedRoute, they, along-with their handlers, will be registered the same way as Route objects. When a request comes in, `SecurityRestFilter.java` applies an authorization check which extracts information about the NamedRoute.
+Next we get the unique name and actionNames associated with that route and evaluate these against existing `cluster_permissions` across all roles of the requesting user. If the authorization check succeeds, the request chain proceeds as normal. If it fails, a 401 response is returned to the user.
+
+NOTE:
+1. The action names defined in roles must exactly match the names of registered routes, or else, the request would be deemed unauthorized.
+2. This check will not be implemented for plugins who do not use NamedRoutes.
+
+
+
+### How to translate an existing Route to be a NamedRoute?
+
+Here is a sample of an existing route converted to a named route:
+Before:
+```
+public List<Route> routes() {
+    return ImmutableList.of(
+            new Route(GET, "/uri")
+        );
+}
+```
+With new scheme:
+```
+public List<NamedRoute> routes() {
+    return ImmutableList.of(
+            new NamedRoute.Builder().method(GET).path("/uri").uniqueName("plugin:uri").actionNames(Set.of("cluster:admin/opensearch/plugin/uri")).build()
+        );
+}
+```
+
+`actionNames()` are optional. They correspond to any current actions defined as permissions in roles.
+Ensure that these name-to-route mappings are easily accessible to the cluster admins to allow granting access to these APIs.
+
+### How does authorization in the REST Layer work?
+
+We will continue on the above example of translating `/uri` from Route to NamedRoute.
+
+Consider these roles are defined in the cluster:
+```yaml
+plugin_role:
+  reserved: true
+  cluster_permissions:
+    - 'plugin:uri'
+
+plugin_role_legacy:
+  reserved: true
+  cluster_permissions:
+    - 'cluster:admin/opensearch/plugin/uri'
+```
+
+Successful authz scenarios for a user:
+1. The user is mapped either to `plugin_role` OR `plugin_role_legacy`.
+2. The user is mapped to both of these roles.
+3. The user is mapped to `plugin_role` even if no `actionNames()` were registered for this route.
+
+Unsuccessful authz scenarios for a user:
+1. The user is not mapped any roles.
+2. The user is mapped to a different role which doesn't grant the cluster permissions: `plugin:uri` OR `cluster:admin/opensearch/plugin/uri`/
+3. The user is mapped to a role `plugin_role_other` which has a typo in action name, i.e.`plugin:uuri`.
+
+
+### Sample API in Security Plugin
+
+As part of this effort a new uri `GET /whoamiprotected` was introduced as a NamedRoute version of `GET /whoami`. Here is how you can test it:
+
+#### roles.yml
+```yaml
+who_am_i_role:
+  reserved: true
+  cluster_permissions:
+    - 'security:whoamiprotected'
+
+who_am_i_role_legacy:
+  reserved: true
+  cluster_permissions:
+    - 'cluster:admin/opendistro_security/whoamiprotected'
+
+who_am_i_role_no_perm:
+  reserved: true
+  cluster_permissions:
+    - 'some_invalid_perm'
+
+```
+
+#### internal_users.yml
+```yaml
+who_am_i-user:
+  hash: "$2a$12$VcCDgh2NDk07JGN0rjGbM.Ad41qVR/YFJcgHp0UGns5JDymv..TOG" #admin
+  reserved: true
+  description: "Demo user for ext-test"
+
+who_am_i_legacy-user:
+  hash: "$2a$12$VcCDgh2NDk07JGN0rjGbM.Ad41qVR/YFJcgHp0UGns5JDymv..TOG"
+  reserved: true
+  description: "Demo user for ext-test"
+
+who_am_i_no_perm-user:
+  hash: "$2a$12$VcCDgh2NDk07JGN0rjGbM.Ad41qVR/YFJcgHp0UGns5JDymv..TOG"
+  reserved: true
+  description: "Demo user for ext-test"
+```
+
+#### roles_mapping.yml
+```yaml
+who_am_i_role:
+  reserved: true
+  users:
+    - "who_am_i-user"
+
+who_am_i_role_legacy:
+  reserved: true
+  users:
+    - "who_am_i_legacy-user"
+
+who_am_i_role_no_perm:
+  reserved: true
+  users:
+    - "who_am_i_no_perm-user"
+```
+
+Follow [DEVELOPER_GUIDE](DEVELOPER_GUIDE.md) to setup OpenSearch cluster and initialize security plugin. Once you have verified that security plugin is installed correctly and OpenSearch is running, execute following curl requests:
+1. `curl -XGET https://who_am_i-user:admin@localhost:9200/_plugins/_security/whoami --insecure` should succeed.
+2. `curl -XGET https://who_am_i_legacy-user:admin@localhost:9200/_plugins/_security/whoami --insecure` should succeed.
+3. `curl -XGET https://who_am_i_no-perm-user:admin@localhost:9200/_plugins/_security/whoami --insecure` should fail.
+4. `curl -XPOST ` to `/whoami` with all 3 users should succeed. This is because POST route is not a NamedRoute and hence no authorization check was made.

TRIAGING.md

@@ -50,6 +50,19 @@ While we are always happy to help the community, the best resource for implement
 
 There you can find answers to many common questions as well as speak with implementation experts.
 
+### What are the issue labels associated with triaging?
+
+Yes, there are several labels that are used to identify the 'state' of issues filed in OpenSearch and the Security Plugin.
+
+| Label | When applied | Meaning |
+| ----- | ------------ | ------- |
+| Untriaged | When issues are created or re-opened. | Issues labeled as 'Untriaged' require the attention of the repository maintainers and may need to be prioritized for quicker resolution. It's crucial to keep the count of 'Untriaged' labels low to ensure all potential security issues are addressed in a timely manner. See [SECURITY.md](https://github.com/opensearch-project/security/blob/main/SECURITY.md) for more details on handling these issues. |
+| Triaged | During triage meetings. | Issues labeled as 'Triaged' have been reviewed and are deemed actionable. Opening a pull request for an issue with the 'Triaged' label has a higher likelihood of approval from the project maintainers, particularly in novel areas. |
+| Neither Label | During triage meetings. | This category is for issues that lack sufficient details to formulate a potential solution. Until more details are provided, it's difficult to ascertain if a proposed solution would be acceptable. When dealing with an 'Untriaged' issue that falls into this category, the triage team should provide further insights so the issue can be appropriately closed or labeled as 'Triaged'. Issues in this state are reviewed during every triage meeting. |
+| Help Wanted | Anytime. | Issues marked as 'Help Wanted' signal that they are actionable and not the current focus of the project maintainers. Community contributions are especially encouraged for these issues. |
+| Good First Issue | Anytime. | Issues labeled as 'Good First Issue' are small in scope and can be resolved with a single pull request. These are recommended starting points for newcomers looking to make their first contributions. |
+
+
 ### What if my issue is critical to OpenSearch operations, do I have to wait for the weekly meeting for it to be addressed?
 
 All new issues for the [security](https://github.com/opensearch-project/security/issues?q=is%3Aissue+is%3Aopen+label%3Auntriaged) repo and [security-dashboards](https://github.com/opensearch-project/security-dashboards-plugin/issues?q=is%3Aissue+is%3Aopen+-label%3Atriaged) repo are reviewed daily to check for critical issues which require immediate triaging. If an issue relates to a severe concern for OpenSearch operation, it will be triaged by a maintainer mid-week. You can still come to discuss an issue at the following meeting even if it has already been triaged during the week.