Troubleshoot authorization errors need refinement

[eedugon]

Type of issue

None

What documentation page is affected

https://www.elastic.co/docs/troubleshoot/elasticsearch/security/security-trb-roles

What happened?

That doc needs a lot of refinement, as it feels a bit disconnected.

It directly talks about roles defined in roles.yml where roles can also be defined in the native realm, also it looks it's scoped for file realm but also mentions LDAP without giving enough background.

It also mentions elasticsearch-users command where it's not needed and makes the content only valid for self-managed environments.

The most important troubelshooting guidance of the doc is at the end, which is the increase of logging levels to analyze the authorization error.

I'd suggest to rewrite it a bit, improving the introduction, explaining what type of issue it address, then explaining the most common and useful troubleshooting method (increasing log level), and finally explaining some possible problems, clarifying each of them with proper scope, like:

• IF YOU ARE USING THE FILE REALM (with link), then check that the roles.yml contains..., you can use elasticsearch-users command to .... (all that for the file realm example).

• IF YOU ARE USING LDAP (with link), typical authorization errors are related with the group mappings that are defined with......

• For other external REALMS (with link),.....

PS - Also note that the log level increase is also useful to troubleshoot authentication problems with external realms, not only authorization. I'll check if we can also make this doc valid to troubleshoot authentication and authorization errors in general.

Additional info

No response