Update secure RBAC check strings with descriptions

This commit attempts to clarify the intended usage of each persona.
After reading the comment for each, it should be clear how and when to
apply them to specific resources. If not, then we should continue to
improve the definition and remove ambiguity.

This commit also adds a new composite check string for system
administrators and project members. This implements a more robust
security posture where system administrators are allowed to do things
that project member can do. Individual deployments can offload some of
the administrative burden to system members if desired by override the
default SYSTEM_ADMIN_OR_PROJECT_MEMBER check string.

Change-Id: I7bad7b5ebaff3d191c0701a9e72ed4c6334ecaa3

cinder/policies/base.py

@@ -18,15 +18,50 @@ from oslo_policy import policy
 RULE_ADMIN_OR_OWNER = 'rule:admin_or_owner'
 RULE_ADMIN_API = 'rule:admin_api'
 
+# Generic policy check string for system administrators. These are the people
+# who need the highest level of authorization to operate the deployment.
+# They're allowed to create, read, update, or delete any system-specific
+# resource. They can also operate on project-specific resources where
+# applicable (e.g., cleaning up volumes or backups)
 SYSTEM_ADMIN = 'role:admin and system_scope:all'
+
+# Generic policy check string for system users who don't require all the
+# authorization that system administrators typically have. This persona, or
+# check string, typically isn't used by default, but it's existence it useful
+# in the event a deployment wants to offload some administrative action from
+# system administrator to system members
 SYSTEM_MEMBER = 'role:member and system_scope:all'
+
+# Generic policy check string for read-only access to system-level resources.
+# This persona is useful for someone who needs access for auditing or even
+# support. These uses are also able to view project-specific resources where
+# applicable (e.g., listing all volumes in the deployment, regardless of the
+# project they belong to).
 SYSTEM_READER = 'role:reader and system_scope:all'
 
+# This check string is reserved for actions that require the highest level of
+# authorization on a project or resources within the project (e.g., setting the
+# default volume type for a project)
 PROJECT_ADMIN = 'role:admin and project_id:%(project_id)s'
+
+# This check string is the primary use case for typical end-users, who are
+# working with resources that belong to a project (e.g., creating volumes and
+# backups).
 PROJECT_MEMBER = 'role:member and project_id:%(project_id)s'
+
+# This check string should only be used to protect read-only project-specific
+# resources. It should not be used to protect APIs that make writable changes
+# (e.g., updating a volume or deleting a backup).
 PROJECT_READER = 'role:reader and project_id:%(project_id)s'
 
+# The following are common composite check strings that are useful for
+# protecting APIs designed to operate with multiple scopes (e.g., a system
+# administrator should be able to delete any volume in the deployment, a
+# project member should only be able to delete volumes in their project).
 SYSTEM_OR_DOMAIN_OR_PROJECT_ADMIN = 'rule:system_or_domain_or_project_admin'
+SYSTEM_ADMIN_OR_PROJECT_MEMBER = (
+    '(' + SYSTEM_ADMIN + ') or (' + PROJECT_MEMBER + ')'
+)
 SYSTEM_OR_PROJECT_MEMBER = (
     '(' + SYSTEM_MEMBER + ') or (' + PROJECT_MEMBER + ')'
 )