The nova.openstack.common.policy Module

Common Policy Engine Implementation

Policies can be expressed in one of two forms: A list of lists, or a string written in the new policy language.

In the list-of-lists representation, each check inside the innermost list is combined as with an “and” conjunction–for that check to pass, all the specified checks must pass. These innermost lists are then combined as with an “or” conjunction. As an example, take the following rule, expressed in the list-of-lists representation:

[["role:admin"], ["project_id:%(project_id)s", "role:projectadmin"]]

This is the original way of expressing policies, but there now exists a new way: the policy language.

In the policy language, each check is specified the same way as in the list-of-lists representation: a simple “a:b” pair that is matched to the correct class to perform that check:

+===========================================================================+
|            TYPE                |                SYNTAX                    |
+===========================================================================+
|User's Role                     |              role:admin                  |
+---------------------------------------------------------------------------+
|Rules already defined on policy |          rule:admin_required             |
+---------------------------------------------------------------------------+
|Against URL's¹                  |         http://my-url.org/check          |
+---------------------------------------------------------------------------+
|User attributes²                |    project_id:%(target.project.id)s      |
+---------------------------------------------------------------------------+
|Strings                         |        <variable>:'xpto2035abc'          |
|                                |         'myproject':<variable>           |
+---------------------------------------------------------------------------+
|                                |         project_id:xpto2035abc           |
|Literals                        |         domain_id:20                     |
|                                |         True:%(user.enabled)s            |
+===========================================================================+

¹URL checking must return ‘True’ to be valid ²User attributes (obtained through the token): user_id, domain_id or project_id

Conjunction operators are available, allowing for more expressiveness in crafting policies. So, in the policy language, the previous check in list-of-lists becomes:

role:admin or (project_id:%(project_id)s and role:projectadmin)

The policy language also has the “not” operator, allowing a richer policy rule:

project_id:%(project_id)s and not role:dunce

Attributes sent along with API calls can be used by the policy engine (on the right side of the expression), by using the following syntax:

<some_value>:%(user.id)s

Contextual attributes of objects identified by their IDs are loaded from the database. They are also available to the policy engine and can be checked through the target keyword:

<some_value>:%(target.role.name)s

Finally, two special policy checks should be mentioned; the policy check “@” will always accept an access, and the policy check ”!” will always reject an access. (Note that if a rule is either the empty list (“[]”) or the empty string, this is equivalent to the “@” policy check.) Of these, the ”!” policy check is probably the most useful, as it allows particular rules to be explicitly disabled.

class AndCheck(rules)

Bases: nova.openstack.common.policy.BaseCheck

Implements the “and” logical operator.

A policy check that requires that a list of other checks all return True.

add_check(rule)

Adds rule to be tested.

Allows addition of another rule to the list of rules that will be tested. Returns the AndCheck object for convenience.

class BaseCheck

Bases: object

Abstract base class for Check classes.

class Check(kind, match)

Bases: nova.openstack.common.policy.BaseCheck

A base class to allow for user-defined policy checks.

class Enforcer(policy_file=None, rules=None, default_rule=None, use_conf=True, overwrite=True)

Bases: object

Responsible for loading and enforcing rules.

Parameters:

• policy_file – Custom policy file to use, if none is specified, CONF.policy_file will be used.
• rules – Default dictionary / Rules to use. It will be considered just in the first instantiation. If load_rules(True), clear() or set_rules(True) is called this will be overwritten.
• default_rule – Default rule to use, CONF.default_rule will be used if none is specified.
• use_conf – Whether to load rules from cache or config file.
• overwrite – Whether to overwrite existing rules when reload rules from config file.

clear()

Clears Enforcer rules, policy’s cache and policy’s path.

enforce(rule, target, creds, do_raise=False, exc=None, *args, **kwargs)

Checks authorization of a rule against the target and credentials.

Parameters:

