Merge "docs: Add sections about context_is_admin/custom policy checks"

doc/source/framework/overview.rst

@@ -1,11 +1,11 @@
 RBAC Testing Validation
 =======================
 
-.. _framework-overview:
+.. _validation-workflow-overview:
 
---------
-Overview
---------
+----------------------------
+Validation Workflow Overview
+----------------------------
 
 RBAC testing validation is broken up into 3 stages:
 
@@ -38,6 +38,16 @@ RBAC testing validation is broken up into 3 stages:
    ``oslo.policy`` or a 403 from the API call and a ``True`` result from
    ``oslo.policy`` are failing results.
 
+.. warning::
+
+  Note that Patrole cannot currently derive the expected policy result for
+  service-specific ``oslo.policy`` `checks`_, like Neutron's `FieldCheck`_,
+  because such checks are contained within the service's code base itself,
+  which Patrole cannot import.
+
+.. _checks: https://docs.openstack.org/oslo.policy/latest/reference/api/oslo_policy.policy.html#generic-checks
+.. _FieldCheck: https://docs.openstack.org/neutron/pike/contributor/internals/policy.html#fieldcheck-verify-resource-attributes
+
 -------------------------------
 The RBAC Rule Validation Module
 -------------------------------

doc/source/rbac-overview.rst

@@ -57,7 +57,7 @@ the out-of-the-box defaults are sanity-checked, to ensure that OpenStack
 services are secure, from an RBAC perspective, for each release.
 
 Patrole strives to validate RBAC by using the policy in code documentation,
-wherever possible.
+wherever possible. See :ref:`validation-workflow-overview` for more details.
 
 .. _custom-policies:
 
@@ -85,8 +85,7 @@ specifications via policy overrides, without:
 
 This has implications on Patrole's :ref:`design-principles`: validating custom
 overrides requires the ability to handle arbitrary roles, which requires logic
-capable of dynamically determining expected test behavior. See
-:ref:`rbac-validation` for more details.
+capable of dynamically determining expected test behavior.
 
 Note that support for custom policies is limited. This is because custom
 policies can be arbitrarily complex, requiring that tests be very robust
@@ -140,6 +139,39 @@ Most OpenStack services raise a ``403 Forbidden`` following failed
 as well. See Neutron's `authorization policy enforcement`_ documentation
 for more details.
 
+Admin Context Policy
+--------------------
+
+The so-called "admin context" policy refers to the following policy definition
+(using the legacy policy file syntax):
+
+.. code-block:: javascript
+
+  {
+    "context_is_admin": "role:admin"
+    ...
+  }
+
+Which is unfortunately used to bypass ``oslo.policy`` authorization checks,
+for example:
+
+.. code-block:: python
+
+  # This function is responsible for calling oslo.policy to check whether
+  # requests are authorized to perform an API action.
+  def enforce(context, action, target, [...]):
+    # Here this condition, if True, skips over the enforce call below which
+    # is what calls oslo.policy.
+    if context.is_admin:
+        return True
+    _ENFORCER.enforce([...])  # This is what can be skipped over.
+    [...]
+
+This type of behavior is currently present in many services. Unless such
+logic is removed in the future for services that implement it, Patrole
+won't really be able to validate that admin role works from an ``oslo.policy``
+perspective.
+
 Glossary
 --------
 

doc/source/test_writing_guide.rst

@@ -10,8 +10,8 @@ Patrole tests are broken up into 3 stages:
 #. :ref:`rbac-test-execution`
 #. :ref:`rbac-test-cleanup`
 
-See the :ref:`framework overview documentation <framework-overview>` for a
-high-level explanation of the entire testing work flow and framework
+See the :ref:`framework overview documentation <validation-workflow-overview>`
+for a high-level explanation of the entire testing work flow and framework
 implementation. The guide that follows is concerned with helping developers
 know how to write Patrole tests.