From d02e5cd0daf051ef115b081ecc069850d4e585f7 Mon Sep 17 00:00:00 2001 From: Ben Nemec Date: Wed, 8 Jul 2020 17:48:59 +0000 Subject: [PATCH] Include example of literal comparison policy rule When doing a literal comparison in a rule, it is necessary to enclose the literal in single quotes. This is not apparent from the existing docs and is only mentioned in a private module[0] which does not appear in the published docs. This change adds an example that covers literal comparisons and briefly discusses how to determine what fields are available for comparison. The latter should be expanded upon at some point as it is important for anyone writing their own policy rules. Change-Id: I383f179ce274c1cf00f83d006a1dcddd40c52084 0: https://github.com/openstack/oslo.policy/blob/de857746867344c1a3f9f1dadf87b7ae046a1fc1/oslo_policy/_checks.py#L299 --- doc/source/admin/policy-yaml-file.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/doc/source/admin/policy-yaml-file.rst b/doc/source/admin/policy-yaml-file.rst index 1cef8fed..5757dc7b 100644 --- a/doc/source/admin/policy-yaml-file.rst +++ b/doc/source/admin/policy-yaml-file.rst @@ -63,6 +63,23 @@ You can also decline permission to use an API: The exclamation mark stands for "never" or "nobody", which effectively disables the Compute API "shelve an instance". +A simple comparison can be done using a literal value: + +.. code-block:: yaml + + "copy_image": "'shared':%(visibility)s" + +This check compares the literal ``shared`` with the value of the key +``visibility`` from the object. It will pass if and only if +``object['visibility'] == 'shared'``. It is necessary to include the +single quotes around the literal value when writing the rule so oslo.policy +knows not to interpret it as an API attribute. + +To determine the fields available on the object passed to the policy check, +it is necessary to enable debug logging for oslo.policy. This can be done +by enabling debug logging for the service in question, and also removing +``oslo_policy`` from the default_log_levels option. + Many APIs can only be called by administrators. This can be expressed by the rule ``"role:admin"``. The following policy ensures that only administrators can create new users in the Identity database: