Debian Codegraph @

doc/source/admin/policy-yaml-file.rst

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