| 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. |