Stable Interface¶

Patrole offers a stable interface that is guaranteed to be backwards compatible and can be directly consumed by other projects. Currently, rbac_exceptions.py and rbac_policy_parser.py are guaranteed to be stable.

Release Versioning¶

Patrole Release Notes show what changes have been released.

Test Flows¶

There are several possible test flows.

If the rbac_test_role is allowed to access the endpoint:

• The test passes if no 403 Forbidden or RbacActionFailed exception is raised.

If the rbac_test_role is not allowed to access the endpoint:

• If the endpoint returns a 403 Forbidden exception the test will pass.
• If the endpoint returns successfully, then the test will fail with an RbacOverPermission exception.
• If the endpoint returns something other than a 403 Forbidden to indicate that the role is not allowed, the test will raise an RbacActionFailed exception.

Test Execution Workflow¶

The workflow is as follows:

1. Each test uses the rbac_rule_validation.action decorator, like below:

   @rbac_rule_validation.action(
       service="nova",
       rule="os_compute_api:servers:stop")
   @decorators.idempotent_id('ab4a17d2-166f-4a6d-9944-f17baa576cf2')
   def test_stop_server(self):
       # Set the primary credential's role to "rbac_test_role".
       self.rbac_utils.switch_role(self, toggle_rbac_role=True)
       # Call the API that enforces the policy action specified by "rule".
       self._test_stop_server()
   

   The service attribute accepts an OpenStack service and the rule attribute accepts a valid OpenStack policy action, like “os_compute_api:servers:stop”.

2. The rbac_rule_validation.action decorator passes these attributes, along with user_id and project_id information derived from the primary Tempest credential (self.os.credentials.user_id and self.os.credentials.project_id), to the rbac_policy_parser.

3. The logic in rbac_policy_parser then passes all this information along and the role in CONF.rbac.rbac_test_role to oslo_policy to determine whether the rbac_test_role is authorized to perform the policy action for the given service.

4. After all of the logic above has executed inside the rbac decorator, the test is executed. The test then sets up test-level resources, if necessary, with admin credentials implicitly. This is accomplished through rbac_utils.switch_role(toggle_rbac_role=False), which is done as part of client setup (inside the call to rbac_utils.RbacUtils):

   @classmethod
   def setup_clients(cls):
       super(BaseV2ComputeRbacTest, cls).setup_clients()
       cls.auth_provider = cls.os_primary.auth_provider
       cls.rbac_utils = rbac_utils.RbacUtils(cls)
       ...
   

   This code has already executed when the test class is instantiated, because it is located in the base rbac test class. Whenever cls.rbac_utils.switch_role is called, one of two behaviors are possible:

   1. The primary credential’s role is changed to admin if toggle_rbac_role=False
   2. The primary credential’s role is changed to rbac_test_role if toggle_rbac_role=True

   Thus, at the beginning of every test and during resource_setup and resource_cleanup, the primary credential has the admin role.

5. After preliminary test-level setup is performed, like creating a server, a second call to self.rbac_utils.switch_role is done:

   self.rbac_utils.switch_role(cls, toggle_rbac_role=True)
   

   Now the primary credential has the role specified by rbac_test_role.

6. The API endpoint in which policy enforcement of “os_compute_api:servers:stop” is performed can now be called.

7. Now that a call is made to “stop_server” with the primary credentials having the role specified by rbac_test_role, either the nova contoller will allow or disallow the action to be performed. Since the “stop_server” policy action in nova is defined as “base.RULE_ADMIN_OR_OWNER”, the API will most likely return a successful status code. For more information about this policy action, see https://github.com/openstack/nova/blob/master/nova/policies/servers.py.

8. As mentioned above, the result from the API call and the result from oslo_policy are compared for consistency.

9. Finally, after the test has executed, but before tearDown or resource_cleanup is called, self.rbac_utils.switch_role(cls, toggle_rbac_role=False) is called, so that the primary credential yet again has admin permissions for test clean up. This call is always performed in the “finally” block inside the rbac_rule_validation decorator.