Document which APIs are affected by which role pivileges

[Erni]

Currently our documentation states the Cluster andIndices privileges that you can set to your roles: https://www.elastic.co/guide/en/x-pack/current/security-privileges.html

That´s fine but there are many users not knowing the actual requests a particular privilege allows to do.
For example imagine the manage_index_templates privilege. Its description says All operations on index templates. However many users might be confuser not being allowed to execute the _cat/templates API call with this privilege.
So there´s clearly a need to specify the APIs and actions that every privilege involves.

[elasticmachine]

Pinging @elastic/es-security

[tvernum]

We've discussed this (a few times).

Actually documenting which privileges are required by each Rest API is an impossible task. The API changes rapidly enough that the documentation simply can't keep up - and the way Elasticsearch works with plugins means that it's not something that is easy to generate automatically.

There are 2 things we think we can do:

1. Make some general improvements to the privileges pages. They've been around for a while, and haven't seen a lot of love in the last few years. We can definitely document some of those privileges more clearly so that it is more obvious what they are intended to allow.
2. Make the "permission denied" error more explicit & actionable. At the moment you get something like "user [xyz] is not permitted to perform action [cluster:foo/bar]" which is factually correct, but not of a lot of use to the person who it trying to setup roles for their needs. We can do better here.

I'm going to raise issues for each of those, at which point I will close this issue.

[tvernum]

I raised

• Make builtin privileges docs more explicit  #42165
• Authorization denial errors are not actionable #42166