| 1 |
==================== |
| 2 |
The policy.yaml file |
| 3 |
==================== |
| 4 |
|
| 5 |
Each OpenStack service, Identity, Compute, Networking, and so on, has its |
| 6 |
own role-based access policies. They determine which user can access |
| 7 |
which objects in which way, and are defined in the service's |
| 8 |
``policy.yaml`` file. |
| 9 |
|
| 10 |
Whenever an API call to an OpenStack service is made, the service's |
| 11 |
policy engine uses the appropriate policy definitions to determine if |
| 12 |
the call can be accepted. Any changes to ``policy.yaml`` are effective |
| 13 |
immediately, which allows new policies to be implemented while the |
| 14 |
service is running. |
| 15 |
|
| 16 |
A ``policy.yaml`` file is a text file in YAML (YAML Ain't Markup Language) |
| 17 |
format. Each policy is defined by a one-line statement in the |
| 18 |
form ``"<target>" : "<rule>"``. |
| 19 |
|
| 20 |
The policy target, also named "action", represents an API call like |
| 21 |
"start an instance" or "attach a volume". |
| 22 |
|
| 23 |
Action names are usually qualified. For example, the Compute service features |
| 24 |
API calls to list instances, volumes, and networks. In |
| 25 |
``/etc/nova/policy.yaml``, these APIs are represented by |
| 26 |
``compute:get_all``, ``volume:get_all``, and ``network:get_all``, |
| 27 |
respectively. |
| 28 |
|
| 29 |
The mapping between API calls and actions is not generally documented. |
| 30 |
|
| 31 |
The policy rule determines under which circumstances the API call is |
| 32 |
permitted. Usually this involves the user who makes the call (hereafter |
| 33 |
named the "API user") and often the object on which the API call |
| 34 |
operates. A typical rule checks if the API user is the object's owner. |
| 35 |
|
| 36 |
.. warning:: |
| 37 |
|
| 38 |
**Modifying the policy** |
| 39 |
|
| 40 |
While recipes for editing ``policy.yaml`` files are found on blogs, |
| 41 |
modifying the policy can have unexpected side effects and is not |
| 42 |
encouraged. |
| 43 |
|
| 44 |
Examples |
| 45 |
~~~~~~~~ |
| 46 |
|
| 47 |
A simple rule might look like this: |
| 48 |
|
| 49 |
.. code-block:: yaml |
| 50 |
|
| 51 |
"compute:get_all" : "" |
| 52 |
|
| 53 |
The target is ``"compute:get_all"``, the "list all instances" API of the |
| 54 |
Compute service. The rule is an empty string meaning "always". This |
| 55 |
policy allows anybody to list instances. |
| 56 |
|
| 57 |
You can also decline permission to use an API: |
| 58 |
|
| 59 |
.. code-block:: yaml |
| 60 |
|
| 61 |
"compute:shelve": "!" |
| 62 |
|
| 63 |
The exclamation mark stands for "never" or "nobody", which effectively |
| 64 |
disables the Compute API "shelve an instance". |
| 65 |
|
| 66 |
A simple comparison can be done using a literal value: |
| 67 |
|
| 68 |
.. code-block:: yaml |
| 69 |
|
| 70 |
"copy_image": "'shared':%(visibility)s" |
| 71 |
|
| 72 |
This check compares the literal ``shared`` with the value of the key |
| 73 |
``visibility`` from the object. It will pass if and only if |
| 74 |
``object['visibility'] == 'shared'``. It is necessary to include the |
| 75 |
single quotes around the literal value when writing the rule so oslo.policy |
| 76 |
knows not to interpret it as an API attribute. |
| 77 |
|
| 78 |
To determine the fields available on the object passed to the policy check, |
| 79 |
it is necessary to enable debug logging for oslo.policy. This can be done |
| 80 |
by enabling debug logging for the service in question, and also removing |
| 81 |
``oslo_policy`` from the default_log_levels option. |
| 82 |
|
| 83 |
Many APIs can only be called by administrators. This can be expressed by |
| 84 |
the rule ``"role:admin"``. The following policy ensures that only |
| 85 |
administrators can create new users in the Identity database: |
| 86 |
|
| 87 |
.. code-block:: yaml |
| 88 |
|
| 89 |
"identity:create_user" : "role:admin" |
| 90 |
|
| 91 |
.. note:: ``admin`` is a built-in default role in Keystone. For more |
| 92 |
details and other roles that may be available, see the |
| 93 |
`Keystone documentation on default roles. <https://docs.openstack.org/keystone/latest/admin/service-api-protection.html>`_ |
| 94 |
|
| 95 |
You can limit APIs to any role. For example, the Orchestration service |
| 96 |
defines a role named ``heat_stack_user``. Whoever has this role is not |
| 97 |
allowed to create stacks: |
| 98 |
|
| 99 |
.. code-block:: yaml |
| 100 |
|
| 101 |
"stacks:create": "not role:heat_stack_user" |
| 102 |
|
| 103 |
This rule makes use of the boolean operator ``not``. More complex rules |
| 104 |
can be built using operators ``and``, ``or``, and parentheses. |
| 105 |
|
| 106 |
You can define aliases for rules: |
| 107 |
|
| 108 |
.. code-block:: yaml |
| 109 |
|
| 110 |
"deny_stack_user": "not role:heat_stack_user" |
| 111 |
|
| 112 |
The policy engine understands that ``"deny_stack_user"`` is not an API |
| 113 |
and consequently interprets it as an alias. The stack creation policy |
| 114 |
above can then be written as: |
| 115 |
|
| 116 |
.. code-block:: yaml |
| 117 |
|
| 118 |
"stacks:create": "rule:deny_stack_user" |
| 119 |
|
| 120 |
This is taken verbatim from ``/etc/heat/policy.yaml``. |
| 121 |
|
| 122 |
Rules can compare API attributes to object attributes. For example: |
| 123 |
|
| 124 |
.. code-block:: yaml |
| 125 |
|
| 126 |
"os_compute_api:servers:start" : "project_id:%(project_id)s" |
| 127 |
|
| 128 |
states that only the owner of an instance can start it up. The |
| 129 |
``project_id`` string before the colon is an API attribute, namely the project |
| 130 |
ID of the API user. It is compared with the project ID of the object (in |
| 131 |
this case, an instance). More precisely, it is compared with the |
| 132 |
``project_id`` field of that object in the database. If the two values are |
| 133 |
equal, permission is granted. |
| 134 |
|
| 135 |
An administrator always has permission to call APIs. This is how |
| 136 |
``/etc/keystone/policy.yaml`` makes this policy explicit: |
| 137 |
|
| 138 |
.. code-block:: yaml |
| 139 |
|
| 140 |
"admin_required": "role:admin or is_admin:1" |
| 141 |
"owner" : "user_id:%(user_id)s" |
| 142 |
"admin_or_owner": "rule:admin_required or rule:owner" |
| 143 |
"identity:change_password": "rule:admin_or_owner" |
| 144 |
|
| 145 |
The first line defines an alias for "user is an admin user". The |
| 146 |
``is_admin`` flag is only used when setting up the Identity service for |
| 147 |
the first time. It indicates that the user has admin privileges granted |
| 148 |
by the service token (``--os-token`` parameter of the ``keystone`` |
| 149 |
command line client). |
| 150 |
|
| 151 |
The second line creates an alias for "user owns the object" by comparing |
| 152 |
the API's user ID with the object's user ID. |
| 153 |
|
| 154 |
Line 3 defines a third alias ``admin_or_owner``, combining the two first |
| 155 |
aliases with the Boolean operator ``or``. |
| 156 |
|
| 157 |
Line 4 sets up the policy that a password can only be modified by its |
| 158 |
owner or an admin user. |
| 159 |
|
| 160 |
As a final example, let's examine a more complex rule: |
| 161 |
|
| 162 |
.. code-block:: yaml |
| 163 |
|
| 164 |
"identity:ec2_delete_credential": "rule:admin_required or |
| 165 |
(rule:owner and user_id:%(target.credential.user_id)s)" |
| 166 |
|
| 167 |
|
| 168 |
This rule determines who can use the Identity API "delete EC2 |
| 169 |
credential". Here, boolean operators and parentheses combine three |
| 170 |
simpler rules. ``admin_required`` and ``owner`` are the same aliases as |
| 171 |
in the previous example. ``user_id:%(target.credential.user_id)s`` |
| 172 |
compares the API user with the user ID of the credential object |
| 173 |
associated with the target. |
| 174 |
|
| 175 |
Syntax |
| 176 |
~~~~~~ |
| 177 |
|
| 178 |
A ``policy.yaml`` file consists of policies and aliases of the form |
| 179 |
``target:rule`` or ``alias:definition``: |
| 180 |
|
| 181 |
.. code-block:: yaml |
| 182 |
|
| 183 |
"alias 1" : "definition 1" |
| 184 |
"alias 2" : "definition 2" |
| 185 |
.... |
| 186 |
"target 1" : "rule 1" |
| 187 |
"target 2" : "rule 2" |
| 188 |
.... |
| 189 |
|
| 190 |
Targets are APIs and are written ``"service:API"`` or simply ``"API"``. |
| 191 |
For example, ``"compute:create"`` or ``"add_image"``. |
| 192 |
|
| 193 |
Rules determine whether the API call is allowed. |
| 194 |
|
| 195 |
Rules can be: |
| 196 |
|
| 197 |
- Always true. The action is always permitted. This can be written as |
| 198 |
``""`` (empty string), ``[]``, or ``"@"``. |
| 199 |
|
| 200 |
- Always false. The action is never permitted. Written as ``"!"``. |
| 201 |
|
| 202 |
- A special check |
| 203 |
|
| 204 |
- A comparison of two values |
| 205 |
|
| 206 |
- Boolean expressions based on simpler rules |
| 207 |
|
| 208 |
Special checks are: |
| 209 |
|
| 210 |
- ``role:<role name>``, a test whether the API credentials contain |
| 211 |
this role. |
| 212 |
|
| 213 |
- ``rule:<rule name>``, the definition of an alias. |
| 214 |
|
| 215 |
- ``http:<target URL>``, which delegates the check to a remote server. |
| 216 |
The API is authorized when the server returns True. |
| 217 |
|
| 218 |
Developers can define additional special checks. |
| 219 |
|
| 220 |
Two values are compared in the following way: |
| 221 |
|
| 222 |
.. code-block:: yaml |
| 223 |
|
| 224 |
"value1 : value2" |
| 225 |
|
| 226 |
Possible values are: |
| 227 |
|
| 228 |
- Constants: Strings, numbers, ``true``, ``false`` |
| 229 |
|
| 230 |
- API attributes |
| 231 |
|
| 232 |
- Target object attributes |
| 233 |
|
| 234 |
- The flag ``is_admin`` |
| 235 |
|
| 236 |
API attributes can be ``project_id``, ``user_id`` or ``domain_id``. |
| 237 |
|
| 238 |
Target object attributes are fields from the object description in the |
| 239 |
database. For example in the case of the ``"compute:start"`` API, the |
| 240 |
object is the instance to be started. The policy for starting instances |
| 241 |
could use the ``%(project_id)s`` attribute, that is the project that |
| 242 |
owns the instance. The trailing ``s`` indicates this is a string. The same |
| 243 |
case would be valid for API attributes like ``%(user_id)s`` and |
| 244 |
``%(domain_id)s``. |
| 245 |
|
| 246 |
During a debug logging phase, it's common to have the target object |
| 247 |
attributes retrieved in the API calls. Comparing the API call on the logs |
| 248 |
with the policy enforced for the corresponding API, you can check which API |
| 249 |
attribute has been used as the target object. For example in the policy.yaml |
| 250 |
for the Nova project you can find ``"compute:start"`` API, the policy will show as |
| 251 |
``"rule:admin_or_owner"`` which will point for |
| 252 |
``"admin_or_owner": "is_admin:True or project_id:%(project_id)s"`` and in this |
| 253 |
way you can check that the target object in the debug logging it needs to be a |
| 254 |
``project_id`` attribute. |
| 255 |
|
| 256 |
``is_admin`` indicates that administrative privileges are granted via |
| 257 |
the admin token mechanism (the ``--os-token`` option of the ``keystone`` |
| 258 |
command). The admin token allows initialisation of the Identity database |
| 259 |
before the admin role exists. |
| 260 |
|
| 261 |
The alias construct exists for convenience. An alias is short name for a |
| 262 |
complex or hard to understand rule. It is defined in the same way as a |
| 263 |
policy: |
| 264 |
|
| 265 |
.. code-block:: yaml |
| 266 |
|
| 267 |
alias name : alias definition |
| 268 |
|
| 269 |
Once an alias is defined, use the ``rule`` keyword to use it in a policy |
| 270 |
rule. |