docs: Add sections about context_is_admin/custom policy checks

This documentation adds oslo.policy/policy related information
to Patrole RBAC documentation so users understand some limitations
related to current implementation of oslo.policy in OpenStack
and some limitations around edge case policy testing w.r.t custom
oslo.policy rulechecks.

* Currently admin context policy rule is used to skip over oslo.policy
  authorization checks in many services -- this is important to note
  as this means Patrole can't properly validate admin against
  oslo.policy [0].
* Currently it is not possible to test policy rules that rely on
  generic checks/oslo.policy checks defined in services themselves
  like Neutron's FieldCheck [1] as Patrole has no way of importing such
  code in order to get these checks registered.

[0] b4b725ade9/neutron/policy.py (L374)
[1] https://docs.openstack.org/neutron/pike/contributor/internals/policy.html#fieldcheck-verify-resource-attributes

Change-Id: I0e375a11eb323d83b1ece1537dbd008633126eb3

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.