"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "doc/source/admin/service-api-protection.rst" between
keystone-16.0.1.tar.gz and keystone-17.0.0.tar.gz

About: OpenStack Keystone (Core Service: Identity) provides an authentication and authorization service for other OpenStack services. Provides a catalog of endpoints for all OpenStack services.
The "Ussuri" series (latest release).

service-api-protection.rst  (keystone-16.0.1):service-api-protection.rst  (keystone-17.0.0)
============================================================= =============
Identity API protection with role-based access control (RBAC) Default Roles
============================================================= =============
------
Primer
------
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.
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).
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.
Default roles and behaviors across scopes allow operators to delegate more
functionality to their team, auditors, customers, and users without maintaining
custom policies.
.. _`token guide`: https://docs.openstack.org/keystone/latest/admin/tokens-overv
iew.html#authorization-scopes
-----------------
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
``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
default policies by making check strings short. For example, a policy that
requires ``reader`` can be expressed as:
Like most OpenStack projects, Identity supports the protection of its .. code-block:: yaml
APIs by defining policy rules based on an RBAC approach. Identity stores
a reference to a policy JSON file in the main Identity configuration
file, ``/etc/keystone/keystone.conf``. Typically this file is named
``policy.json``, and contains the rules for which roles have access to
certain actions in defined services.
Each Identity API v3 call has a line in the policy file that dictates
which level of governance of access applies.
.. code-block:: none
API_NAME: RULE_STATEMENT or MATCH_STATEMENT
Where:
``RULE_STATEMENT`` can contain ``RULE_STATEMENT`` or
``MATCH_STATEMENT``.
``MATCH_STATEMENT`` is a set of identifiers that must match between the
token provided by the caller of the API and the parameters or target
entities of the API call in question. For example:
.. code-block:: none
"identity:create_user": "role:admin and domain_id:%(user.domain_id)s"
Indicates that to create a user, you must have the admin role in your
token. The ``domain_id`` in your token must match the
``domain_id`` in the user object that you are trying
to create, which implies this must be a domain-scoped token.
In other words, you must have the admin role on the domain
in which you are creating the user, and the token that you use
must be scoped to that domain.
Each component of a match statement uses this format:
.. code-block:: none
ATTRIB_FROM_TOKEN:CONSTANT or ATTRIB_RELATED_TO_API_CALL
The Identity service expects these attributes:
Attributes from token:
- ``user_id``
- ``domain_id``
- ``project_id``
The ``project_id`` attribute requirement depends on the scope, and the
list of roles you have within that scope.
Attributes related to API call:
- ``user.domain_id``
- Any parameters passed into the API call
- Any filters specified in the query string
You reference attributes of objects passed with an object.attribute
syntax (such as, ``user.domain_id``). The target objects of an API are
also available using a target.object.attribute syntax. For instance:
.. code-block:: none "identity:list_foo": "role:reader"
"identity:delete_user": "role:admin and domain_id:%(target.user.domain_id)s" Instead of:
would ensure that Identity only deletes the user object in the same .. code-block:: yaml
domain as the provided token.
Every target object has an ``id`` and a ``name`` available as "identity:list_foo": "role:admin or role:member or role:reader"
``target.OBJECT.id`` and ``target.OBJECT.name``. Identity retrieves
other attributes from the database, and the attributes vary between
object types. The Identity service filters out some database fields,
such as user passwords.
List of object attributes: Reader
======
.. code-block:: yaml 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
the ``reader`` role on the system can list all projects within the deployment.
A user with the ``reader`` role on a domain can only list projects within their
domain.
By analyzing the scope of a role assignment, we increase the re-usability of
the ``reader`` role and provide greater functionality without introducing more
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.
Member
======
Within keystone, there isn't a distinct advantage to having the ``member`` role
instead of the ``reader`` role. The ``member`` role is more applicable to other
services. The ``member`` role works nicely for introducing granularity between
``admin`` and ``reader`` roles. Other services might write default policies
that require the ``member`` role to create resources, but the ``admin`` role to
delete them. For example, users with ``reader`` on a project could list
instance, users with ``member`` on a project can list and create instances, and
users with ``admin`` on a project can list, create, and delete instances.
Service developers can use the ``member`` role to provide more flexibility
between ``admin`` and ``reader`` on different scopes.
Admin
=====
We reserve the ``admin`` role for the most privileged operations within a given
scope. It is important to note that having ``admin`` on a project, domain, or
the system carries separate authorization and are not transitive. For example,
users with ``admin`` on the system should be able to manage every aspect of the
deployment because they're operators. Users with ``admin`` on a project
shouldn't be able to manage things outside the project because it would violate
the tenancy of their role assignment (this doesn't apply consistently since
services are addressing this individually at their own pace).
.. note::
As of the Train release, keystone applies the following personas
consistently across its API.
---------------------
System Administrators
---------------------
*System administrators* are allowed to manage every resource in keystone.
System administrators are typically operators and cloud administrators. They
can control resources that ultimately affect the behavior of the deployment.
For example, they can add or remove services and endpoints in the catalog,
create new domains, add federated mappings, and clean up stale resources, like
a user's application credentials or trusts.
You can find *system administrators* in your deployment with the following
assignments:
.. code-block:: console
$ openstack role assignment list --names --system all
+-------+------------------+-----------------------+---------+--------+-----
---+-----------+
| Role | User | Group | Project | Domain | Syst
em | Inherited |
+-------+------------------+-----------------------+---------+--------+-----
---+-----------+
| admin | | system-admins@Default | | | all
| False |
| admin | admin@Default | | | | all
| False |
| admin | operator@Default | | | | all
| False |
+-------+------------------+-----------------------+---------+--------+-----
---+-----------+
-------------------------------
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.
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:
.. code-block:: console
$ openstack role assignment list --names --system all --role member --role r
eader
+--------+------------------------+-------------------------+---------+-----
---+--------+-----------+
| Role | User | Group | Project | Doma
in | System | Inherited |
+--------+------------------------+-------------------------+---------+-----
---+--------+-----------+
| reader | | system-auditors@Default | |
| all | False |
| admin | operator@Default | | |
| all | False |
| member | system-support@Default | | |
| all | False |
+--------+------------------------+-------------------------+---------+-----
---+--------+-----------+
.. warning::
Filtering system role assignments is currently broken and is being tracked
as a `bug <https://bugs.launchpad.net/keystone/+bug/1846817>`_.
---------------------
Domain Administrators
---------------------
*Domain administrators* can manage most aspects of the domain or its contents.
These users can create new projects and users within their domain. They can
inspect the role assignments users have on projects within their domain.
*Domain administrators* aren't allowed to access system-specific resources or
resources outside their domain. Users that need control over project, group,
and user creation are a great fit for *domain administrators*.
You can find *domain administrators* in your deployment with the following role
assignment:
.. code-block:: console
$ openstack role assignment list --names --domain foobar --role admin
+-------+----------------+----------------------+---------+--------+--------
+-----------+
| Role | User | Group | Project | Domain | System
| Inherited |
+-------+----------------+----------------------+---------+--------+--------
+-----------+
| admin | jsmith@Default | | | foobar |
| False |
| admin | | foobar-admins@foobar | | foobar |
| False |
+-------+----------------+----------------------+---------+--------+--------
+-----------+
-------------------------------
Domain Members & Domain Readers
-------------------------------
Domain members and domain readers have the same relationship as system members
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:
.. code-block:: console
$ openstack role assignment list --names --role member --domain foobar
+--------+-------------+-------+---------+--------+--------+-----------+
| Role | User | Group | Project | Domain | System | Inherited |
+--------+-------------+-------+---------+--------+--------+-----------+
| member | jdoe@foobar | | | foobar | | False |
+--------+-------------+-------+---------+--------+--------+-----------+
$ openstack role assignment list --names --role reader --domain foobar
+--------+-----------------+-------+---------+--------+--------+-----------+
| Role | User | Group | Project | Domain | System | Inherited |
+--------+-----------------+-------+---------+--------+--------+-----------+
| reader | auditor@Default | | | foobar | | False |
+--------+-----------------+-------+---------+--------+--------+-----------+
----------------------
Project Administrators
----------------------
*Project administrators* can only view and modify data within the project in
their role assignment. They're able to view information about their projects
and set tags on their projects. They're not allowed to view system or domain
resources, as that would violate the tenancy of their role assignment. Since
the majority of the resources in keystone's API are system and domain-specific,
*project administrators* don't have much authorization.
You can find *project administrators* in your deployment with the following
role assignment:
.. code-block:: console
$ openstack role assignment list --names --project production --role admin
+-------+----------------+--------------------------+-------------------+---
-----+--------+-----------+
| Role | User | Group | Project | Do
main | System | Inherited |
+-------+----------------+--------------------------+-------------------+---
-----+--------+-----------+
| admin | jsmith@Default | | production@foobar |
| | False |
| admin | | production-admins@foobar | production@foobar |
| | False |
+-------+----------------+--------------------------+-------------------+---
-----+--------+-----------+
---------------------------------
Project Members & Project Readers
---------------------------------
*Project members* and *project readers* can discover information about their
projects. They can access important information like resource limits for their
project, but they're not allowed to view information outside their project or
view system-specific information.
You can find *project members* and *project readers* in your deployment with
the following role assignments:
.. code-block:: console
$ openstack role assignment list --names --project production --role member
+--------+------+--------------------------+-------------------+--------+---
-----+-----------+
| Role | User | Group | Project | Domain | Sy
stem | Inherited |
+--------+------+--------------------------+-------------------+--------+---
-----+-----------+
| 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 |
+--------+-----------------+----------------------------+-------------------
+--------+--------+-----------+
----------------
Writing Policies
----------------
If the granularity provided above doesn't meet your specific use-case, you can
still override policies and maintain them manually. You can read more about how
to do that in oslo.policy usage `documentation`_.
role: .. _`documentation`: https://docs.openstack.org/oslo.policy/latest/admin/index.h
target.role.id tml
target.role.name
user:
target.user.default_project_id
target.user.description
target.user.domain_id
target.user.enabled
target.user.id
target.user.name
group:
target.group.description
target.group.domain_id
target.group.id
target.group.name
domain:
target.domain.enabled
target.domain.id
target.domain.name
project:
target.project.description
target.project.domain_id
target.project.enabled
target.project.id
target.project.name
The default ``policy.json`` file supplied provides a somewhat
basic example of API protection, and does not assume any particular
use of domains. Refer to ``policy.v3cloudsample.json`` as an
example of multi-domain configuration installations where a cloud
provider wants to delegate administration of the contents of a domain
to a particular ``admin domain``. This example policy file also
shows the use of an ``admin_domain`` to allow a cloud provider to
enable administrators to have wider access across the APIs.
A clean installation could start with the standard policy file, to
allow creation of the ``admin_domain`` with the first users within
it. You could then obtain the ``domain_id`` of the admin domain,
paste the ID into a modified version of
``policy.v3cloudsample.json``, and then enable it as the main
``policy file``.
 End of changes. 9 change blocks. 
75 lines changed or deleted 295 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)