Role-Based Access Control (RBAC) is used by most OpenStack services to control user access to resources. Authorization is granted if a user has the necessary role to perform an action. Patrole is concerned with validating that each of these resources can be accessed by authorized users and cannot be accessed by unauthorized users.
OpenStack services use oslo.policy as the library for RBAC authorization. Patrole relies on the same library for deriving expected test results.
Services publish their policy-to-API mapping via policy in code documentation. This mapping includes the list of APIs that authorize a policy, for each policy declared within a service.
For example, Nova’s policy in code documentation is located in the
Nova repository under nova/policies
. Likewise, Keystone’s policy in
code documentation is located in the Keystone repository under
keystone/common/policies
. The other OpenStack services follow the same
directory layout pattern with respect to policy in code.
The policy in code governance goal enumerates many advantages with following this RBAC design approach. A so-called library of in-code policies offers the following advantages, with respect to facilitating validation:
By default, Patrole validates default OpenStack policies. This is so that 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.
Operators can override policy in code defaults using policy.yaml. While this allows operators to offer more fine-grained RBAC control to their tenants, it opens the door to misconfiguration and bugs. Patrole can be used to validate that custom policy overrides don’t break anything and work as expected.
While testing default policy behavior is a valid use case, oftentimes default policies are modified with custom overrides in production. OpenStack’s policy.yaml documentation claims that “modifying policy can have unexpected side effects”, which is why Patrole was created: to ensure that custom overrides allow the principle of least privilege to be tailor-made to exact specifications via policy overrides, without:
This has implications on Patrole’s Design Principles: validating custom overrides requires the ability to handle arbitrary roles, which requires logic capable of dynamically determining expected test behavior. See RBAC Rule Validation Module for more details.
Note that support for custom policies is limited. This is because custom policies can be arbitrarily complex, requiring that tests be very robust in order to handle all edge cases.
Behind the scenes, many APIs enforce multiple policies, for many reasons, including:
This makes policy in code especially important for policy validation: it is difficult to keep track of all the policies being enforced across all the individual APIs, without policy in code documentation.
Patrole offers support for validating APIs that enforce multiple policies. Perhaps in an ideal world each API endpoint would enforce only one policy, but in reality some API endpoints enforce multiple policies. Thus, to offer accurate validation, Patrole handles multiple policies:
Most OpenStack services raise a 403 Forbidden
following failed
hard authorization. Neutron, however, can raise a 404 NotFound
as well. See Neutron’s authorization policy enforcement documentation
for more details.
The following nomenclature is used throughout Patrole documentation so it is important to understand what each term means in order to understand concepts related to RBAC in Patrole.
oslo.policy
determining whether a user can perform a
policy given his or her role.The do_raise flag controls whether policy authorization should result
in an exception getting raised or a boolean value getting returned.
Hard authorization results in an exception getting raised. Usually, this
results in a 403 Forbidden
getting returned for unauthorized requests.
(See Error Codes for further details.)
Related term: soft authorization.
Registers default OpenStack policies for a service in the service’s code base.
Beginning with the Queens release, policy in code became a governance goal.
The do_raise flag controls whether policy authorization should result in an exception getting raised or a boolean value getting returned. Soft authorization results in a boolean value getting returned. When policy authorization evaluates to true, additional operations are performed as a part of the API request or additional information is included in the response body (see response filtering for an example).
Related term: hard authorization.
Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.