summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAkihiro Motoki <amotoki@gmail.com>2019-01-07 19:10:03 +0900
committerAkihiro Motoki <amotoki@gmail.com>2019-01-10 18:21:07 +0900
commit4aa79ae4a5414fff698b471390eedc4557b36162 (patch)
tree94e6c2a0c91b01e36a26e5c49e6d8fb0604c2edc
parent15c782b5a12ea2f09750bdf061a25f81d2c9f135 (diff)
Guideline on defining in-code policies
Notes
Notes (review): Code-Review+2: Slawek Kaplonski <skaplons@redhat.com> Code-Review+2: Hongbin Lu <hongbin.lu@huawei.com> Workflow+1: Hongbin Lu <hongbin.lu@huawei.com> Verified+2: Zuul Submitted-by: Zuul Submitted-at: Fri, 11 Jan 2019 02:30:41 +0000 Reviewed-on: https://review.openstack.org/628928 Project: openstack/neutron Branch: refs/heads/master
-rw-r--r--doc/source/contributor/internals/policy.rst74
1 files changed, 64 insertions, 10 deletions
diff --git a/doc/source/contributor/internals/policy.rst b/doc/source/contributor/internals/policy.rst
index d766ad9..643e0ad 100644
--- a/doc/source/contributor/internals/policy.rst
+++ b/doc/source/contributor/internals/policy.rst
@@ -93,19 +93,21 @@ built in the following way:
93 create a rule matching policy names in the form 93 create a rule matching policy names in the form
94 ``<operation>_<resource>:<attribute>`` rule, and link it with the 94 ``<operation>_<resource>:<attribute>`` rule, and link it with the
95 previous rule with an 'And' relationship (using ``oslo_policy.AndCheck``); 95 previous rule with an 'And' relationship (using ``oslo_policy.AndCheck``);
96 this step will be performed only if the enforce_policy flag is set to 96 this step will be performed only if the ``enforce_policy`` flag is set to
97 True in the resource attribute descriptor (usually found in a data 97 ``True`` in the resource attribute descriptor (usually found in a data
98 structure called ``RESOURCE_ATTRIBUTE_MAP``); 98 structure called ``RESOURCE_ATTRIBUTE_MAP``);
99* If the attribute is a composite one then further rules will be created; 99* If the attribute is a composite one then further rules will be created;
100 These will match policy names in the form ``<operation>_<resource>: 100 These will match policy names in the form
101 <attribute>:<sub_attribute>``. An 'And' relationship will be used in this 101 ``<operation>_<resource>:<attribute>:<sub_attribute>``.
102 case too. 102 An 'And' relationship will be used in this case too.
103 103
104As all the rules to verify are linked by 'And' relationships, all the policy 104As all the rules to verify are linked by 'And' relationships, all the policy
105checks should succeed in order for a request to be authorized. Rule 105checks should succeed in order for a request to be authorized. Rule
106verification is performed by ``oslo_policy`` with no "customization" from the 106verification is performed by ``oslo_policy`` with no "customization" from the
107Neutron side. 107Neutron side.
108 108
109.. _response_filtering:
110
109Response Filtering 111Response Filtering
110~~~~~~~~~~~~~~~~~~ 112~~~~~~~~~~~~~~~~~~
111 113
@@ -193,7 +195,7 @@ The check, performed in the ``__call__`` method, works as follows:
193* verify if the target field is already in the target data. If yes, then 195* verify if the target field is already in the target data. If yes, then
194 simply verify whether the value for the target field in target data 196 simply verify whether the value for the target field in target data
195 is equal to value for the same field in credentials, just like 197 is equal to value for the same field in credentials, just like
196 ``oslo_policy.GeneriCheck`` would do. This is also the most frequent case 198 ``oslo_policy.GenericCheck`` would do. This is also the most frequent case
197 as the target field is usually ``tenant_id``; 199 as the target field is usually ``tenant_id``;
198* if the previous check failed, extract a parent resource type and a 200* if the previous check failed, extract a parent resource type and a
199 parent field name from the target field. For instance 201 parent field name from the target field. For instance
@@ -234,8 +236,8 @@ to ``<value>`` or return ``False`` is the ``<field>`` either is not equal to
234``<value>`` or does not exist at all. 236``<value>`` or does not exist at all.
235 237
236 238
237Guidance for API developers 239Guidance for Neutron API developers
238--------------------------- 240-----------------------------------
239 241
240When developing REST APIs for Neutron it is important to be aware of how the 242When developing REST APIs for Neutron it is important to be aware of how the
241policy engine will authorize these requests. This is true both for APIs 243policy engine will authorize these requests. This is true both for APIs
@@ -274,9 +276,8 @@ served by Neutron "core" and for the APIs served by the various Neutron
274 inconsistent state if a request is not authorized after it has already 276 inconsistent state if a request is not authorized after it has already
275 been dispatched to the backend. 277 been dispatched to the backend.
276 278
277
278Notes 279Notes
279----- 280~~~~~
280 281
281* No authorization checks are performed for requests coming from the RPC over 282* No authorization checks are performed for requests coming from the RPC over
282 AMQP channel. For all these requests a neutron admin context is built, and 283 AMQP channel. For all these requests a neutron admin context is built, and
@@ -303,6 +304,56 @@ Notes
303Policy-in-Code support 304Policy-in-Code support
304---------------------- 305----------------------
305 306
307Guideline on defining in-code policies
308~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
309
310The following is the guideline of policy definitions.
311
312Ideally we should define all available policies, but in the neutron policy
313enforcement it is not practical to define all policies because we check
314all attributes of a target resource in the :ref:`response_filtering`.
315Considering this, we have the special guidelines for "get" operation.
316
317* All policies of ``<action>_<resource>`` must be defined
318 for all types of operations.
319 Valid actions are ``create``, ``update``, ``delete`` and ``get``.
320
321* ``get_<resourceS>`` (get plural) is unnecessary.
322 The neutron API layer use a single form policy ``get_<resource>``
323 when listing resources [#]_ [#]_.
324
325* Member actions for individual resources must be defined.
326 For example, ``add_router_interface`` of ``router`` resource.
327
328* All policies with attributes on "create", "update" and "delete" actions must
329 be defined. ``<action>_<resource>:<attribute>(:<sub_attribute>)`` policy is
330 required for attributes with ``enforce_policy`` in the API definitions.
331 Note that it is recommended to define even if a rule is same as for
332 ``<action>_<resource>`` from the documentation perspective.
333
334* For a policy with attributes of "get" actions like
335 ``get_<resource>:<attribute>(:<sub_attribute>)``,
336 the following guideline is applied:
337
338 * A policy with an attribute must be defined if the policy is different from
339 the policy for ``get_<resource>`` (without attributes).
340 * If a policy with an attribute is same as for ``get_<resource>``, there is
341 no need to define it explicitly.
342 This is for simplicity. We check all attributes of a target resource
343 in the process of :ref:`response_filtering` so it leads to a long long
344 policy definitions for "get" actions in our documentation.
345 It is not happy for operators either.
346 * If an attribute is marked as ``enforce_policy``, it is recommended to
347 define the corresponding policy with the attribute.
348 This is for clarification. If an attribute is marked as ``enforce_policy``
349 in the API definitions, for example, the neutron API limits to set such
350 attribute only to admin users but allows to retrieve a value for regular
351 users. If policies for the attribute are different across the types of
352 operations, it is better to define all of them explicitly.
353
354Registering policies in neutron related projects
355~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
356
306Policy-in-code support in neutron is a bit different from other projects 357Policy-in-code support in neutron is a bit different from other projects
307because the neutron server needs to load policies in code from multiple 358because the neutron server needs to load policies in code from multiple
308projects. Each neutron related project should register the following two entry 359projects. Each neutron related project should register the following two entry
@@ -362,5 +413,8 @@ References
362 413
363.. _reset: http://git.openstack.org/cgit/openstack/neutron/tree/neutron/api/v2/router.py?id=2015.1.1#n122 414.. _reset: http://git.openstack.org/cgit/openstack/neutron/tree/neutron/api/v2/router.py?id=2015.1.1#n122
364 415
416.. [#] https://github.com/openstack/neutron/blob/051b6b40f3921b9db4f152a54f402c402cbf138c/neutron/pecan_wsgi/hooks/policy_enforcement.py#L173
417.. [#] https://github.com/openstack/neutron/blob/051b6b40f3921b9db4f152a54f402c402cbf138c/neutron/pecan_wsgi/hooks/policy_enforcement.py#L143
418
365.. [#] https://docs.openstack.org/oslo.policy/latest/user/usage.html#sample-file-generation 419.. [#] https://docs.openstack.org/oslo.policy/latest/user/usage.html#sample-file-generation
366.. [#] https://docs.openstack.org/oslo.policy/latest/cli/index.html#oslopolicy-sample-generator 420.. [#] https://docs.openstack.org/oslo.policy/latest/cli/index.html#oslopolicy-sample-generator