We have a document in our administrator guide that describes what tokens are, different scope types, and token providers [0]. While this is good information, we could elaborate on it a bit more to make the document even more useful:
- Different types of scopes should have examples (e.g. project-scope == instance management)
- Remove references to the UUID token provider, which has already been removed
- Consider breaking the Authorization Scopes section out of the admin guide and into the user guide (it contains information that would be useful for end users as well as operators)
We get comments from developers of other services about how scopes work (See Michael's comment in patch set 8 [1]). I think most people close to the system-scope work understand it because we've been exposed to the problem for so long and are familiar with the implementation. It'd be nice to work a fresh perspective into the Authorization Types document, or even have a separate document that explains the different scopes and how they relate to other services [2].
[0] https://docs.openstack.org/keystone/latest/admin/identity-tokens.html
[1] https://review.openstack.org/#/c/523973/
[2] https://docs.openstack.org/keystone/latest/contributor/services.html
Fix proposed to branch: master
Review: https:/