Clarify ``reader`` role implementation in persona admin guide

The secure RBAC work propogating throughout the community has led to
some interesting discussions about how to implement support for
``reader``. Specifically, should ``reader`` be used for auditing
deployments?

Some compliance targets, verified by third-party auditors, require
access to sensitive information (e.g., thinking about license keys in
glance images or volume type encryption metadata in cinder). The concern
raised among developers updating their default policies to use
``reader`` roles is if they should be using that role to protect
sensitive information, especially if it's the least-authoritative role
in the hierarchy between reader, member, and admin.

This documentation is supposed to assist deployers in understanding the
various personas that developers are implementing by default, but it
doesn't call out the complicated relationship we have with ``reader``
and auditing.

The change here proposes that we explicitly say that ``reader``
shouldn't be used to protect sensitive information, regardless of the
scope, because ``reader`` was designed to be the least-authoritative
role provided by keystone, by default. Instead, service developers
working to implement these personas consistently in other services
should keep sensitive information, if applicable to their API or
resources, at the ``admin`` tier of the hierarchy. This provides better
protection of sensitive information by not exposing is implicitly.

We can consider supporting a formal default role for auditing in the
future, but building it outside the default implied role tree so that
it's not implied to anyone with a role assignment. This will come at
another time and we can use implied roles to re-use all the work we've
done across OpenStack to implement support for ``reader``.

For now, ``reader`` should be viewed from the perspective of the
least-authoritative permissions grant-able to a given scope (e.g.,
system, domain, or project). Even if ``reader`` has limited use in
auditing deployments, it's still incredibly useful for operators
because they have a role they can grant to users with minimal trust, or
minimal permissions in the deployment.

This commit acknowledges the use-case for an elevated auditor role and
that it's something we can implement as a formal role in keystone in the
future.

Change-Id: Iea28faf1b3e63c7ab07e90808d2bc76ee3ee0612

1 files changed, 67 insertions, 28 deletions

diff --git a/doc/source/admin/service-api-protection.rst b/doc/source/admin/service-api-protection.rst
index 80b8af150..d7f146a39 100644
--- a/doc/source/admin/service-api-protection.rst
+++ b/doc/source/admin/service-api-protection.rst
@@ -10,14 +10,16 @@ Like most OpenStack services, keystone protects its API using role-based access
 control (RBAC).
 
 Users can access different APIs depending on the roles they have on a project,
-domain, or system.
+domain, or system, which we refer to as scope.
 
 As of the Rocky release, keystone provides three roles called ``admin``,
 ``member``, and ``reader`` by default. Operators can grant these roles to any
-actor (e.g., group or user) on any target (e.g., system, domain, or project).
+actor (e.g., group or user) on any scope (e.g., system, domain, or project).
 If you need a refresher on authorization scopes and token types, please refer
 to the `token guide`_. The following sections describe how each default role
-behaves with keystone's API across different scopes.
+behaves with keystone's API across different scopes. Additionally, other
+service developers can use this document as a guide for implementing similar
+patterns in their services.
 
 Default roles and behaviors across scopes allow operators to delegate more
 functionality to their team, auditors, customers, and users without maintaining
@@ -29,9 +31,10 @@ custom policies.
 Roles Definitions
 -----------------
 
-The default roles imply one another. The ``admin`` role implies the ``member``
-role, and the ``member`` role implies the ``reader`` role. This implication
-means users with the ``admin`` role automatically have the ``member`` and
+The default roles provided by keystone, via ``keystone-manage boostrap``, are
+related through role implications. The ``admin`` role implies the ``member``
+role, and the ``member`` role implies the ``reader`` role. These implications
+mean users with the ``admin`` role automatically have the ``member`` and
 ``reader`` roles. Additionally, users with the ``member`` role automatically
 have the ``reader`` role. Implying roles reduces role assignments and forms a
 natural hierarchy between the default roles. It also reduces the complexity of
@@ -51,6 +54,26 @@ Instead of:
 Reader
 ======
 
+.. warning::
+
+   While it's possible to use the ``reader`` role to perform audits, we highly
+   recommend assessing the viability of using ``reader`` for auditing from the
+   perspective of the compliance target you're pursuing.
+
+   The ``reader`` role is the least-privileged role within the role hierarchy
+   described here. As such, OpenStack development teams, by default, do not
+   advocate exposing sensitive information to users with the ``reader`` role,
+   regardless of the scope. We have noted the need for a formal, read-only,
+   role that is useful for inspecting all applicable resources within a
+   particular scope, but it shouldn't be implemented as the lowest level of
+   authorization. This work will come in a subsequent release where we support
+   an elevated read-only role, that implies ``reader``, but also exposes
+   sensitive information, where applicable.
+
+   This will allow operators to grant third-party auditors a permissive role
+   for viewing sensitive information, specifically for compliance targets that
+   require it.
+
 The ``reader`` role provides read-only access to resources within the system, a
 domain, or a project. Depending on the assignment scope, two users with the
 ``reader`` role can expect different API behaviors. For example, a user with
