Browse Source

Merge "Guideline on defining in-code policies"

tags/14.0.0.0b2
Zuul 5 months ago
parent
commit
5daebbc561
1 changed files with 64 additions and 10 deletions
  1. 64
    10
      doc/source/contributor/internals/policy.rst

+ 64
- 10
doc/source/contributor/internals/policy.rst View File

@@ -93,19 +93,21 @@ built in the following way:
93 93
   create a rule matching policy names in the form
94 94
   ``<operation>_<resource>:<attribute>`` rule, and link it with the
95 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
97
-  True in the resource attribute descriptor (usually found in a data
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
98 98
   structure called ``RESOURCE_ATTRIBUTE_MAP``);
99 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>:
101
-  <attribute>:<sub_attribute>``. An 'And' relationship will be used in this
102
-  case too.
100
+  These will match policy names in the form
101
+  ``<operation>_<resource>:<attribute>:<sub_attribute>``.
102
+  An 'And' relationship will be used in this case too.
103 103
 
104 104
 As all the rules to verify are linked by 'And' relationships, all the policy
105 105
 checks should succeed in order for a request to be authorized. Rule
106 106
 verification is performed by ``oslo_policy`` with no "customization" from the
107 107
 Neutron side.
108 108
 
109
+.. _response_filtering:
110
+
109 111
 Response Filtering
110 112
 ~~~~~~~~~~~~~~~~~~
111 113
 
@@ -193,7 +195,7 @@ The check, performed in the ``__call__`` method, works as follows:
193 195
 * verify if the target field is already in the target data. If yes, then
194 196
   simply verify whether the value for the target field in target data
195 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 199
   as the target field is usually ``tenant_id``;
198 200
 * if the previous check failed, extract a parent resource type and a
199 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 236
 ``<value>`` or does not exist at all.
235 237
 
236 238
 
237
-Guidance for API developers
238
----------------------------
239
+Guidance for Neutron API developers
240
+-----------------------------------
239 241
 
240 242
 When developing REST APIs for Neutron it is important to be aware of how the
241 243
 policy 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 276
   inconsistent state if a request is not authorized after it has already
275 277
   been dispatched to the backend.
276 278
 
277
-
278 279
 Notes
279
------
280
+~~~~~
280 281
 
281 282
 * No authorization checks are performed for requests coming from the RPC over
282 283
   AMQP channel. For all these requests a neutron admin context is built, and
@@ -303,6 +304,56 @@ Notes
303 304
 Policy-in-Code support
304 305
 ----------------------
305 306
 
307
+Guideline on defining in-code policies
308
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
309
+
310
+The following is the guideline of policy definitions.
311
+
312
+Ideally we should define all available policies, but in the neutron policy
313
+enforcement it is not practical to define all policies because we check
314
+all attributes of a target resource in the :ref:`response_filtering`.
315
+Considering 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
+
354
+Registering policies in neutron related projects
355
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
356
+
306 357
 Policy-in-code support in neutron is a bit different from other projects
307 358
 because the neutron server needs to load policies in code from multiple
308 359
 projects. Each neutron related project should register the following two entry
@@ -362,5 +413,8 @@ References
362 413
 
363 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 419
 .. [#] https://docs.openstack.org/oslo.policy/latest/user/usage.html#sample-file-generation
366 420
 .. [#] https://docs.openstack.org/oslo.policy/latest/cli/index.html#oslopolicy-sample-generator

Loading…
Cancel
Save