[DOC] - Expand keycloak roles docs

[kcpevey]

Preliminary Checks

• This issue is not a question, feature request, RFC, or anything other than a bug report. Please post those things in GitHub Discussions: https://github.com/nebari-dev/nebari/discussions

Summary

The docs for roles cover a limited number of usecases. It would be very beneficial to expand these. I spent hours trying to figure out these roles and how they related to each other at different levels.

First, the table in https://www.nebari.dev/docs/how-tos/nebari-extension-system explains the difference between admin/superadmin/developer/analyst. The table is fine in understanding "if I give someone developer role, they can do this list of things".

Here are the issues with the table:

• Not all of the roles are explained (conda-store roles and grafana roles). We need practical usage explanations here: "user can access existing grafana dashboards but not edit or create new ones or run queries", "user can use conda envs in all shared envs, but not create envs in any namespace other than their own".
• The table has bullet points in different columns but each bullet corresponds to a bullet in the following column (except when it doesn't). It would be better to add explicit rows to make it easier to follow.
• I don't know what "read access to Jupyter scheduler" is but I'm not convinced its a thing. You can never see other people's jobs via the scheduler UI. So if you can't submit jobs, there is never anything to view?

Also, if I want to give someone slightly different roles, I will need to do that on my own. The issue here is that we have instructions for creating fine-grained access (https://www.nebari.dev/docs/how-tos/fine-grained-permissions#creating-a-role) but...

• There is no link between the two documents
• The docs say that nebari comes with 5 clients. These should be explained. Also, there are 13 in our deployment...
• All of the roles discussed in this document are at a level LOWER than the first document. So the first doc explained (sort of) the dask_developer role. But here I see things like dask_gateway_developer. Does dask_developer control different things than dask_gateway_developer?? Which one should I use?
• This doc shows the allow-app-sharing-role - what is that? Its never explained and in fact, the control over app sharing is never explained. I assume that one of the high level roles also controls that (e.g. admin/developer/analyst), but its not documented.
• What are Realm roles? We have default-roles-nebari, offline_access and uma_authorization. What are these?
• This whole doc is operating at a lower level than the first, which is totally fine but there is no explanations for what any of these roles are or what they do. We need a lookup table with plain language explanations.