The openstack_dashboard.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. 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 code to perform that check. However, conjunction operators are available, allowing for more expressiveness in crafting policies.

As an example, take the following rule, expressed in the list-of-lists representation:

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

In the policy language, this 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

It is possible to perform policy checks on the following user attributes (obtained through the token): user_id, domain_id or project_id:

domain_id:<some_value>

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

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

All these attributes (related to users, API calls, and context) can be checked against each other or against constants, be it literals (True, <a_number>) or strings.

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 openstack_dashboard.openstack.common.policy.AndCheck(rules)

Bases: openstack_dashboard.openstack.common.policy.BaseCheck

Implements the “and” logical operator.

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

AndCheck.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 openstack_dashboard.openstack.common.policy.BaseCheck

Bases: object

Abstract base class for Check classes.

class openstack_dashboard.openstack.common.policy.Check(kind, match)

Bases: openstack_dashboard.openstack.common.policy.BaseCheck

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

class openstack_dashboard.openstack.common.policy.Enforcer(policy_file=None, rules=None, default_rule=None, use_conf=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.

Enforcer.clear()

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

Enforcer.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 check() (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.

Enforcer.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 overwrite current rules.

Enforcer.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 openstack_dashboard.openstack.common.policy.FalseCheck

Bases: openstack_dashboard.openstack.common.policy.BaseCheck

A policy check that always returns False (disallow).

class openstack_dashboard.openstack.common.policy.GenericCheck(kind, match)

Bases: openstack_dashboard.openstack.common.policy.Check

class openstack_dashboard.openstack.common.policy.HttpCheck(kind, match)

Bases: openstack_dashboard.openstack.common.policy.Check

class openstack_dashboard.openstack.common.policy.NotCheck(rule)

Bases: openstack_dashboard.openstack.common.policy.BaseCheck

Implements the “not” logical operator.

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

class openstack_dashboard.openstack.common.policy.OrCheck(rules)

Bases: openstack_dashboard.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.

OrCheck.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 openstack_dashboard.openstack.common.policy.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.

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

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

ParseState.result

Obtain the final result of the parse.

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

ParseState.shift(tok, value)

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

class openstack_dashboard.openstack.common.policy.ParseStateMeta

Bases: type

Metaclass for the ParseState class.

Facilitates identifying reduction methods.

exception openstack_dashboard.openstack.common.policy.PolicyNotAuthorized(rule)

Bases: exceptions.Exception

class openstack_dashboard.openstack.common.policy.RoleCheck(kind, match)

Bases: openstack_dashboard.openstack.common.policy.Check

class openstack_dashboard.openstack.common.policy.RuleCheck(kind, match)

Bases: openstack_dashboard.openstack.common.policy.Check

class openstack_dashboard.openstack.common.policy.Rules(rules=None, default_rule=None)

Bases: dict

A store for rules. Handles the default_rule setting directly.

classmethod Rules.load_json(data, default_rule=None)

Allow loading of JSON rule data.

class openstack_dashboard.openstack.common.policy.TrueCheck

Bases: openstack_dashboard.openstack.common.policy.BaseCheck

A policy check that always returns True (allow).

openstack_dashboard.openstack.common.policy.parse_rule(rule)

Parses a policy rule into a tree of Check objects.

openstack_dashboard.openstack.common.policy.reducer(*tokens)

Decorator for reduction methods.

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

openstack_dashboard.openstack.common.policy.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.