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] https://github.com/openstack/neutron/blob/b4b725ade9e11aff80c6193cb4acd49f2aba012d/neutron/policy.py#L374
[1] https://docs.openstack.org/neutron/pike/contributor/internals/policy.html#fieldcheck-verify-resource-attributes
Change-Id: I0e375a11eb323d83b1ece1537dbd008633126eb3
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
-------------------------------