From 8ace3dc13e86229cd9802cf173428122c06ad45b Mon Sep 17 00:00:00 2001 From: Lance Bragstad Date: Fri, 1 Sep 2017 22:04:21 +0000 Subject: [PATCH] Propose specification to include policy scope This specification details the benefits of including scope in policy operations. Change-Id: I36847d9dbeb78aa5b8feff0692ba81847c6f9f6a --- specs/queens/include-scope-in-policy.rst | 225 +++++++++++++++++++++++ 1 file changed, 225 insertions(+) create mode 100644 specs/queens/include-scope-in-policy.rst diff --git a/specs/queens/include-scope-in-policy.rst b/specs/queens/include-scope-in-policy.rst new file mode 100644 index 0000000..3cca09e --- /dev/null +++ b/specs/queens/include-scope-in-policy.rst @@ -0,0 +1,225 @@ +=================== +Add Scope to Policy +=================== + +https://blueprints.launchpad.net/oslo?searchtext=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 +upgrades. + +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 +specifications: + +* `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 +code. + +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 + + ... + + policy.DocumentedRuleDefault( + name=SERVERS % 'create', + check_str=RULE_ADMIN_OR_OWNER, + description='Create a server.', + operations=[ + {'method': 'POST', + 'path': '/servers'} + ] + ) + + ... + + + policy.DocumentedRuleDefault( + name=base.IDENTITY % 'create_user', + check_str=base.RULE_ADMIN_REQUIRED, + description='Create a user.', + operations=[ + {'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 + + ... + + policy.DocumentedRuleDefault( + name=SERVERS % 'create', + scope_type=['project'], + check_str=RULE_ADMIN_OR_OWNER, + description='Create a server.', + operations=[ + {'method': 'POST', + 'path': '/servers'} + ] + ) + + ... + + + policy.DocumentedRuleDefault( + name=base.IDENTITY % 'create_user', + scope_type=['system', 'project'], + check_str=base.RULE_ADMIN_REQUIRED, + description='Create a user.', + operations=[ + {'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. + +Alternatives +------------ + +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 +------------------ + +None. + +Configuration Impact +-------------------- + +None. + +Developer Impact +---------------- + +None. + +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. + +Implementation +============== + +Assignee(s) +----------- + +Primary assignee: + Lance Bragstad lbragstad + +Milestones +---------- + +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. + +Dependencies +============ + +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. + +References +========== + +None. + + +.. note:: + + This work is licensed under a Creative Commons Attribution 3.0 + Unported License. + http://creativecommons.org/licenses/by/3.0/legalcode +