[DOC] Add doc for Authorization in REST Layer

[DarshitChanpura]

What do you want to do?

• Request a change to existing documentation
• Add new documentation
• Report a technical problem with the documentation
• Other

Tell us about your request. Provide a summary of the request and all versions that are affected.

Description of the Feature

The Security plugin has recently introduced a new feature. This addition enhances the plugin's capabilities by enabling user authorization for requested REST routes. Let's delve into the details of how this feature functions.

NOTE: This feature sits on top of existing authorization check at Transport Layer. No changes were made at Transport Layer.

During the registration of a new route, the plugin requires a unique name to be assigned to each route. This ensures that no duplicate names are used during the registration process. Additionally, the plugin provides the option to register a set of "legacy" cluster permissions for each route. These permissions, such as cluster:admin/transport/, serve as the criteria against which the route is evaluated when a user attempts to access it.

Functionality of the Feature

The authorization process for this feature operates as follows: when a user initiates a REST request, their roles are examined, and each permission associated with the user is evaluated. The evaluation is conducted to determine if either of the following conditions is met: a match with the unique name assigned to the route or a match with any of the legacy actions defined during the route's registration.

For instance, let's consider a scenario where a user is assigned to role A. Here is an example configuration in YAML format:

abcplugin_read_access:
  reserved: true
  cluster_permissions:
    - 'cluster:admin/opensearch/abcplugin/route/get'
    - 'cluster:admin/opensearch/abcplugin/route/put'

Suppose the plugin has two registered routes under the abcplugin namespace as instance of NamedRoute:

1. /_plugins/_abcplugin/route/get registered with the unique name routeGet and associated with the legacy transport action cluster:admin/opensearch/abcplugin/route/get.
2. /_plugins/_abcplugin/route/delete registered with the unique name routeDelete and associated with the legacy transport action cluster:admin/opensearch/abcplugin/route/delete.

In this scenario, when the user makes a REST API call to /_plugins/_abcplugin/route/get, they will be granted authorization. The request flow will proceed as normal.
However, if the same user attempts a REST call to /_plugins/_abcplugin/route/delete, they will be denied authorization and receive an error message.

Goal of the documentation

1. It should help plugin developers point to the correct resources, for registering named routes
2. It should help end user define correct permission actions in the roles.

Related issue: opensearch-project/security#2590

[cwillum]

Getting this started now.

[hdhalter]

As per Dave, this has been moved to 2.10.

[peternied]

@cwillum This is not going to make it for 2.10, moving to 2.11 - sorry for the shuffle.

CC: @davidlago @hdhalter