openstack/keystone
Code Issues Proposed changes

Merge "Clarify `reader` role implementation in persona admin guide"

Browse Source
This commit is contained in:
Zuul 2021-02-27 05:23:02 +00:00 committed by Gerrit Code Review
commit f7c5a38881
1 changed files with 67 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

95
doc/source/admin/service-api-protection.rst
View File

@ -10,14 +10,16 @@ Like most OpenStack services, keystone protects its API using role-based access
control (RBAC).
Users can access different APIs depending on the roles they have on a project,
domain, or system.
domain, or system, which we refer to as scope.
As of the Rocky release, keystone provides three roles called ``admin``,
``member``, and ``reader`` by default. Operators can grant these roles to any
actor (e.g., group or user) on any target (e.g., system, domain, or project).
actor (e.g., group or user) on any scope (e.g., system, domain, or project).
If you need a refresher on authorization scopes and token types, please refer
to the `token guide`_. The following sections describe how each default role
behaves with keystone's API across different scopes.
behaves with keystone's API across different scopes. Additionally, other
service developers can use this document as a guide for implementing similar
patterns in their services.
Default roles and behaviors across scopes allow operators to delegate more
functionality to their team, auditors, customers, and users without maintaining
@ -29,9 +31,10 @@ custom policies.
Roles Definitions
-----------------
The default roles imply one another. The ``admin`` role implies the ``member``
role, and the ``member`` role implies the ``reader`` role. This implication
means users with the ``admin`` role automatically have the ``member`` and
The default roles provided by keystone, via ``keystone-manage boostrap``, are
related through role implications. The ``admin`` role implies the ``member``
role, and the ``member`` role implies the ``reader`` role. These implications
mean users with the ``admin`` role automatically have the ``member`` and
``reader`` roles. Additionally, users with the ``member`` role automatically
have the ``reader`` role. Implying roles reduces role assignments and forms a
natural hierarchy between the default roles. It also reduces the complexity of
@ -51,6 +54,26 @@ Instead of:
Reader
======
.. warning::
While it's possible to use the ``reader`` role to perform audits, we highly
recommend assessing the viability of using ``reader`` for auditing from the
perspective of the compliance target you're pursuing.
The ``reader`` role is the least-privileged role within the role hierarchy
described here. As such, OpenStack development teams, by default, do not
advocate exposing sensitive information to users with the ``reader`` role,
regardless of the scope. We have noted the need for a formal, read-only,
role that is useful for inspecting all applicable resources within a
particular scope, but it shouldn't be implemented as the lowest level of
authorization. This work will come in a subsequent release where we support
an elevated read-only role, that implies ``reader``, but also exposes
sensitive information, where applicable.
This will allow operators to grant third-party auditors a permissive role
for viewing sensitive information, specifically for compliance targets that
require it.
The ``reader`` role provides read-only access to resources within the system, a
domain, or a project. Depending on the assignment scope, two users with the
``reader`` role can expect different API behaviors. For example, a user with
@ -64,6 +87,20 @@ roles. For example, to accomplish this without analyzing assignment scope, you
would need ``system-reader``, ``domain-reader``, and ``project-reader`` roles
in addition to custom policies for each service.
It's imperative to note that ``reader`` is the least authoritative role in the
hierarchy because assignments using ``admin`` or ``member`` ultimately include
the ``reader`` role. We document this explicitly so that ``reader`` roles are not
overloaded with read-only access to sensitive information. For example, a deployment
pursuing a specific compliance target may want to leverage the ``reader`` role
to perform the audit. If the audit requires the auditor to evaluate sensitive
information, like license keys or administrative metadata, within a given
scope, auditors shouldn't expect to perform these operations with the
``reader`` role. We justify this design decision because sensitive information
should be explicitly protected, and not implicitly exposed.
The ``reader`` role should be implemented and used from the perspective of
least-privilege, which may or may not fulfill your auditing use case.
Member
======
@ -126,23 +163,24 @@ System Members & System Readers
In keystone, *system members* and *system readers* are very similar and have
the same authorization. Users with these roles on the system can view all
resources within keystone. They can audit role assignments, users, projects,
and group memberships, among other resources.
resources within keystone. They can list role assignments, users, projects, and
group memberships, among other resources.
The *system reader* persona is useful for auditors or members of a support
team. You can find *system members* and *system readers* in your deployment
with the following assignments:
The *system reader* persona is useful for members of a support team or auditors
if the audit doesn't require access to sensitive information. You can find
*system members* and *system readers* in your deployment with the following
assignments:
.. code-block:: console
$ openstack role assignment list --names --system all --role member --role reader
+--------+------------------------+-------------------------+---------+--------+--------+-----------+
| Role | User | Group | Project | Domain | System | Inherited |
+--------+------------------------+-------------------------+---------+--------+--------+-----------+
| reader | | system-auditors@Default | | | all | False |
| admin | operator@Default | | | | all | False |
| member | system-support@Default | | | | all | False |
+--------+------------------------+-------------------------+---------+--------+--------+-----------+
+--------+------------------------+------------------------+---------+--------+--------+-----------+
| Role | User | Group | Project | Domain | System | Inherited |
+--------+------------------------+------------------------+---------+--------+--------+-----------+
| reader | | system-support@Default | | | all | False |
| admin | operator@Default | | | | all | False |
| member | system-support@Default | | | | all | False |
+--------+------------------------+------------------------+---------+--------+--------+-----------+
.. warning::
@ -183,9 +221,10 @@ and system readers. They're allowed to view resources and information about
their domain. They aren't allowed to access system-specific information or
information about projects, groups, and users outside their domain.
The domain member and domain reader use-cases are great for auditing, support,
or monitoring the details of an account. You can find domain members and domain
readers with the following role assignments:
The domain member and domain reader use-cases are great for support teams,
monitoring the details of an account, or auditing resources within a domain
assuming the audit doesn't validate sensitive information. You can find domain
members and domain readers with the following role assignments:
.. code-block:: console
@ -199,7 +238,7 @@ readers with the following role assignments:
+--------+-----------------+-------+---------+--------+--------+-----------+
| Role | User | Group | Project | Domain | System | Inherited |
+--------+-----------------+-------+---------+--------+--------+-----------+
| reader | auditor@Default | | | foobar | | False |
| reader | support@Default | | | foobar | | False |
+--------+-----------------+-------+---------+--------+--------+-----------+
@ -249,12 +288,12 @@ the following role assignments:
| member | | foobar-operators@Default | production@foobar | | | False |
+--------+------+--------------------------+-------------------+--------+--------+-----------+
$ openstack role assignment list --names --project production --role reader
+--------+-----------------+----------------------------+-------------------+--------+--------+-----------+
| Role | User | Group | Project | Domain | System | Inherited |
+--------+-----------------+----------------------------+-------------------+--------+--------+-----------+
| reader | auditor@Default | | production@foobar | | | False |
| reader | | production-support@Default | production@foobar | | | False |
+--------+-----------------+----------------------------+-------------------+--------+--------+-----------+
+--------+---------------+----------------------------+-------------------+--------+--------+-----------+
| Role | User | Group | Project | Domain | System | Inherited |
+--------+---------------+----------------------------+-------------------+--------+--------+-----------+
| reader | alice@Default | | production@foobar | | | False |
| reader | | production-support@Default | production@foobar | | | False |
+--------+---------------+----------------------------+-------------------+--------+--------+-----------+
----------------
Writing Policies