Clarify top-level personas in RBAC documentation

This commit updates the documentation for service api protection to
better describe the overall personas for system, domain, and project
users. It also adds some examples that show operators how to list users
with all role assignments on a particular target, which include a
superset of the existing examples.

Change-Id: I40dd33fc0afa0240c6b1cd48322fd988fc5524af

1 files changed, 69 insertions, 13 deletions

diff --git a/doc/source/admin/service-api-protection.rst b/doc/source/admin/service-api-protection.rst
index d7f146a39..dd90c7efe 100644
--- a/doc/source/admin/service-api-protection.rst
+++ b/doc/source/admin/service-api-protection.rst
@@ -132,9 +132,30 @@ services are addressing this individually at their own pace).
    As of the Train release, keystone applies the following personas
    consistently across its API.
 
----------------------
+---------------
+System Personas
+---------------
+
+This section describes authorization personas typically used for operators and
+deployers. You can find all users with system role assignments using the
+following query:
+
+.. code-block:: console
+
+    $ openstack role assignment list --names --system all
+    +--------+------------------------+------------------------+---------+--------+--------+-----------+
+    | Role   | User                   | Group                  | Project | Domain | System | Inherited |
+    +--------+------------------------+------------------------+---------+--------+--------+-----------+
+    | admin  |                        | system-admins@Default  |         |        | all    | False     |
+    | admin  | admin@Default          |                        |         |        | all    | False     |
+    | admin  | operator@Default       |                        |         |        | all    | False     |
+    | reader |                        | system-support@Default |         |        | all    | False     |
+    | admin  | operator@Default       |                        |         |        | all    | False     |
+    | member | system-support@Default |                        |         |        | all    | False     |
+    +--------+------------------------+------------------------+---------+--------+--------+-----------+
+
 System Administrators
----------------------
+=====================
 
 *System administrators* are allowed to manage every resource in keystone.
 System administrators are typically operators and cloud administrators. They
@@ -148,7 +169,7 @@ assignments:
 
 .. code-block:: console
 
-    $ openstack role assignment list --names --system all
+    $ openstack role assignment list --names --system all --role admin
     +-------+------------------+-----------------------+---------+--------+--------+-----------+
     | Role  | User             | Group                 | Project | Domain | System | Inherited |
     +-------+------------------+-----------------------+---------+--------+--------+-----------+
@@ -157,9 +178,8 @@ assignments:
     | admin | operator@Default |                       |         |        | all    | False     |
     +-------+------------------+-----------------------+---------+--------+--------+-----------+
 
--------------------------------
 System Members & System Readers
--------------------------------
+===============================
 
 In keystone, *system members* and *system readers* are very similar and have
 the same authorization. Users with these roles on the system can view all
@@ -187,9 +207,28 @@ assignments:
    Filtering system role assignments is currently broken and is being tracked
    as a `bug <https://bugs.launchpad.net/keystone/+bug/1846817>`_.
 
----------------------
+---------------
+Domain Personas
+---------------
+
+This section describes authorization personas for people who manage their own
+domains, which contain projects, users, and groups. You can find all users with
+role assignments on a specific domain using the following query:
+
+.. code-block:: console
+
+    $ openstack role assignment list --names --domain foobar
+    +--------+-----------------+----------------------+---------+--------+--------+-----------+
+    | Role   | User            | Group                | Project | Domain | System | Inherited |
+    +--------+-----------------+----------------------+---------+--------+--------+-----------+
+    | reader | support@Default |                      |         | foobar |        | False     |
+    | admin  | jsmith@Default  |                      |         | foobar |        | False     |
+    | admin  |                 | foobar-admins@foobar |         | foobar |        | False     |
+    | member | jdoe@foobar     |                      |         | foobar |        | False     |
+    +--------+-----------------+----------------------+---------+--------+--------+-----------+
+
 Domain Administrators
----------------------
+=====================
 
 *Domain administrators* can manage most aspects of the domain or its contents.
 These users can create new projects and users within their domain. They can
@@ -212,9 +251,8 @@ assignment:
     | admin |                | foobar-admins@foobar |         | foobar |        | False     |
     +-------+----------------+----------------------+---------+--------+--------+-----------+
 
--------------------------------
 Domain Members & Domain Readers
--------------------------------
+===============================
 
 Domain members and domain readers have the same relationship as system members
 and system readers. They're allowed to view resources and information about
@@ -241,10 +279,29 @@ members and domain readers with the following role assignments:
     | reader | support@Default |       |         | foobar |        | False     |
     +--------+-----------------+-------+---------+--------+--------+-----------+
 
+----------------
+Project Personas
+----------------
+
+This section describes authorization personas for users operating within a
+project. These personas are commonly used by end users. You can find all users
+with role assignments on a specific project using the following query:
+
+.. code-block:: console
+
+    $ openstack role assignment list --names --project production
+    +--------+----------------+----------------------------+-------------------+--------+--------+-----------+
+    | Role   | User           | Group                      | Project           | Domain | System | Inherited |
+    +--------+----------------+----------------------------+-------------------+--------+--------+-----------+
+    | admin  | jsmith@Default |                            | production@foobar |        |        | False     |
+    | admin  |                | production-admins@foobar   | production@foobar |        |        | False     |
+    | member |                | foobar-operators@Default   | production@foobar |        |        | False     |
+    | reader | alice@Default  |                            | production@foobar |        |        | False     |
+    | reader |                | production-support@Default | production@foobar |        |        | False     |
+    +--------+----------------+----------------------------+-------------------+--------+--------+-----------+
 
-----------------------
 Project Administrators
-----------------------
+======================
 
 *Project administrators* can only view and modify data within the project in
 their role assignment. They're able to view information about their projects
@@ -266,9 +323,8 @@ role assignment:
     | admin |                | production-admins@foobar | production@foobar |        |        | False     |
     +-------+----------------+--------------------------+-------------------+--------+--------+-----------+
 
----------------------------------
 Project Members & Project Readers
----------------------------------
+=================================
 
 *Project members* and *project readers* can discover information about their
 projects. They can access important information like resource limits for their