@@ -64,6 +87,20 @@ roles. For example, to accomplish this without analyzing assignment scope, you
 would need ``system-reader``, ``domain-reader``, and ``project-reader`` roles
 in addition to custom policies for each service.
 
+It's imperative to note that ``reader`` is the least authoritative role in the
+hierarchy because assignments using ``admin`` or ``member`` ultimately include
+the ``reader`` role. We document this explicitly so that ``reader`` roles are not
+overloaded with read-only access to sensitive information. For example, a deployment
+pursuing a specific compliance target may want to leverage the ``reader`` role
+to perform the audit. If the audit requires the auditor to evaluate sensitive
+information, like license keys or administrative metadata, within a given
+scope, auditors shouldn't expect to perform these operations with the
+``reader`` role. We justify this design decision because sensitive information
+should be explicitly protected, and not implicitly exposed.
+
+The ``reader`` role should be implemented and used from the perspective of
+least-privilege, which may or may not fulfill your auditing use case.
+
 Member
 ======
 
@@ -126,23 +163,24 @@ 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
-resources within keystone. They can audit role assignments, users, projects,
-and group memberships, among other resources.
+resources within keystone. They can list role assignments, users, projects, and
+group memberships, among other resources.
 
-The *system reader* persona is useful for auditors or members of a support
-team. You can find *system members* and *system readers* in your deployment
-with the following assignments:
+The *system reader* persona is useful for members of a support team or auditors
+if the audit doesn't require access to sensitive information. You can find
+*system members* and *system readers* in your deployment with the following
+assignments:
 
 .. code-block:: console
 
     $ openstack role assignment list --names --system all --role member --role reader
-    +--------+------------------------+-------------------------+---------+--------+--------+-----------+
-    | Role   | User                   | Group                   | Project | Domain | System | Inherited |
-    +--------+------------------------+-------------------------+---------+--------+--------+-----------+
-    | reader |                        | system-auditors@Default |         |        | all    | False     |
-    | admin  | operator@Default       |                         |         |        | all    | False     |
-    | member | system-support@Default |                         |         |        | all    | False     |
-    +--------+------------------------+-------------------------+---------+--------+--------+-----------+
+    +--------+------------------------+------------------------+---------+--------+--------+-----------+
+    | Role   | User                   | Group                  | Project | Domain | System | Inherited |
+    +--------+------------------------+------------------------+---------+--------+--------+-----------+
+    | reader |                        | system-support@Default |         |        | all    | False     |
+    | admin  | operator@Default       |                        |         |        | all    | False     |
+    | member | system-support@Default |                        |         |        | all    | False     |
+    +--------+------------------------+------------------------+---------+--------+--------+-----------+
 
 .. warning::
 
@@ -183,9 +221,10 @@ and system readers. They're allowed to view resources and information about
 their domain. They aren't allowed to access system-specific information or
 information about projects, groups, and users outside their domain.
 
-The domain member and domain reader use-cases are great for auditing, support,
-or monitoring the details of an account. You can find domain members and domain
-readers with the following role assignments:
+The domain member and domain reader use-cases are great for support teams,
+monitoring the details of an account, or auditing resources within a domain
+assuming the audit doesn't validate sensitive information. You can find domain
+members and domain readers with the following role assignments:
 
 .. code-block:: console
 
@@ -199,7 +238,7 @@ readers with the following role assignments:
     +--------+-----------------+-------+---------+--------+--------+-----------+
     | Role   | User            | Group | Project | Domain | System | Inherited |
     +--------+-----------------+-------+---------+--------+--------+-----------+
-    | reader | auditor@Default |       |         | foobar |        | False     |
+    | reader | support@Default |       |         | foobar |        | False     |
     +--------+-----------------+-------+---------+--------+--------+-----------+
 
 
@@ -249,12 +288,12 @@ the following role assignments:
     | member |      | foobar-operators@Default | production@foobar |        |        | False     |
     +--------+------+--------------------------+-------------------+--------+--------+-----------+
     $ openstack role assignment list --names --project production --role reader
-    +--------+-----------------+----------------------------+-------------------+--------+--------+-----------+
-    | Role   | User            | Group                      | Project           | Domain | System | Inherited |
-    +--------+-----------------+----------------------------+-------------------+--------+--------+-----------+
-    | reader | auditor@Default |                            | production@foobar |        |        | False     |
-    | reader |                 | production-support@Default | production@foobar |        |        | False     |
-    +--------+-----------------+----------------------------+-------------------+--------+--------+-----------+
+    +--------+---------------+----------------------------+-------------------+--------+--------+-----------+
+    | Role   | User          | Group                      | Project           | Domain | System | Inherited |
+    +--------+---------------+----------------------------+-------------------+--------+--------+-----------+
+    | reader | alice@Default |                            | production@foobar |        |        | False     |
+    | reader |               | production-support@Default | production@foobar |        |        | False     |
+    +--------+---------------+----------------------------+-------------------+--------+--------+-----------+
 
 ----------------
 Writing Policies