• rule – A string or BaseCheck instance specifying the rule to evaluate.
• target – As much information about the object being operated on as possible, as a dictionary.
• creds – As much information about the user performing the action as possible, as a dictionary.
• do_raise – Whether to raise an exception or not if check fails.
• exc – Class of the exception to raise if the check fails. Any remaining arguments passed to enforce() (both positional and keyword arguments) will be passed to the exception class. If not specified, PolicyNotAuthorized will be used.

Returns:

Returns False if the policy does not allow the action and exc is not provided; otherwise, returns a value that evaluates to True. Note: for rules using the “case” expression, this True value will be the specified string from the expression.

load_rules(force_reload=False)

Loads policy_path’s rules.

Policy file is cached and will be reloaded if modified.

Parameters:force_reload – Whether to reload rules from config file.

set_rules(rules, overwrite=True, use_conf=False)

Create a new Rules object based on the provided dict of rules.

Parameters:

• rules – New rules to use. It should be an instance of dict.
• overwrite – Whether to overwrite current rules or update them with the new rules.
• use_conf – Whether to reload rules from cache or config file.

class FalseCheck

Bases: nova.openstack.common.policy.BaseCheck

A policy check that always returns False (disallow).

class GenericCheck(kind, match)

Bases: nova.openstack.common.policy.Check

class HttpCheck(kind, match)

Bases: nova.openstack.common.policy.Check

class NotCheck(rule)

Bases: nova.openstack.common.policy.BaseCheck

Implements the “not” logical operator.

A policy check that inverts the result of another policy check.

class OrCheck(rules)

Bases: nova.openstack.common.policy.BaseCheck

Implements the “or” operator.

A policy check that requires that at least one of a list of other checks returns True.

add_check(rule)

Adds rule to be tested.

Allows addition of another rule to the list of rules that will be tested. Returns the OrCheck object for convenience.

class ParseState

Bases: object

Implement the core of parsing the policy language.

Uses a greedy reduction algorithm to reduce a sequence of tokens into a single terminal, the value of which will be the root of the Check tree.

Note: error reporting is rather lacking. The best we can get with this parser formulation is an overall “parse failed” error. Fortunately, the policy language is simple enough that this shouldn’t be that big a problem.

reduce()

Perform a greedy reduction of the token stream.

If a reducer method matches, it will be executed, then the reduce() method will be called recursively to search for any more possible reductions.

reducers = [(['check', 'and', 'check'], '_make_and_expr'), (['not', 'check'], '_make_not_expr'), (['(', 'or_expr', ')'], '_wrap_check'), (['(', 'and_expr', ')'], '_wrap_check'), (['(', 'check', ')'], '_wrap_check'), (['and_expr', 'and', 'check'], '_extend_and_expr'), (['or_expr', 'or', 'check'], '_extend_or_expr'), (['check', 'or', 'check'], '_make_or_expr')]

result

Obtain the final result of the parse.

Raises ValueError if the parse failed to reduce to a single result.

shift(tok, value)

Adds one more token to the state. Calls reduce().

class ParseStateMeta

Bases: type

Metaclass for the ParseState class.

Facilitates identifying reduction methods.

exception PolicyNotAuthorized(rule)

Bases: exceptions.Exception

class RoleCheck(kind, match)

Bases: nova.openstack.common.policy.Check

class RuleCheck(kind, match)

Bases: nova.openstack.common.policy.Check

class Rules(rules=None, default_rule=None)

Bases: dict

A store for rules. Handles the default_rule setting directly.

classmethod load_json(data, default_rule=None)

Allow loading of JSON rule data.

class TrueCheck

Bases: nova.openstack.common.policy.BaseCheck

A policy check that always returns True (allow).

list_opts()

Entry point for oslo-config-generator.

parse_rule(rule)

Parses a policy rule into a tree of Check objects.

reducer(*tokens)

Decorator for reduction methods.

Arguments are a sequence of tokens, in order, which should trigger running this reduction method.

register(name, func=None)

Register a function or Check class as a policy check.

Parameters:

• name – Gives the name of the check type, e.g., ‘rule’, ‘role’, etc. If name is None, a default check type will be registered.
• func – If given, provides the function or class to register. If not given, returns a function taking one argument to specify the function or class to register, allowing use as a decorator.