summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorHarry Rybacki <hrybacki@redhat.com>2018-05-04 14:21:30 -0400
committerHarry Rybacki <hrybacki@redhat.com>2018-05-20 13:40:30 -0400
commitacfc05ae9655702c096aa43e875c17c38339caec (patch)
tree77dfbada0ef24adb90129297299c3f7001cc9b78
parentdfeb67c789a010f00459d3c1aa93749e43529b4f (diff)
Define a set of basic default roles
With the recent work to keystone and oslo.policy, we should be able to offer tooling to project development teams so they can start evolving their policies. Before we start changing things, we should come to consensus on a set of defaults we should offer out of the box. Moving towards a set of known defaults will make maintenance for operators much easier. It will also build the foundation for a more robust RBAC system that is better at modeling complex organization, ultimately being more useful in the real-world. Change-Id: Ia6ddf64b4483a73ab79c86d5d794cce561aa19e0 Co-authored-By: Lance Bragstad <lbragstad@gmail.com> Co-Authored-By: Jamie Lennox <jamielennox@gmail.com>
Notes
Notes (review): Code-Review+2: Lance Bragstad <lbragstad@gmail.com> Code-Review+2: Gage Hugo <gagehugo@gmail.com> Code-Review+2: Morgan Fainberg <morgan.fainberg@gmail.com> Workflow+1: Morgan Fainberg <morgan.fainberg@gmail.com> Verified+2: Zuul Submitted-by: Zuul Submitted-at: Wed, 23 May 2018 17:57:58 +0000 Reviewed-on: https://review.openstack.org/566377 Project: openstack/keystone-specs Branch: refs/heads/master
-rw-r--r--specs/keystone/rocky/define-default-roles.rst285
1 files changed, 285 insertions, 0 deletions
diff --git a/specs/keystone/rocky/define-default-roles.rst b/specs/keystone/rocky/define-default-roles.rst
new file mode 100644
index 0000000..cad837a
--- /dev/null
+++ b/specs/keystone/rocky/define-default-roles.rst
@@ -0,0 +1,285 @@
1===================
2Basic Default Roles
3===================
4
5`blueprint basic-default-roles <https://blueprints.launchpad.net/openstack/+spec/basic-default-roles>`_
6
7Managing `Role Based Access Control
8<https://csrc.nist.gov/Projects/Role-Based-Access-Control>`_ (RBAC) across
9OpenStack is one of the hardest pain points for operators to deal with. It is
10not uncommon for operators to have to dig through source code and keep notes
11about oddities in RBAC implementations across OpenStack just to offer basic
12RBAC capabilities to their customers. End users are also affected because it is
13very rare for any two deployments to have similar roles, or ensure those roles
14are mapped to similar operations.
15
16Problem description
17===================
18
19OpenStack's initial implementation of RBAC was simple and worked for trivial
20deployments. As OpenStack evolved and deployments started modeling larger, more
21complex organizations, the RBAC implementation failed to evolve with it. As a
22result, operators are stuck using existing tooling to provide the facade of a
23more sophisticated RBAC solution. This is a confusing and incredibly tough
24maintenance burden for operators who customize policy.
25
26It's not uncommon to see various services hardcode operations to a specific
27role. While the operation may require that role, the role to policy mapping
28should be driven by policy defaults that can be overridden by operators instead
29of hardcoding.
30
31Proposed change
32===============
33
34As a platform, OpenStack should offer a basic, easy to understand RBAC
35implementation with clear, reasonable default values. The process of
36implementing this will give operators more flexibility out-of-the-box. It will
37also be less likely to introduce inconsistencies across deployments due to the
38limitations of the existing implementation.
39
40To help ensure a graceful transition, `improvements
41<http://specs.openstack.org/openstack/oslo-specs/specs/queens/policy-deprecation.html>`_
42were made to the oslo policy library and a community `goal
43<https://governance.openstack.org/tc/goals/queens/policy-in-code.html>`_ put in
44place to help projects teams register defaults policies in code and provide
45documentation. This work gives OpenStack project teams the tools necessary to
46improve default role definitions. The changing defaults can be consumed by
47operators in ways that are consistent with changing configuration options.
48
49This specification proposes that Keystone enhance the basic RBAC experience
50by incorporating the following default roles into its default policies.
51
52Our goal is that this work will serve as a template which other services may
53use to adopt the proposed default roles in a future `community goal
54<https://governance.openstack.org/tc/goals/>`_.
55
56Default Roles
57-------------
58
59**auditor**: It should only be used for read-only APIs and operations. Alternatively
60referred to as ``reader``, this role fills an extremely popular need from operators.
61
62**member**: serves as the
63general purpose ‘do-er’ role. It introduces granularity between the administrator(s)
64and everyone else.
65
66**admin**: This role will be only be considered appropriate for operations deemed too
67sensitive for anyone with a member role.
68
69The desired outcome of implementing the roles above is that projects should
70start moving away from the practice of hardcoding operations to specific role
71names. Instead, each policy should have a reasonable default that can be
72overridden by operators.
73
74Scope Type (Refresher)
75----------------------
76
77**project-scope**: Project-scope relates to authorization for operating in a
78specific tenancy of the cloud.
79
80**system-scope**: System-scope relates to authorization for operating with APIs that
81do not map nicely to the concept of Project scope. It is **not** meant to cover *all*
82APIs across a deployment. More information about system-scope can be found in the `specification
83<http://specs.openstack.org/openstack/keystone-specs/specs/keystone/queens/system-scope.html>`_,
84along with relevant historical context justifying the `need for system-scope
85<https://bugs.launchpad.net/keystone/+bug/968696>`_.
86
87Examples
88--------
89
90`auditor:`
91An example project-scoped application of this role would be listing project tags (``identity:get_project_tags``).
92An example system-scoped application of this role would be listing service endpoints
93(``identity:list_endpoints``).
94
95`member:`
96An example project-scoped application of this role would be creating a project tag (``identity:update_project_tags``).
97An example system-scope application of this role would be updating an endpoint
98(``identity:update_endpoint``).
99
100`admin:`
101An example project-scoped administrator operation would be deleting project tags (``identity:delete_project_tags``).
102An example system-scoped administrator operation would be creating an endpoint for a service
103(``identity:create_endpoint``) or listing migrations (``os_compute_api:os-migrations``).
104
105
106The following table is neither a final nor a comprehensive list of all possible rules/policies.
107It serves merely as a snippet of existing rules to showcase how policies, scope, and the new
108default roles can work together to provide a richer policy experience.
109
110+-------------+------------------------------+---------------------------------+---------------------------------+
111| | auditor | member | admin |
112+=============+==============================+=================================+=================================+
113| **Project** | * identity:list_project_tags | * identity:list_project_tags | * identity:list_project_tags |
114| | * identity:get_project_tag | * identity:get_project_tag | * identity:get_project_tag |
115| | | * identity:update_project_tags | * identity:update_project_tags |
116| | | | * identity:create_project_tag |
117| | | | * identity:delete_project_tags |
118+-------------+------------------------------+---------------------------------+---------------------------------+
119| **System** | * identity:list_endpoints | * identity:list_endpoints | * identity:list_endpoints |
120| | * identity:get_endpoint | * identity:get_endpoint | * identity:get_endpoint |
121| | | * identity:update_endpoint | * identity:update_endpoint |
122| | | | * identity:create_endpoint |
123| | | | * os_compute_api:os-hypervisors |
124| | | | * os_compute_api:os-migrations |
125+-------------+------------------------------+---------------------------------+---------------------------------+
126
127
128Example snippets of various policy files, or rendered snippets, could look like
129the following.
130
131.. note::
132
133 The default roles discussed will be created by Keystone, during the bootstrap process, using `implied roles
134 <https://docs.openstack.org/python-openstackclient/latest/cli/command-objects/implied_role.html>`_.
135 As indicated in the above table, having ``admin`` role implies a user also has the same rights as
136 the ``member`` role. Therefore this user will also has the same rights as the ``auditor`` role as
137 ``member`` implies ``auditor``.
138
139 This keeps policy files clean. For example:
140
141 "identity:list_endpoints": "role:auditor OR role:member OR role:admin" is equivalent to
142 "identity:list_endpoints": "role:auditor" as a result of the implied roles chain.
143
144 The chain of implied roles will be documented alongside of the `policy-in-code defaults
145 <https://github.com/openstack/keystone/blob/master/keystone/common/policies/base.py>`_ in addition to
146 general Keystone documentation updates noting as much.
147
148::
149
150 # scope_types = ('project')
151 "identity:list_project_tags": "role:auditor"
152 "identity:get_project_tag": "role:auditor"
153 "identity:update_project_tags": "role:member"
154 "identity:create_project_tag": "role:admin"
155 "identity:delete_project_tags": "role:admin"
156
157 # scope_types = ('system')
158 "identity:list_endpoints": "role:auditor"
159 "identity:get_endpoints": "role:auditor"
160 "identity:update_endpoint": "role:member"
161 "identity:create_endpoint": "role:admin"
162 "os_compute_api:os-hypervisors": "role:admin"
163 "os_compute_api:os-migrations": "role:admin"
164
165
166Let's assume the following role assignment exist:
167
168- **Alice** has role **auditor** on system
169- **Bob** has the role **member** on system
170- **Charlie** has role **admin** on system
171- **Qiana** has role **auditor** on Project Alpha
172- **Rebecca** has role **member** on Project Alpha
173- **Steve** has role **admin** on Project Alpha
174
175Given the above assignments and policies, the following would be possible:
176
177**Alice** can list or retrieve specific endpoints. Alice cannot do any project specific
178operations since her authorization is limited to the deployment system.
179
180**Bob** can retrieve specific endpoints, list them, and update them. He cannot create new
181endpoints, or delete existing ones. Bob cannot do any project specific operations because his
182authorization is limited to the deployment system.
183
184**Charlie** can retrieve specific endpoints, list, as well as create them. Additionally, Charlie
185can list information on migrations as well as hypervisors. He cannot perform any project specific
186operations because his authorization is limited to the deployment system.
187
188**Qiana** can list all tags and get details about a specific tag within Project Alpha. She may not
189perform system specific policies because her authorization is on a single project.
190
191**Rebecca** can list all tags, get details about a specific tag, and update a tag within Project
192Alpha. She cannot perform any system specific policies because her authorization is on a single
193project.
194
195**Steve** can list all tags, create new tags, get details about a specific tag, update a tag, and
196delete tags within Project Alpha. He cannot perform any system specific policies because his
197authorization is on a single project.
198
199Risk Mitigation
200---------------
201
202**Scenario One -- A role serving the purposes described in this spec exists under another name**:
203Let us assume that Deployment A already has ``Role X`` which serves the purpose of the proposed here as
204the ``auditor`` role. In this instance, it is reasonable to assume that operators may have custom policy
205work in place and do not want to port immediately.
206
207This issue may be mitigated through the use of implied roles. Operators need simply to ensure that
208``auditor`` implies ``Role X``. Please review the documentation on `implied roles
209<https://docs.openstack.org/python-openstackclient/latest/cli/command-objects/implied_role.html>`_. for
210specific instructions on how make one role imply another.
211
212**Scenario Two -- An existing ``auditor``, ``member``, or ``admin`` role already exists**: Let us assume
213that Deployment B already has a ``member`` role. Keystone will not attempt to overwrite any existing roles
214that have been populated. It will instead note that a role with the name ``member`` already exists in log
215output.
216
217Alternatives
218------------
219
220reader/writer/admin vs auditor/member/admin. There was much debate regarding the naming
221conventions for these roles. We have opted to use `auditor`, `member`, and `admin` as we
222believe they most accurately describe their purpose when the context of OpenStack is taken
223into consideration.
224
225Implementation
226==============
227
228Assignee(s)
229-----------
230
231Primary assignee:
232
233* Lance Bragstad lbragstad lbragstad@gmail.com
234* Harry Rybacki hrybacki hrybacki@redhat.com
235
236Work Items
237----------
238
239* Add ability for Keystone bootstrap to create proposed roles
240* Implement auditor role across policies
241* Implement member role across policies
242* Implement admin role across policies
243* Implement scope_types for all policies in Keystone
244* Remove @protected decorator
245* Document how operators may generate policy files with service specific roles
246* Prepare Proof-of-Concept to demo and facilitate acceptance of an OpenStack Community Goal
247 to promote default roles across the other services.
248
249Dependencies
250============
251
252This work is dependent on the following:
253
254* `Registering and documenting
255 <https://governance.openstack.org/tc/goals/queens/policy-in-code.html>`_
256 all policies in code
257
258The work detailed in this specification will be supplemented with policy work
259being done in oslo and keystone:
260
261* Implementing `system-scope
262 <http://specs.openstack.org/openstack/keystone-specs/specs/keystone/queens/system-scope.html>`_
263 in keystone
264* Implementing `scope_types
265 <http://specs.openstack.org/openstack/oslo-specs/specs/queens/include-scope-in-policy.html>`_
266
267Full dependencies and relevant work can be found in the `Policy Roadmap
268<https://trello.com/b/bpWycnwa/policy-roadmap>`_.
269
270Resources
271=========
272
273* `Policy Roadmap <https://trello.com/b/bpWycnwa/policy-roadmap>`_
274* `System Scope <http://specs.openstack.org/openstack/keystone-specs/specs/keystone/queens/system-scope.html>`_
275* `Deprecation with oslo.policy <http://specs.openstack.org/openstack/oslo-specs/specs/queens/policy-deprecation.html>`_
276* `Scope types in oslo.policy <http://specs.openstack.org/openstack/oslo-specs/specs/queens/include-scope-in-policy.html>`_
277* Previous `attempts <https://review.openstack.org/#/c/245629>`_ at providing
278 default roles
279
280
281.. note::
282
283 This work is licensed under a Creative Commons Attribution 3.0 Unported License.
284 http://creativecommons.org/licenses/by/3.0/legalcode
285