Add documentation for authorization on the REST layer

[cwillum]

Description

To support extensions, authorization of API actions can now be carried out on the REST layer, necessarily for extensions and optionally for new and existing plugins. This PR documents details surrounding the enhancement.

Issues Resolved

Fixes #4381

Checklist

• By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license and subject to the Developers Certificate of Origin.
  For more information on following Developer Certificate of Origin and signing off your commits, please check here.

[cwillum]

Just collecting the dots at this point. Thus the draft status.

[cwillum]

Received news that this will most likely get pushed to 2.10.

[cwillum]

@DarshitChanpura Could you have a look at this for technical accuracy, language, and completeness? I'm not sure if I got some of the language-concept agreement right in some cases. Thanks.

[DarshitChanpura]

Some minor changes requested. Thank you @cwillum for putting this together.

[DarshitChanpura]

Suggested change

Authorization on the REST layer provides an added level of security for plugin and extension API requests by offering a mechanism for authorization checks on the REST layer. This level of security sits atop the transport layer and provides a complementary method of authorization without replacing, modifying, or in any way changing the same process on the transport layer. REST layer authorization was initially created to address the need for an authorization check for extensions, which do not communicate on the transport layer. However, the feature is also supported for existing plugins and will be available for future plugins created to operate with OpenSearch.

Authorization on the REST layer provides an added level of security for plugin and extension API requests by offering a mechanism for authorization checks on the REST layer. This level of security sits atop the transport layer and provides a complementary method of authorization without replacing, modifying, or in any way changing the same process on the transport layer. REST layer authorization was initially created to address the need for an authorization check for extensions, which do not communicate on the transport layer. However, the feature is also available for developers to utilize while creating future plugins to operate with OpenSearch.

Current plugins have not been migrated to utilize this feature. But, the feature is available for current plugins to migrate their APIs to support authorization.

[DarshitChanpura]

Suggested change

	The benefits to developers when using the REST layer for authorization mean that they do not need to build transport layer actions and get authorization for them to adhere to security procedures. As a result, this decreases the code-writing burden and time invested in creating a single action. As an alternative, they can create REST API actions and authorize them on the REST layer.
	The benefits to developers when using the REST layer for authorization mean that they can authorize requests at REST layer and filter out unauthorized requests. As a result, this decreases the processing burden on transport layer while allowing granular control over access to APIs.

We are not replacing transport authz, we are just adding a layer on top.

[DarshitChanpura]

This is true only for extensions. For plugins, developers will have to declare the permission names.

[cwillum]

@DarshitChanpura (1) What exact part of "this" is true for creating a permission name for extensions? Is it this whole piece: "... the routeNamePrefix value in the settings.yml file for the resource ad is added to the route to complete a unique name."?
(2) Is there any guidance for declaring a permission name for plugins? Are there required elements in the name like that for a permission name for an extension? Or do you just invent anything you want?

[DarshitChanpura]

Apologies for confusion. By "this" I mean the routeNamePrefix is a setting only configured in extension. This setting doesn't exist in plugins.

There is no guidance as of now in defining permissions. But we can make a suggestion to have it something like: <plugin/extension-name>:<route> (i.e. ad:detectors/get)

Let me know if this helps.

[cwillum]

@DarshitChanpura Thanks for the clarification. I've adjusted that wording to include current understanding for extensions and plugins. I've also addressed the other two comments/suggestions. I think this should be ready for documentation team review when 2.11 comes along. I'll comment that it's on hold for that. And if there are any changes between now and then, we can always revise the current draft before the release.

[cwillum]

The work is essentially done for this PR. I considered adding the status tag "Done but waiting to merge". But it will need documentation team review and editorial review before merging for 2.11. I'm leaving it alone for now in case the Security team wants any additional changes before then.

[DarshitChanpura]

LGTM!

[cwillum]

Stepping this up to doc review.

[Naarcha-AWS]

Two small fixes, otherwise LGTM.

[DarshitChanpura]

LGTM. @Naarcha-AWS Would you please re-review this?

[natebower]

@cwillum Just a few comments/changes. Thanks for your advance work on this!

[natebower]

It's probably worth noting that up to this point, we used "on" the REST layer as opposed to "at". We should probably be consistent throughout.

[cwillum]

RE: Authorization at REST Layer for plugins
Yeah, I can't do anything about the name of that resource. It's created by Security team developers. But point taken.