diff options
author | Zuul <zuul@review.opendev.org> | 2021-02-27 05:23:02 +0000 |
---|---|---|
committer | Gerrit Code Review <review@openstack.org> | 2021-02-27 05:23:02 +0000 |
commit | f7c5a3888142202d1511a4d6f4dccd7954c05dd4 (patch) | |
tree | 26eec0922aeade8c366ca4464f7663456e7f7d50 | |
parent | d67975e7b9cdbb3654840d7453402438a546c1bf (diff) | |
parent | 4df1130e1285da2a55569f727abe5077acd4220d (diff) | |
download | keystone-f7c5a3888142202d1511a4d6f4dccd7954c05dd4.tar.gz |
Merge "Clarify ``reader`` role implementation in persona admin guide"
-rw-r--r-- | doc/source/admin/service-api-protection.rst | 95 |
1 files changed, 67 insertions, 28 deletions
diff --git a/doc/source/admin/service-api-protection.rst b/doc/source/admin/service-api-protection.rst index 80b8af150..d7f146a39 100644 --- a/doc/source/admin/service-api-protection.rst +++ b/doc/source/admin/service-api-protection.rst @@ -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 |