[META] Document fine-grained access control permissions needed for each client call

[Jon-AtAWS]

This is a generic comment, across clients.

I often stumble when trying to make API calls, to understand the needed permissions under fine-grained access control. The problem is made somewhat worse, and somewhat better, with action groups. Mapping the action groups to what they actually do is made easier by this page https://opensearch.org/docs/latest/security/access-control/default-action-groups/. But even that doesn't go all the way, since I don't know what API calls are under the client calls.

For each client, and each API, can we document the permissions (not the action group) required to execute that API.

If we can add comments to the individual clients' methods, we should be able to auto-generate this documentation. Either way, we need to put the information somewhere.

[wbeckler]

This could live in the API spec and both the comments and documentation could be generated from that.

[dblock]

I'm moving this to opensearch-api-specification.

[dblock]

@nhtruong @Xtansia

Where would be put this type of metadata in the newer flavor of OpenAPI spec that we're POCing?

[nhtruong]

Each API operation can be accompanied by a description property. Though it's only meant for a few sentences to summarize the operation. It's best to add an externalDocs to a doc that fully explains the feature.

[Xtansia]

We can also always add a x-required-permissions: ['indices:admin/mapping/put'] extension property on the operations

[Jon-AtAWS]

That is the idea, BUT:

Whatever route we go, we need to specify whether the permission is under cluster_permissions or index_permissions. You can (and sometimes have to) add indices:* permissions at the cluster level. I admit to being completely confused about where to put, e.g. indices:write/data/bulk.

By Cluster level, I mean cluster_permissions in the FGAC policy:

            fgac_cluster_perms = {
                "cluster_permissions": [
                    "cluster_monitor",
                    "indices_all"
                ],
                "index_permissions": [{
                    "index_patterns": [
                        "*"
                    ],
                    "dls": "",
                    "fls": [],
                    "masked_fields": [],
                    "allowed_actions": [
                        "indices_all"
                    ]
                }]
            }