openstack/keystone
Code Issues Proposed changes

Clarify `reader` role implementation in persona admin guide

Browse Source 
The secure RBAC work propogating throughout the community has led to
some interesting discussions about how to implement support for
``reader``. Specifically, should ``reader`` be used for auditing
deployments?

Some compliance targets, verified by third-party auditors, require
access to sensitive information (e.g., thinking about license keys in
glance images or volume type encryption metadata in cinder). The concern
raised among developers updating their default policies to use
``reader`` roles is if they should be using that role to protect
sensitive information, especially if it's the least-authoritative role
in the hierarchy between reader, member, and admin.

This documentation is supposed to assist deployers in understanding the
various personas that developers are implementing by default, but it
doesn't call out the complicated relationship we have with ``reader``
and auditing.

The change here proposes that we explicitly say that ``reader``
shouldn't be used to protect sensitive information, regardless of the
scope, because ``reader`` was designed to be the least-authoritative
role provided by keystone, by default. Instead, service developers
working to implement these personas consistently in other services
should keep sensitive information, if applicable to their API or
resources, at the ``admin`` tier of the hierarchy. This provides better
protection of sensitive information by not exposing is implicitly.

We can consider supporting a formal default role for auditing in the
future, but building it outside the default implied role tree so that
it's not implied to anyone with a role assignment. This will come at
another time and we can use implied roles to re-use all the work we've
done across OpenStack to implement support for ``reader``.

For now, ``reader`` should be viewed from the perspective of the
least-authoritative permissions grant-able to a given scope (e.g.,
system, domain, or project). Even if ``reader`` has limited use in
auditing deployments, it's still incredibly useful for operators
because they have a role they can grant to users with minimal trust, or
minimal permissions in the deployment.

This commit acknowledges the use-case for an elevated auditor role and
that it's something we can implement as a formal role in keystone in the
future.

Change-Id: Iea28faf1b3e63c7ab07e90808d2bc76ee3ee0612
This commit is contained in:
Lance Bragstad 2021-01-19 19:24:37 +00:00
parent c239cc6661
commit 4df1130e12
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