Merge "Docs: Add RBAC overview documentation"

This commit is contained in:
Zuul 2018-07-24 06:35:17 +00:00 committed by Gerrit Code Review
commit e737900e60
3 changed files with 267 additions and 0 deletions

View File

@ -31,6 +31,8 @@ documentation.
* Bugs: https://bugs.launchpad.net/patrole
* Release notes: https://docs.openstack.org/releasenotes/patrole/
.. _design-principles:
Design Principles
-----------------
@ -59,6 +61,9 @@ but not all, as its testing scope is confined to policies.
Realistically this is not always possible because some services have
not yet moved to policy in code.
* *Customizable*. Patrole should be able to validate custom policy overrides to
ensure that those overrides enhance rather than undermine the cloud's RBAC
configuration. In addition, Patrole should be able to validate any role.
* *Self-cleaning*. Patrole should attempt to clean up after itself; whenever
possible we should tear down resources when done.

View File

@ -10,6 +10,14 @@ Overview
overview
RBAC Overview
-------------
.. toctree::
:maxdepth: 2
rbac-overview
User's Guide
============

View File

@ -0,0 +1,254 @@
==================================
Role-Based Access Control Overview
==================================
Introduction
------------
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.
.. _policy-in-code:
Policy in Code
--------------
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:
* includes every policy enforced by an OpenStack service, enabling the
possibility of complete Patrole test coverage for that service (otherwise
one has to read the source code to discover all the policies)
* provides the policy-to-API mapping for each policy which can be used
to write correct Patrole tests (otherwise reading source code and
experimentation are required to derive this mapping)
* by extension, the policy-to-API mapping facilitates writing multi-policy
Patrole tests (otherwise even more experimentation and code reading is
required to arrive at all the policies enforced by an API)
* policy in code documentation includes additional information, like
descriptions and (in the case of some services, like Keystone)
`scope types`_, which help with understanding how to correctly write
Patrole tests
* by extension, such information helps to determine whether a Patrole test
should assume :term:`hard authorization` or :term:`soft authorization`
Policy in Code (Default) 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.
.. _custom-policies:
Custom Policies
---------------
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.
Custom Policy Validation
^^^^^^^^^^^^^^^^^^^^^^^^
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:
* causing unintended side effects (breaking API endpoints, breaking
cross-service workflows, breaking the policy file itself); or
* resulting in poor RBAC configuration, promoting security vulnerabilities
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.
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.
.. _multiple-policies:
Multiple Policies
-----------------
Behind the scenes, many APIs enforce multiple policies, for many reasons,
including:
* to control complex cross-service workflows;
* to control whether a server is booted from an image or booted from a volume
(for example);
* to control whether a response body should contain additional information
conditioned upon successful policy authorization.
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.
Multi-Policy Validation
^^^^^^^^^^^^^^^^^^^^^^^
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:
* for services *with* policy in code documentation: this documentation
indicates that a single API endpoint enforces multiple policy actions.
* for services *without* policy in code documentation: the API code clearly
shows multiple policy actions being validated. Note that in this case some
degree of log tracing is required by developers to confirm that the expected
policies are getting enforced, prior to the tests getting merged.
.. todo::
Link to multi-policy validation documentation section once it has been
written.
.. _error-codes:
Error Codes
-----------
Most OpenStack services raise a ``403 Forbidden`` following failed
:term:`hard authorization`. Neutron, however, can raise a ``404 NotFound``
as well. See Neutron's `authorization policy enforcement`_ documentation
for more details.
Glossary
--------
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.
.. glossary::
authorize
The act of ``oslo.policy`` determining whether a user can perform a
:term:`policy` given his or her :term:`role`.
enforce
See :term:`authorize`.
hard authorization
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 :ref:`error-codes` for further details.)
Related term: :term:`soft authorization`.
oslo.policy
The OpenStack library providing support for RBAC policy enforcement across
all OpenStack services. See the `official documentation`_ for more
information.
policy
Defines an RBAC rule. Each policy is defined by a one-line statement in
the form "<target>" : "<rule>". For more information, reference OpenStack's
`policy documentation`_.
policy action
See :term:`policy target`.
policy file
Prior to `governance goal`_ used by all OpenStack services to define
policy defaults. Still used by some services, which is why Patrole
needs to read the policy files to derive policy information for testing.
policy in code
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`_.
policy rule
The policy rule determines under which circumstances the API call is
permitted.
policy target
The name of a policy.
requirements file
Requirements-driven approach to declaring the expected RBAC test results
referenced by Patrole. Uses a high-level YAML syntax to crystallize policy
requirements concisely and unambiguously. See :ref:`requirements-authority`
for more information.
role
A designation for the set of actions that describe what a user can do in
the system. Roles are managed through the `Keystone Roles API`_.
Role-Based Access Control (RBAC)
May be formally defined as "an approach to restricting system access to
authorized users."
rule
See :term:`policy rule`. Note that currently the Patrole code base
conflates "rule" with :term:`policy target` in some places.
soft authorization
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: :term:`hard authorization`.
.. _Nova repository: https://github.com/openstack/nova/tree/master/nova/policies
.. _Keystone repository: https://github.com/openstack/keystone/tree/master/keystone/common/policies
.. _governance goal: https://governance.openstack.org/tc/goals/queens/policy-in-code.html
.. _scope types: https://docs.openstack.org/keystone/latest/admin/identity-tokens.html#authorization-scopes
.. _policy.yaml: https://docs.openstack.org/ocata/config-reference/policy-yaml-file.html
.. _oslo.policy: https://docs.openstack.org/oslo.policy/latest/
.. _policy documentation: https://docs.openstack.org/kilo/config-reference/content/policy-json-file.html
.. _do_raise: https://docs.openstack.org/oslo.policy/latest/reference/api/oslo_policy.policy.html#oslo_policy.policy.Enforcer.enforce
.. _authorization policy enforcement: https://docs.openstack.org/neutron/latest/contributor/internals/policy.html
.. _official documentation: https://docs.openstack.org/oslo.policy/latest/
.. _Keystone Roles API: https://developer.openstack.org/api-ref/identity/v3/#roles
.. _response filtering: https://docs.openstack.org/neutron/latest/contributor/internals/policy.html#response-filtering