Rename rbac_policy_parser to policy_authority
This change is a follow-up to commit
I8ba89ab5e134b15e97ac20a7aacbfd70896e192f
which introduced an abstract class from which (previously)
rbac_policy_parser and requirements authority inherit, providing
rbac_rule_validation with 2 ways of validating RBAC.
For the sake of naming consistency, rbac_policy_parser is renamed
to policy_authority. This naming scheme is better because
"policy parser" is implementation-specific and doesn't convey
what the file (and class name) do from a high-level perspective.
Because this file is only used internally to Patrole, it can be
changed without backward-compatibility concerns.
This commit also includes documentation for the policy authority
module and the rbac_rule_validation module.
Change-Id: Ie09fc2d884f9211244b062fdd5fe018970c2bb2d
diff --git a/doc/source/HACKING.rst b/doc/source/HACKING.rst
new file mode 100644
index 0000000..1847447
--- /dev/null
+++ b/doc/source/HACKING.rst
@@ -0,0 +1,4 @@
+=======
+Hacking
+=======
+.. include:: ../../HACKING.rst
diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst
deleted file mode 100644
index 1728a61..0000000
--- a/doc/source/contributing.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-============
-Contributing
-============
-.. include:: ../../CONTRIBUTING.rst
diff --git a/doc/source/index.rst b/doc/source/index.rst
index f58ee7f..e2cc0bd 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -20,9 +20,17 @@
=================
.. toctree::
+ :maxdepth: 1
+
+ HACKING
+
+Framework
+---------
+
+.. toctree::
:maxdepth: 2
- contributing
+ rbac_validation
Indices and tables
==================
diff --git a/doc/source/rbac_validation.rst b/doc/source/rbac_validation.rst
new file mode 100644
index 0000000..ccaf3c8
--- /dev/null
+++ b/doc/source/rbac_validation.rst
@@ -0,0 +1,64 @@
+.. _rbac-validation:
+
+RBAC Testing Validation
+=======================
+
+--------
+Overview
+--------
+
+RBAC Testing Validation is broken up into 3 stages:
+
+ 1. "Expected" stage. Determine whether the test should be able to succeed
+ or fail based on the test role defined by ``[patrole] rbac_test_role``)
+ and the policy action that the test enforces.
+ 2. "Actual" stage. Run the test by calling the API endpoint that enforces
+ the expected policy action using the test role.
+ 3. Comparing the outputs from both stages for consistency. A "consistent"
+ result is treated as a pass and an "inconsistent" result is treated
+ as a failure. "Consistent" (or successful) cases include:
+
+ * Expected result is ``True`` and the test passes.
+ * Expected result is ``False`` and the test fails.
+
+ "Inconsistent" (or failing) cases include:
+
+ * Expected result is ``False`` and the test passes. This results in an
+ ``RbacOverPermission`` exception getting thrown.
+ * Expected result is ``True`` and the test fails. This results in a
+ ``Forbidden`` exception getting thrown.
+
+ For example, a 200 from the API call and a ``True`` result from
+ ``oslo.policy`` or a 403 from the API call and a ``False`` result from
+ ``oslo.policy`` are successful results.
+
+-------------------------------
+The RBAC Rule Validation Module
+-------------------------------
+
+High-level module that implements decorator inside which the "Expected" stage
+is initiated.
+
+.. automodule:: patrole_tempest_plugin.rbac_rule_validation
+ :members:
+
+---------------------------
+The Policy Authority Module
+---------------------------
+
+Using the Policy Authority Module, policy verification is performed by:
+
+1. Pooling together the default `in-code` policy rules.
+2. Overriding the defaults with custom policy rules located in a policy.json,
+ if the policy file exists and the custom policy definition is explicitly
+ defined therein.
+3. Confirming that the policy action -- for example, "list_users" -- exists.
+ (``oslo.policy`` otherwise claims that role "foo" is allowed to
+ perform policy action "bar", for example, because it defers to the
+ "default" policy rule and oftentimes the default can be "anyone allowed").
+4. Performing a call with all necessary data to ``oslo.policy`` and returning
+ the expected result back to ``rbac_rule_validation`` decorator.
+
+.. automodule:: patrole_tempest_plugin.policy_authority
+ :members:
+ :special-members: