Browse Source

Propose specification to include policy scope

This specification details the benefits of including scope in policy

Change-Id: I36847d9dbeb78aa5b8feff0692ba81847c6f9f6a
Lance Bragstad 2 years ago
1 changed files with 225 additions and 0 deletions
  1. 225

+ 225
- 0
specs/queens/include-scope-in-policy.rst View File

@@ -0,0 +1,225 @@
Add Scope to Policy

This specification details the benefits and outlines the work required to
extend oslo.policy to include a scope attribute.

Problem description

There are several initiatives underway to make consuming and understanding role
based access control (RBAC) easier for developers and deployers.

The first is a community-wide `goal
<>`_ to
register all policies into code and treat them like we we treat configuration.
This has numerous benefits for deployers and eases maintenance, especially

The second is the ability to introduce a scope that fits naturally with
system-level policies or operations. The main idea here is that today
OpenStack's Identity service allows users to get authorization on the domain
and project levels. This makes a lot of sense when dealing with APIs that act
on resources owned by projects or domains. When dealing with operations above
project scope (e.g. modifying endpoints or listing hypervisors), it gets
harder to repurpose project or even domain scope for these actions. This
usually leads to end-user and deployer confusion. In addition to confusion, it
makes it really hard for operators to properly isolate project operations from
system operations (see `bug 968696 <>`_).
As a result, there is work to introduce elevated scopes in OpenStack that make
the solution to the problem a little easier to understand and implement. For
more information on the actual approach, please see the related Identity

* `A roadmap for improving security through policy <>`_
* `Specification for system-level scope <>`_

If the above approaches are accepted, documenting the scope of each operation
in a project will be required. We can leverage the oslo.policy library to do
this since the community already leans on the library to document and register
default policies in code.

Use Cases

As an operator, I need to understand at which level an operation is applied.

As a developer, I want to enforce the scope for a specific operation through

Proposed change

The oslo.policy library currently has a ``DocumentedRuleDefault`` object that
is used to register policy in code and document it. We can extend this object
to support an additional attribute that denotes the scope of the operation.
Consider the following two examples::

from oslo_policy import policy


name=SERVERS % 'create',
description='Create a server.',
{'method': 'POST',
'path': '/servers'}


name=base.IDENTITY % 'create_user',
description='Create a user.',
{'method': 'POST',
'path': '/v3/users'}

Both rules are descriptive in what they do, but they don't include the scope at
which they are intended to operate. Instances must belong to a project and user
can exist globally or within a specific domain. The following representations
are better because they are easier to understand and they help enforce
necessary scope during policy enforcement::

from oslo_policy import policy


name=SERVERS % 'create',
description='Create a server.',
{'method': 'POST',
'path': '/servers'}


name=base.IDENTITY % 'create_user',
scope_type=['system', 'project'],
description='Create a user.',
{'method': 'POST',
'path': '/v3/users'}

The ``scope_type`` attribute of policy can then be generated in sample policy
files with the existing ``description`` making it even more helpful for
deployers that need to understand policy. It can also be available during the
policy enforcement of an operation at runtime. This makes it easier for
oslo.policy enforcement to ensure the operation being performed matches the
scope of the authorization context of the token. For example, comparing the
``scope_type`` of the policy operation against the role on the token's scope
should help solve `admin-ness issues <>`_
across OpenStack.


We can document the scope of operations outside of the project, but doing it
in-code with policy registration makes the approach less error-prone.

Impact on Existing APIs

This will make the ``DocumentedRuleDefault`` object more useful in documenting
and evaluating policy. The changes described here are additive only and should
not impact existing functionality of the object.

Security impact

Directly, there are no security implications of this. Down the road, after
projects start using the attribute to evaluate policy, security will improve.
See the previously linked `Identity specification
<>`_ for details.

Performance Impact


Configuration Impact


Developer Impact


Testing Impact

We should test that scope is actually advertised and set on policies. We should
also loop-in the `Patrole team <>`_
to see how this can improve testing of RBAC across OpenStack.



Primary assignee:
Lance Bragstad <> lbragstad


Target Milestone for completion: queens-1

Making this available early in the Queens release will allow projects to supply
scope documentation through automated docs.

Work Items

* Extend the ``DocumentedRuleDefault`` object to support a ``scope`` attribute

Documentation Impact

This functionality will need extensive documentation and usage guides
describing how it improves policy documentation and evaluation.


Projects must move policy into code and document it before associating scope to
specific policies. Keystone will also need to provide a way for users to get
system-scoped tokens. After that, projects can start enforcing policy scope by
comparing it to the token scope, but most of that will be handled automatically
by oslo.policy's ``Enforcer`` object.



.. note::

This work is licensed under a Creative Commons Attribution 3.0
Unported License.