Debian Codegraph @

doc/source/user/usage.rst

raw
1 =======
2 Usage
3 =======
4
5 To use oslo.policy in a project, import the relevant module. For
6 example::
7
8 from oslo_policy import policy
9
10 Migrating to oslo.policy
11 ========================
12
13 Applications using the incubated version of the policy code from Oslo aside
14 from changing the way the library is imported, may need to make some extra
15 changes.
16
17 Incorporating oslo.policy tooling
18 ---------------------------------
19
20 The ``oslo.policy`` library offers a generator that projects can use to render
21 sample policy files, check for redundant rules or policies, among other things.
22 This is a useful tool not only for operators managing policies but also for
23 developers looking to automate documentation describing projects' default
24 policies.
25
26 This part of the document describes how you can incorporate these features into
27 your project. Let's assume we're working on an OpenStack-like project called
28 ``foo``. Policies for this service are registered in code in a common module of
29 the project.
30
31 First, you'll need to expose a couple of entry points in the project's
32 ``setup.cfg``::
33
34 [entry_points]
35 oslo.policy.policies =
36 foo = foo.common.policies:list_rules
37
38 oslo.policy.enforcer =
39 foo = foo.common.policy:get_enforcer
40
41 The ``oslo.policy`` library uses the project namespace to call ``list_rules``,
42 which should return a list of ``oslo.policy`` objects, instances of either
43 ``RuleDefault`` or ``DocumentedRuleDefault``.
44
45 The second entry point allows ``oslo.policy`` to generate complete policy from
46 overrides supplied by an existing policy file on disk. This is useful for
47 operators looking to supply a policy file to Horizon or for security compliance
48 complete with overrides important to that deployment. The ``get_enforcer``
49 method should return an instance of ``oslo.policy.policy:Enforcer``. The
50 information passed into the constructor of ``Enforcer`` should resolve any
51 overrides on disk. An example for project ``foo`` might look like the
52 following::
53
54 from oslo_config import cfg
55 from oslo_policy import policy
56
57 from foo.common import policies
58
59 CONF = cfg.CONF
60 _ENFORCER = None
61
62 def get_enforcer():
63 CONF([], project='foo')
64 global _ENFORCER
65 if not _ENFORCER:
66 _ENFORCER = policy.Enforcer(CONF)
67 _ENFORCER.register_defaults(policies.list_rules())
68 return _ENFORCER
69
70 Please note that if you're incorporating this into a project that already uses
71 ``oslo.policy`` in some form or fashion, this might need to be changed to fit
72 that project's structure accordingly.
73
74 Next, you can create a configuration file for generating policies specifically
75 for project ``foo``. This file could be called ``foo-policy-generator.conf``
76 and it can be kept under version control within the project::
77
78 [DEFAULT]
79 output_file = etc/foo/policy.yaml.sample
80 namespace = foo
81
82 If project ``foo`` uses tox, this makes it easier to create a specific tox
83 environment for generating sample configuration files in ``tox.ini``::
84
85 [testenv:genpolicy]
86 commands = oslopolicy-sample-generator --config-file etc/foo/foo-policy-generator.conf
87
88 Changes to Enforcer Initialization
89 ----------------------------------
90
91 The ``oslo.policy`` library no longer assumes a global configuration object is
92 available. Instead the :py:class:`oslo_policy.policy.Enforcer` class has been
93 changed to expect the consuming application to pass in an ``oslo.config``
94 configuration object.
95
96 When using policy from oslo-incubator
97 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
98
99 ::
100
101 enforcer = policy.Enforcer(policy_file=_POLICY_PATH)
102
103 When using oslo.policy
104 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
105
106 ::
107
108 from oslo_config import cfg
109 CONF = cfg.CONF
110 enforcer = policy.Enforcer(CONF, policy_file=_POLICY_PATH)
111
112 Registering policy defaults in code
113 ===================================
114
115 A project can register policy defaults in their code which brings with it some
116 benefits.
117
118 * A deployer only needs to add a policy file if they wish to override the
119 project defaults.
120
121 * Projects can use Enforcer.authorize to ensure that a policy check is being
122 done against a registered policy. This can be used to ensure that all
123 policies used are registered. The signature of Enforcer.authorize matches
124 Enforcer.enforce.
125
126 * Projects can register policies as `DocumentedRuleDefault` objects, which
127 require a method and path of the corresponding policy. This helps policy
128 readers understand which path maps to a particular policy ultimately
129 providing better documentation.
130
131 * A sample policy file can be generated based on the registered policies
132 rather than needing to be manually maintained.
133
134 * A policy file can be generated which is a merge of registered defaults and
135 policies loaded from a file. This shows the effective policy in use.
136
137 * A list can be generated which contains policies defined in a file which match
138 defaults registered in code. These are candidates for removal from the file
139 in order to keep it small and understandable.
140
141 How to register
142 ---------------
143
144 ::
145
146 from oslo_config import cfg
147 CONF = cfg.CONF
148 enforcer = policy.Enforcer(CONF, policy_file=_POLICY_PATH)
149
150 base_rules = [
151 policy.RuleDefault('admin_required', 'role:admin or is_admin:1',
152 description='Who is considered an admin'),
153 policy.RuleDefault('service_role', 'role:service',
154 description='service role'),
155 ]
156
157 enforcer.register_defaults(base_rules)
158 enforcer.register_default(policy.RuleDefault('identity:create_region',
159 'rule:admin_required',
160 description='helpful text'))
161
162 To provide more information about the policy, use the `DocumentedRuleDefault`
163 class::
164
165 enforcer.register_default(
166 policy.DocumentedRuleDefault(
167 'identity:create_region',
168 'rule:admin_required',
169 'helpful text',
170 [{'path': '/regions/{region_id}', 'method': 'POST'}]
171 )
172 )
173
174 The `DocumentedRuleDefault` class inherits from the `RuleDefault`
175 implementation, but it must be supplied with the `description` attribute in
176 order to be used. In addition, the `DocumentedRuleDefault` class requires a new
177 `operations` attribute that is a list of dictionaries. Each dictionary must
178 have a `path` and a `method` key. The `path` should map to the path used to
179 interact with the resource the policy protects. The `method` should be the HTTP
180 verb corresponding to the `path`. The list of `operations` can be supplied with
181 multiple dictionaries if the policy is used to protect multiple paths.
182
183 Naming policies
184 ---------------
185
186 Policy names are an integral piece of information in understanding how
187 OpenStack's policy engine works. Developers protect APIs using policy names.
188 Operators use policy names to override policies in their deployment. Having
189 consistent policy names across OpenStack services is essential to providing a
190 pleasant user experience. The following rules are guidelines to help you, as a
191 developer, build unique and descriptive policy names.
192
193 Service types
194 ~~~~~~~~~~~~~
195
196 Policy names should be specific about the service that uses them. The service
197 type should also follow a known standard, which is the `service-types authority
198 <https://service-types.openstack.org/service-types.json>`_. Using an existing
199 standard avoids confusing users by reusing an established reference. For
200 example, instead of using `keystone` as the service in a policy name, you
201 should use `identity`, since it is not specific to one implementation. It's
202 also more specific about the functionality provided by the service instead of
203 having readers maintain a mental mapping between service code name and
204 functionality it provides.
205
206 Resources and subresources
207 ~~~~~~~~~~~~~~~~~~~~~~~~~~
208
209 Users may interact with resources exposed by a service's API. You should
210 include the name of a resource in the policy name, and it should be singular.
211 For example, policies that protect the user API should use `identity:user`,
212 instead of `identity:users`.
213
214 Some services might have subresources. For example, a fixed IP address could be
215 considered a subresource of an IP address. You should separate open-form
216 compound words with a hyphen and not an underscore. This spacing convention
217 maintains consistency with spacing used in the service types authority. For
218 example, use `ip-address` instead of `ip_address`. Having more than one way to
219 separate compound words within a single convention is confusing and prone to
220 accidentally introducing inconsistencies.
221
222 Resource names should be minimalist and contain only characters needed to
223 describe the resource. Extra information should be omitted from the resource
224 altogether. Use `agent` instead of `os-agents`, even if the URL path of the
225 resource uses `/os-agents`.
226
227 Actions and subactions
228 ~~~~~~~~~~~~~~~~~~~~~~
229
230 Actions are specific things that users can do to resources. Typical actions are
231 `create`, `get`, `list`, `update`, and `delete`. These action definitions are
232 independent of the HTTP method used to implement their underlying API, which is
233 intentional. This independence is important because two different services may
234 implement the same action using two different HTTP methods. For example, use
235 `compute:server:list` as a policy name for listing servers instead of
236 `compute:server:get_all` or `compute:server:get-all`. Using `all` in the policy
237 name itself implies returning every possible entity when the actual response
238 may be filtered based on the user's authority. In other words, list servers for
239 a domain administrator managing many different projects within that domain
240 could be very different from a member of a project listing servers owned by a
241 single project.
242
243 Some services have the ability to list resources with greater detail. Depending
244 on the context, those additional details might be sensitive in nature and
245 require more strict RBAC permissions than `list`. In this case, use
246 `compute:server:list-detail` as opposed to `compute:server:detail`. By using a
247 compound word, we're being more descriptive about what the `detail` actually
248 means.
249
250 Subactions are optionally available for you to add clarity about resource
251 actions. For example, `compute:server:resize:confirm` is an example of how you
252 can compound an action (resize) with a subaction (confirm) to explicitly name a
253 policy.
254
255 Actions that are open form compound words should use hyphens instead of
256 underscores for spacing. This spacing is consistent with the service types
257 authority and resource names for open form compound words. For example, use
258 `compute:server:resize-state` instead of `compute:server:resize_state`.
259
260 Resource Attributes
261 ~~~~~~~~~~~~~~~~~~~
262
263 Resource attributes may be used in policy names, and are entirely optional. If
264 you need to include the attribute of a resource in the name, you should place
265 it after the resource or subresource portion. For example, use
266 `compute:flavor:private:list` to name a policy for listing all private flavors.
267
268 Putting it all together
269 ~~~~~~~~~~~~~~~~~~~~~~~
270
271 Now that you know what services types, resources, attributes, and actions are
272 within the context of policy names, it is possible to establish the order you
273 should use them. Policy names should increase in detail as you read it. This
274 results in the following syntax::
275
276 <service-type>:<resource>[:<subresource>][:<attribute>]:<action>[:<subaction>]
277
278 You should delimit each segment of the name with a colon (:). The following are
279 examples for existing OpenStack APIs::
280
281 identity:user:list
282 block-storage:volume:extend
283 compute:server:resize:confirm
284 compute:flavor:private:list
285 network:ip-address:fixed-ip-address:create
286
287 Setting scope
288 -------------
289
290 The `RuleDefault` and `DocumentedRuleDefault` objects have an attribute
291 dedicated to the intended scope of the operation called `scope_types`. This
292 attribute can only be set at rule definition and never overridden via a policy
293 file. This variable is designed to save the scope at which a policy should
294 operate. During enforcement, the information in `scope_types` is compared to
295 the scope of the token used in the request. It is designed to match the
296 available token scopes available from keystone, which are `system`, `domain`,
297 and `project`. The examples highlighted here will show the usage with system
298 and project APIs. Setting `scope_types` to anything but these three values is
299 unsupported.
300
301 For example, a policy that is used to protect a resource tracked in a project
302 should require a project-scoped token. This can be expressed with `scope_types`
303 as follows::
304
305 policy.DocumentedRuleDefault(
306 name='service:create_foo',
307 check_str='role:admin',
308 scope_types=['project'],
309 description='Creates a foo resource',
310 operations=[
311 {
312 'path': '/v1/foos/',
313 'method': 'POST'
314 }
315 ]
316 )
317
318 A policy that is used to protect system-level resources can follow the same
319 pattern::
320
321 policy.DocumentedRuleDefault(
322 name='service:update_bar',
323 check_str='role:admin',
324 scope_types=['system'],
325 description='Updates a bar resource',
326 operations=[
327 {
328 'path': '/v1/bars/{bar_id}',
329 'method': 'PATCH'
330 }
331 ]
332 )
333
334 The `scope_types` attribute makes sure the token used to make the request is
335 scoped properly and passes the `check_str`. This is powerful because it allows
336 roles to be reused across different authorization levels without compromising
337 APIs. For example, the `admin` role in the above example is used at the
338 project-level and the system-level to protect two different resources. If we
339 only checked that the token contained the `admin` role, it would be possible
340 for a user with a project-scoped token to access a system-level API.
341
342 Developers incorporating `scope_types` into OpenStack services should be
343 mindful of the relationship between the API they are protecting with a policy
344 and the resource level the API operates at, whether it's system-level or
345 project-level.
346
347 Sample file generation
348 ----------------------
349
350 In setup.cfg of a project using oslo.policy::
351
352 [entry_points]
353 oslo.policy.policies =
354 nova = nova.policy:list_policies
355
356 where list_policies is a method that returns a list of policy.RuleDefault
357 objects.
358
359 Run the oslopolicy-sample-generator script with some configuration options::
360
361 oslopolicy-sample-generator --namespace nova --output-file policy-sample.yaml
362
363 or::
364
365 oslopolicy-sample-generator --config-file policy-generator.conf
366
367 where policy-generator.conf looks like::
368
369 [DEFAULT]
370 output_file = policy-sample.yaml
371 namespace = nova
372
373 If output_file is omitted the sample file will be sent to stdout.
374
375 Merged file generation
376 ----------------------
377
378 This will output a policy file which includes all registered policy defaults
379 and all policies configured with a policy file. This file shows the effective
380 policy in use by the project.
381
382 In setup.cfg of a project using oslo.policy::
383
384 [entry_points]
385 oslo.policy.enforcer =
386 nova = nova.policy:get_enforcer
387
388 where get_enforcer is a method that returns a configured
389 oslo_policy.policy.Enforcer object. This object should be setup exactly as it
390 is used for actual policy enforcement, if it differs the generated policy file
391 may not match reality.
392
393 Run the oslopolicy-policy-generator script with some configuration options::
394
395 oslopolicy-policy-generator --namespace nova --output-file policy-merged.yaml
396
397 or::
398
399 oslopolicy-policy-generator --config-file policy-merged-generator.conf
400
401 where policy-merged-generator.conf looks like::
402
403 [DEFAULT]
404 output_file = policy-merged.yaml
405 namespace = nova
406
407 If output_file is omitted the file will be sent to stdout.
408
409 List of redundant configuration
410 -------------------------------
411
412 This will output a list of matches for policy rules that are defined in a
413 configuration file where the rule does not differ from a registered default
414 rule. These are rules that can be removed from the policy file with no change
415 in effective policy.
416
417 In setup.cfg of a project using oslo.policy::
418
419 [entry_points]
420 oslo.policy.enforcer =
421 nova = nova.policy:get_enforcer
422
423 where get_enforcer is a method that returns a configured
424 oslo_policy.policy.Enforcer object. This object should be setup exactly as it
425 is used for actual policy enforcement, if it differs the generated policy file
426 may not match reality.
427
428 Run the oslopolicy-list-redundant script::
429
430 oslopolicy-list-redundant --namespace nova
431
432 or::
433
434 oslopolicy-list-redundant --config-file policy-redundant.conf
435
436 where policy-redundant.conf looks like::
437
438 [DEFAULT]
439 namespace = nova
440
441 Output will go to stdout.
442
443 Testing default policies
444 ========================
445
446 Developers need to reliably unit test policies used to protect APIs. Having
447 robust unit test coverage increases confidence that changes won't negatively
448 affect user experience. This document is intended to help you understand
449 historical context behind testing practices you may find in your service. More
450 importantly, it's going to describe testing patterns you can use to increase
451 confidence in policy testing and coverage.
452
453 History
454 -------
455
456 Before the ability to register policies in code, developers maintained policies
457 in a policy file, which included all policies used by the service. Developers
458 maintained policy files within the project source code, which contained the
459 default policies for the service.
460
461 Once it became possible to register policies in code, policy files became
462 irrelevant because you could generate them. Generating policy files from code
463 made maintaining documentation for policies easier and allowed for a single
464 source of truth. Registering policies in code also meant testing no longer
465 required a policy file, since the default policies were in the service itself.
466
467 At this point, it is important to note that policy enforcement requires an
468 authorization context based on the user making the request (e.g., is the user
469 allowed to do the operation they're asking to do). Within OpenStack, this
470 authorization context is relayed to services by the token used to call an API,
471 which comes from an OpenStack identity service. In its purest form, you can
472 think of authorization context as the roles a user has on a project, domain, or
473 system. Services can feed the authorization context into policy enforcement,
474 which determines if a user is allowed to do something.
475
476 The coupling between the authorization context, ultimately the token, and the
477 policy enforcement mechanism raises the bar for effectively testing policies
478 and APIs. Service developers want to ensure the functionality specific to their
479 service works and not dwell on the implementation details of an authorization
480 system. Additionally, they want to keep unit tests lightweight, as opposed to
481 requiring a separate system to issue tokens for authorization, crossing the
482 boundary of unit testing to integration testing.
483
484 Because of this, you typically see one of two approaches taken concerning
485 policies and test code across OpenStack services.
486
487 One approach is to supply a policy file specifically for testing that overrides
488 the sample policy file or default policies in code. This file contains mostly
489 policies without proper check strings, which relaxes the authorization enforced
490 by the service using oslo.policy. Without proper check strings, it's possible
491 to access APIs without building context objects or using tokens from an
492 identity service.
493
494 The other approach is to mock policy enforcement to succeed unconditionally.
495 Since developers are bypassing the code within the policy engine, supplying a
496 proper authorization context doesn't have an impact on the APIs used in the
497 test case.
498
499 Both methods let developers focus on validating the domain-specific
500 functionality of their service without needing to understand the intricacies of
501 policy enforcement. Unfortunately, bypassing API authorization testing comes at
502 the expense of introducing gaps where the default policies may break
503 unexpectedly with new changes. If the tests don't assert the default behavior,
504 it's likely that seemingly simple changes negatively impact users or operators,
505 regardless of that being the intent of the developer.
506
507 Testing policies
508 ----------------
509
510 Fortunately, you can test policies without needing to deal with tokens by using
511 context objects directly, specifically a RequestContext object. Chances are
512 your service is already using these to represent information from middleware
513 that sits in front of the API. Using context for authorization strikes a
514 perfect balance between integration testing and exercising just enough
515 authorization to ensure policies sufficiently protect APIs. The oslo.policy
516 library also accepts context objects and automatically translates properties to
517 values used when evaluating policy, which makes using them even more natural.
518
519 To use RequestContext objects effectively, you need to understand the policy
520 under test. Then, you can model a context object appropriately for the test
521 case. The idea is to build a context object to use in the request that either
522 fails or passes policy enforcement. For example, assume you're testing a
523 default policy like the following:
524
525 ::
526
527 from oslo_config import cfg
528
529 CONF = cfg.CONF
530 enforcer = policy.Enforcer(CONF, policy_file=_POLICY_PATH)
531
532 enforcer.register_default(
533 policy.RuleDefault('identity:create_region', 'role:admin')
534 )
535
536 Enforcement here is straightforward in that a user with a role called ``admin``
537 may access this API. You can model this in a request context by setting these
538 attributes explicitly:
539
540 ::
541
542 from oslo_context import context
543
544 context = context.RequestContext()
545 context.roles = ['admin']
546
547 Depending on how your service deploys the API in unit tests, you can either
548 provide a fake context as you supply the request, or mock the return value of
549 the context to return the one you've built.
550
551 You can also supply scope information for policies with complex check strings
552 or the use of scope types. For example, consider the following default policy:
553
554 ::
555
556 from oslo_config import cfg
557
558 CONF = cfg.CONF
559 enforcer = policy.Enforcer(CONF, policy_file=_POLICY_PATH)
560
561 enforcer.register_default(
562 policy.RuleDefault('identity:create_region', 'role:admin',
563 scope_types=['system'])
564 )
565
566 We can model it using the following request context object, which includes
567 scope:
568
569 ::
570
571 from oslo_context import context
572
573 context = context.RequestContext()
574 context.roles = ['admin']
575 context.system_scope = 'all'
576
577 Note that ``all`` is a unique system scope target that signifies the user is
578 authorized to operate on the deployment system. Conversely, the following is an
579 example of a context modeling a project-scoped token:
580
581 ::
582
583 import uuid
584 from oslo_context import context
585
586 context = context.RequestContext()
587 context.roles = ['admin']
588 context.project_id = uuid.uuid4().hex
589
590 The significance here is the difference between administrator authorization on
591 the deployment system and administrator authorization on a project.