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

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