"Fossies" - the Fresh Open Source Software Archive

Member "keystone-19.0.0/doc/source/admin/service-api-protection.rst" (14 Apr 2021, 19389 Bytes) of package /linux/misc/openstack/keystone-19.0.0.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) reStructured Text source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 =============
    2 Default Roles
    3 =============
    4 
    5 ------
    6 Primer
    7 ------
    8 
    9 Like most OpenStack services, keystone protects its API using role-based access
   10 control (RBAC).
   11 
   12 Users can access different APIs depending on the roles they have on a project,
   13 domain, or system, which we refer to as scope.
   14 
   15 As of the Rocky release, keystone provides three roles called ``admin``,
   16 ``member``, and ``reader`` by default. Operators can grant these roles to any
   17 actor (e.g., group or user) on any scope (e.g., system, domain, or project).
   18 If you need a refresher on authorization scopes and token types, please refer
   19 to the `token guide`_. The following sections describe how each default role
   20 behaves with keystone's API across different scopes. Additionally, other
   21 service developers can use this document as a guide for implementing similar
   22 patterns in their services.
   23 
   24 Default roles and behaviors across scopes allow operators to delegate more
   25 functionality to their team, auditors, customers, and users without maintaining
   26 custom policies.
   27 
   28 .. _`token guide`: https://docs.openstack.org/keystone/latest/admin/tokens-overview.html#authorization-scopes
   29 
   30 -----------------
   31 Roles Definitions
   32 -----------------
   33 
   34 The default roles provided by keystone, via ``keystone-manage boostrap``, are
   35 related through role implications. The ``admin`` role implies the ``member``
   36 role, and the ``member`` role implies the ``reader`` role. These implications
   37 mean users with the ``admin`` role automatically have the ``member`` and
   38 ``reader`` roles. Additionally, users with the ``member`` role automatically
   39 have the ``reader`` role. Implying roles reduces role assignments and forms a
   40 natural hierarchy between the default roles. It also reduces the complexity of
   41 default policies by making check strings short. For example, a policy that
   42 requires ``reader`` can be expressed as:
   43 
   44 .. code-block:: yaml
   45 
   46     "identity:list_foo": "role:reader"
   47 
   48 Instead of:
   49 
   50 .. code-block:: yaml
   51 
   52     "identity:list_foo": "role:admin or role:member or role:reader"
   53 
   54 Reader
   55 ======
   56 
   57 .. warning::
   58 
   59    While it's possible to use the ``reader`` role to perform audits, we highly
   60    recommend assessing the viability of using ``reader`` for auditing from the
   61    perspective of the compliance target you're pursuing.
   62 
   63    The ``reader`` role is the least-privileged role within the role hierarchy
   64    described here. As such, OpenStack development teams, by default, do not
   65    advocate exposing sensitive information to users with the ``reader`` role,
   66    regardless of the scope. We have noted the need for a formal, read-only,
   67    role that is useful for inspecting all applicable resources within a
   68    particular scope, but it shouldn't be implemented as the lowest level of
   69    authorization. This work will come in a subsequent release where we support
   70    an elevated read-only role, that implies ``reader``, but also exposes
   71    sensitive information, where applicable.
   72 
   73    This will allow operators to grant third-party auditors a permissive role
   74    for viewing sensitive information, specifically for compliance targets that
   75    require it.
   76 
   77 The ``reader`` role provides read-only access to resources within the system, a
   78 domain, or a project. Depending on the assignment scope, two users with the
   79 ``reader`` role can expect different API behaviors. For example, a user with
   80 the ``reader`` role on the system can list all projects within the deployment.
   81 A user with the ``reader`` role on a domain can only list projects within their
   82 domain.
   83 
   84 By analyzing the scope of a role assignment, we increase the re-usability of
   85 the ``reader`` role and provide greater functionality without introducing more
   86 roles. For example, to accomplish this without analyzing assignment scope, you
   87 would need ``system-reader``, ``domain-reader``, and ``project-reader`` roles
   88 in addition to custom policies for each service.
   89 
   90 It's imperative to note that ``reader`` is the least authoritative role in the
   91 hierarchy because assignments using ``admin`` or ``member`` ultimately include
   92 the ``reader`` role. We document this explicitly so that ``reader`` roles are not
   93 overloaded with read-only access to sensitive information. For example, a deployment
   94 pursuing a specific compliance target may want to leverage the ``reader`` role
   95 to perform the audit. If the audit requires the auditor to evaluate sensitive
   96 information, like license keys or administrative metadata, within a given
   97 scope, auditors shouldn't expect to perform these operations with the
   98 ``reader`` role. We justify this design decision because sensitive information
   99 should be explicitly protected, and not implicitly exposed.
  100 
  101 The ``reader`` role should be implemented and used from the perspective of
  102 least-privilege, which may or may not fulfill your auditing use case.
  103 
  104 Member
  105 ======
  106 
  107 Within keystone, there isn't a distinct advantage to having the ``member`` role
  108 instead of the ``reader`` role. The ``member`` role is more applicable to other
  109 services.  The ``member`` role works nicely for introducing granularity between
  110 ``admin`` and ``reader`` roles. Other services might write default policies
  111 that require the ``member`` role to create resources, but the ``admin`` role to
  112 delete them. For example, users with ``reader`` on a project could list
  113 instance, users with ``member`` on a project can list and create instances, and
  114 users with ``admin`` on a project can list, create, and delete instances.
  115 Service developers can use the ``member`` role to provide more flexibility
  116 between ``admin`` and ``reader`` on different scopes.
  117 
  118 Admin
  119 =====
  120 
  121 We reserve the ``admin`` role for the most privileged operations within a given
  122 scope. It is important to note that having ``admin`` on a project, domain, or
  123 the system carries separate authorization and are not transitive. For example,
  124 users with ``admin`` on the system should be able to manage every aspect of the
  125 deployment because they're operators. Users with ``admin`` on a project
  126 shouldn't be able to manage things outside the project because it would violate
  127 the tenancy of their role assignment (this doesn't apply consistently since
  128 services are addressing this individually at their own pace).
  129 
  130 .. note::
  131 
  132    As of the Train release, keystone applies the following personas
  133    consistently across its API.
  134 
  135 ---------------
  136 System Personas
  137 ---------------
  138 
  139 This section describes authorization personas typically used for operators and
  140 deployers. You can find all users with system role assignments using the
  141 following query:
  142 
  143 .. code-block:: console
  144 
  145     $ openstack role assignment list --names --system all
  146     +--------+------------------------+------------------------+---------+--------+--------+-----------+
  147     | Role   | User                   | Group                  | Project | Domain | System | Inherited |
  148     +--------+------------------------+------------------------+---------+--------+--------+-----------+
  149     | admin  |                        | system-admins@Default  |         |        | all    | False     |
  150     | admin  | admin@Default          |                        |         |        | all    | False     |
  151     | admin  | operator@Default       |                        |         |        | all    | False     |
  152     | reader |                        | system-support@Default |         |        | all    | False     |
  153     | admin  | operator@Default       |                        |         |        | all    | False     |
  154     | member | system-support@Default |                        |         |        | all    | False     |
  155     +--------+------------------------+------------------------+---------+--------+--------+-----------+
  156 
  157 System Administrators
  158 =====================
  159 
  160 *System administrators* are allowed to manage every resource in keystone.
  161 System administrators are typically operators and cloud administrators. They
  162 can control resources that ultimately affect the behavior of the deployment.
  163 For example, they can add or remove services and endpoints in the catalog,
  164 create new domains, add federated mappings, and clean up stale resources, like
  165 a user's application credentials or trusts.
  166 
  167 You can find *system administrators* in your deployment with the following
  168 assignments:
  169 
  170 .. code-block:: console
  171 
  172     $ openstack role assignment list --names --system all --role admin
  173     +-------+------------------+-----------------------+---------+--------+--------+-----------+
  174     | Role  | User             | Group                 | Project | Domain | System | Inherited |
  175     +-------+------------------+-----------------------+---------+--------+--------+-----------+
  176     | admin |                  | system-admins@Default |         |        | all    | False     |
  177     | admin | admin@Default    |                       |         |        | all    | False     |
  178     | admin | operator@Default |                       |         |        | all    | False     |
  179     +-------+------------------+-----------------------+---------+--------+--------+-----------+
  180 
  181 System Members & System Readers
  182 ===============================
  183 
  184 In keystone, *system members* and *system readers* are very similar and have
  185 the same authorization. Users with these roles on the system can view all
  186 resources within keystone. They can list role assignments, users, projects, and
  187 group memberships, among other resources.
  188 
  189 The *system reader* persona is useful for members of a support team or auditors
  190 if the audit doesn't require access to sensitive information. You can find
  191 *system members* and *system readers* in your deployment with the following
  192 assignments:
  193 
  194 .. code-block:: console
  195 
  196     $ openstack role assignment list --names --system all --role member --role reader
  197     +--------+------------------------+------------------------+---------+--------+--------+-----------+
  198     | Role   | User                   | Group                  | Project | Domain | System | Inherited |
  199     +--------+------------------------+------------------------+---------+--------+--------+-----------+
  200     | reader |                        | system-support@Default |         |        | all    | False     |
  201     | admin  | operator@Default       |                        |         |        | all    | False     |
  202     | member | system-support@Default |                        |         |        | all    | False     |
  203     +--------+------------------------+------------------------+---------+--------+--------+-----------+
  204 
  205 .. warning::
  206 
  207    Filtering system role assignments is currently broken and is being tracked
  208    as a `bug <https://bugs.launchpad.net/keystone/+bug/1846817>`_.
  209 
  210 ---------------
  211 Domain Personas
  212 ---------------
  213 
  214 This section describes authorization personas for people who manage their own
  215 domains, which contain projects, users, and groups. You can find all users with
  216 role assignments on a specific domain using the following query:
  217 
  218 .. code-block:: console
  219 
  220     $ openstack role assignment list --names --domain foobar
  221     +--------+-----------------+----------------------+---------+--------+--------+-----------+
  222     | Role   | User            | Group                | Project | Domain | System | Inherited |
  223     +--------+-----------------+----------------------+---------+--------+--------+-----------+
  224     | reader | support@Default |                      |         | foobar |        | False     |
  225     | admin  | jsmith@Default  |                      |         | foobar |        | False     |
  226     | admin  |                 | foobar-admins@foobar |         | foobar |        | False     |
  227     | member | jdoe@foobar     |                      |         | foobar |        | False     |
  228     +--------+-----------------+----------------------+---------+--------+--------+-----------+
  229 
  230 Domain Administrators
  231 =====================
  232 
  233 *Domain administrators* can manage most aspects of the domain or its contents.
  234 These users can create new projects and users within their domain. They can
  235 inspect the role assignments users have on projects within their domain.
  236 
  237 *Domain administrators* aren't allowed to access system-specific resources or
  238 resources outside their domain. Users that need control over project, group,
  239 and user creation are a great fit for *domain administrators*.
  240 
  241 You can find *domain administrators* in your deployment with the following role
  242 assignment:
  243 
  244 .. code-block:: console
  245 
  246     $ openstack role assignment list --names --domain foobar --role admin
  247     +-------+----------------+----------------------+---------+--------+--------+-----------+
  248     | Role  | User           | Group                | Project | Domain | System | Inherited |
  249     +-------+----------------+----------------------+---------+--------+--------+-----------+
  250     | admin | jsmith@Default |                      |         | foobar |        | False     |
  251     | admin |                | foobar-admins@foobar |         | foobar |        | False     |
  252     +-------+----------------+----------------------+---------+--------+--------+-----------+
  253 
  254 Domain Members & Domain Readers
  255 ===============================
  256 
  257 Domain members and domain readers have the same relationship as system members
  258 and system readers. They're allowed to view resources and information about
  259 their domain. They aren't allowed to access system-specific information or
  260 information about projects, groups, and users outside their domain.
  261 
  262 The domain member and domain reader use-cases are great for support teams,
  263 monitoring the details of an account, or auditing resources within a domain
  264 assuming the audit doesn't validate sensitive information. You can find domain
  265 members and domain readers with the following role assignments:
  266 
  267 .. code-block:: console
  268 
  269     $ openstack role assignment list --names --role member --domain foobar
  270     +--------+-------------+-------+---------+--------+--------+-----------+
  271     | Role   | User        | Group | Project | Domain | System | Inherited |
  272     +--------+-------------+-------+---------+--------+--------+-----------+
  273     | member | jdoe@foobar |       |         | foobar |        | False     |
  274     +--------+-------------+-------+---------+--------+--------+-----------+
  275     $ openstack role assignment list --names --role reader --domain foobar
  276     +--------+-----------------+-------+---------+--------+--------+-----------+
  277     | Role   | User            | Group | Project | Domain | System | Inherited |
  278     +--------+-----------------+-------+---------+--------+--------+-----------+
  279     | reader | support@Default |       |         | foobar |        | False     |
  280     +--------+-----------------+-------+---------+--------+--------+-----------+
  281 
  282 ----------------
  283 Project Personas
  284 ----------------
  285 
  286 This section describes authorization personas for users operating within a
  287 project. These personas are commonly used by end users. You can find all users
  288 with role assignments on a specific project using the following query:
  289 
  290 .. code-block:: console
  291 
  292     $ openstack role assignment list --names --project production
  293     +--------+----------------+----------------------------+-------------------+--------+--------+-----------+
  294     | Role   | User           | Group                      | Project           | Domain | System | Inherited |
  295     +--------+----------------+----------------------------+-------------------+--------+--------+-----------+
  296     | admin  | jsmith@Default |                            | production@foobar |        |        | False     |
  297     | admin  |                | production-admins@foobar   | production@foobar |        |        | False     |
  298     | member |                | foobar-operators@Default   | production@foobar |        |        | False     |
  299     | reader | alice@Default  |                            | production@foobar |        |        | False     |
  300     | reader |                | production-support@Default | production@foobar |        |        | False     |
  301     +--------+----------------+----------------------------+-------------------+--------+--------+-----------+
  302 
  303 Project Administrators
  304 ======================
  305 
  306 *Project administrators* can only view and modify data within the project they
  307 have authorization on. They're able to view information about their projects
  308 and set tags on their projects. They're not allowed to view system or domain
  309 resources, as that would violate the tenancy of their role assignment. Since
  310 the majority of the resources in keystone's API are system and domain-specific,
  311 *project administrators* don't have much authorization.
  312 
  313 You can find *project administrators* in your deployment with the following
  314 role assignment:
  315 
  316 .. code-block:: console
  317 
  318     $ openstack role assignment list --names --project production --role admin
  319     +-------+----------------+--------------------------+-------------------+--------+--------+-----------+
  320     | Role  | User           | Group                    | Project           | Domain | System | Inherited |
  321     +-------+----------------+--------------------------+-------------------+--------+--------+-----------+
  322     | admin | jsmith@Default |                          | production@foobar |        |        | False     |
  323     | admin |                | production-admins@foobar | production@foobar |        |        | False     |
  324     +-------+----------------+--------------------------+-------------------+--------+--------+-----------+
  325 
  326 Project Members & Project Readers
  327 =================================
  328 
  329 *Project members* and *project readers* can discover information about their
  330 projects. They can access important information like resource limits for their
  331 project, but they're not allowed to view information outside their project or
  332 view system-specific information.
  333 
  334 You can find *project members* and *project readers* in your deployment with
  335 the following role assignments:
  336 
  337 
  338 .. code-block:: console
  339 
  340     $ openstack role assignment list --names --project production --role member
  341     +--------+------+--------------------------+-------------------+--------+--------+-----------+
  342     | Role   | User | Group                    | Project           | Domain | System | Inherited |
  343     +--------+------+--------------------------+-------------------+--------+--------+-----------+
  344     | member |      | foobar-operators@Default | production@foobar |        |        | False     |
  345     +--------+------+--------------------------+-------------------+--------+--------+-----------+
  346     $ openstack role assignment list --names --project production --role reader
  347     +--------+---------------+----------------------------+-------------------+--------+--------+-----------+
  348     | Role   | User          | Group                      | Project           | Domain | System | Inherited |
  349     +--------+---------------+----------------------------+-------------------+--------+--------+-----------+
  350     | reader | alice@Default |                            | production@foobar |        |        | False     |
  351     | reader |               | production-support@Default | production@foobar |        |        | False     |
  352     +--------+---------------+----------------------------+-------------------+--------+--------+-----------+
  353 
  354 ----------------
  355 Writing Policies
  356 ----------------
  357 
  358 If the granularity provided above doesn't meet your specific use-case, you can
  359 still override policies and maintain them manually. You can read more about how
  360 to do that in oslo.policy usage `documentation`_.
  361 
  362 .. _`documentation`: https://docs.openstack.org/oslo.policy/latest/admin/index.html