Merge "docs: Add sections about context_is_admin/custom policy checks"
diff --git a/doc/source/framework/overview.rst b/doc/source/framework/overview.rst
index 113d461..8e04082 100644
--- a/doc/source/framework/overview.rst
+++ b/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 @@
``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
-------------------------------
diff --git a/doc/source/rbac-overview.rst b/doc/source/rbac-overview.rst
index 5eefa5c..09ab17d 100644
--- a/doc/source/rbac-overview.rst
+++ b/doc/source/rbac-overview.rst
@@ -57,7 +57,7 @@
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 @@
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 @@
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
--------
diff --git a/doc/source/test_writing_guide.rst b/doc/source/test_writing_guide.rst
index 61ab326..1291201 100644
--- a/doc/source/test_writing_guide.rst
+++ b/doc/source/test_writing_guide.rst
@@ -10,8 +10,8 @@
#. :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.