Add Tacker RBAC change documentation and release notes
Tacker v1 API policies adopted the RBAC new defaults and this document try to explain the changes and how operator can use those. Also, adding the migration plan to move from old default to new default. Adding release notes also. Implement blueprint implement-project-personas Change-Id: Ib37cf65b79451a98e58b470726214e69624751a3
This commit is contained in:
Ghanshyam Mann
parent
ba24a89998
commit
d4579bbebb
@ -41,6 +41,16 @@ Policy
|
||||
Tacker, like most OpenStack projects, uses a policy language to restrict
|
||||
permissions on REST API actions.
|
||||
|
||||
* :doc:`Policy Concepts <policy-concepts>`: Starting in the Tacker 11.0.0
|
||||
(OpenStack 2024.1 Caracal) release, Tacker API policy defines new default
|
||||
roles. These new changes improve the security level and manageability of
|
||||
Tacker API as they are richer in terms of handling ‘Read’ and ‘Write’ roles.
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
|
||||
policy-concepts
|
||||
|
||||
* :doc:`Policy Reference <policy>`: A complete reference of all
|
||||
policy points in tacker and what they impact.
|
||||
|
||||
|
||||
334
doc/source/configuration/policy-concepts.rst
Normal file
334
doc/source/configuration/policy-concepts.rst
Normal file
@ -0,0 +1,334 @@
|
||||
Understanding Tacker Policies
|
||||
=============================
|
||||
|
||||
Tacker supports RBAC policy system to control the access permission of APIs.
|
||||
Tacker RBAC policy rule have the default value which can be overridden by
|
||||
operators via ``policy.yaml`` file.
|
||||
|
||||
We try to make the policy default value as close to operators requirements.
|
||||
In the Tacker 11.0.0 (OpenStack 2024.1 caracal) release, further work was
|
||||
undertaken to address some issues that had been identified:
|
||||
|
||||
#. No read-only roles. Since several APIs tend to share a single policy rule
|
||||
for read and write actions, they did not provide the granularity necessary
|
||||
for read-only access roles. To solve this, we should have reader role in
|
||||
the policy.
|
||||
|
||||
#. The ``admin_or_owner`` rule did not work as expected. It has check_str
|
||||
``"is_admin:True or project_id:%(project_id)s",`` which means it only
|
||||
check project_id for owner and not any role. This means `admin_or_owner``
|
||||
rule will allow user with any role in project. For example, user with
|
||||
``role:foo`` in project will behaves as the owner of the project resources.
|
||||
To solve this we should also check the ``member`` role in ``admin_or_owner``
|
||||
rule.
|
||||
|
||||
Keystone comes with ``admin``, ``member`` and ``reader`` roles by default.
|
||||
Please refer to `keystone document
|
||||
<https://docs.openstack.org/keystone/latest//admin/service-api-protection.html>`_
|
||||
for more information about these new defaults. In addition, keystone supports
|
||||
a new "scope" concept that makes it easier to protect deployment level
|
||||
resources from project level resources. Please refer to `keystone authorization
|
||||
scopes document
|
||||
<https://docs.openstack.org/keystone/latest//admin/tokens-overview.html#authorization-scopes>`_
|
||||
to understand the scope concept.
|
||||
|
||||
In the Tacker 11.0.0 (OpenStack 2024.1 caracal), Tacker policies implemented
|
||||
the new default roles provided by keystone (admin, member, and reader). Using
|
||||
common roles from keystone reduces the likelihood of similar, but different,
|
||||
roles implemented across projects or deployments (e.g., a role called
|
||||
``observer`` versus ``reader`` versus ``auditor``). With the help of the new
|
||||
defaults it is easier to understand who can do what across projects, reduces
|
||||
divergence, and increases interoperability. Along with new defaults, Tacker
|
||||
policy define scope_type which is hardcoded to ``project`` so that if system
|
||||
scope token try to access the Tacker APIs, they can get better error message.
|
||||
|
||||
The below sections explain how these new defaults in the Tacker can solve the
|
||||
two issues mentioned above and extend more functionality to end users in a
|
||||
safe and secure way.
|
||||
|
||||
Scope
|
||||
-----
|
||||
|
||||
OpenStack `Keystone supports different scopes
|
||||
<https://docs.openstack.org/keystone/latest//admin/tokens-overview.html#authorization-scopes>`_
|
||||
in tokens. Token scopes represent the layer of authorization. Policy
|
||||
``scope_types`` represent the layer of authorization required to access an API.
|
||||
|
||||
.. note::
|
||||
|
||||
The ``scope_type`` of each policy is hardcoded to ``project`` scoped
|
||||
and is not overridable via the policy file.
|
||||
|
||||
Tacker policies have implemented the scope concept by defining the
|
||||
``scope_type`` for all the policies to ``project`` scoped. It means if user
|
||||
tries to access Tacker APIs with ``system`` scoped token they will get 403
|
||||
permission denied error.
|
||||
|
||||
For example, consider the ``POST /vnflcm/v1/vnf_instances`` API.
|
||||
|
||||
.. code::
|
||||
|
||||
# Creates a new VNF instance resource
|
||||
# POST /vnflcm/v1/vnf_instances
|
||||
# Intended scope(s): project
|
||||
#"os_nfv_orchestration_api:vnf_instances:create": "rule:project_member_or_admin"
|
||||
|
||||
Policy scope is disabled by default to allow operators to migrate from the
|
||||
old policy enforcement system in a graceful way. This can be enabled by
|
||||
configuring the :oslo.config:option:`oslo_policy.enforce_scope` option to
|
||||
``True`` in tacker.conf on controller node.
|
||||
|
||||
.. note::
|
||||
|
||||
[oslo_policy]
|
||||
enforce_scope=True
|
||||
|
||||
|
||||
Roles
|
||||
-----
|
||||
|
||||
You can refer to `keystone role documentation
|
||||
<https://docs.openstack.org/keystone/latest//admin/service-api-protection.html>`_
|
||||
to know about all available defaults from Keystone.
|
||||
|
||||
Tacker policy defines new defaults for each policy.
|
||||
|
||||
.. rubric:: ``reader``
|
||||
|
||||
This provides read-only access to the resources. Tacker policies are
|
||||
defaulted to below rules:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
policy.RuleDefault(
|
||||
name="admin_api",
|
||||
check_str="role:admin",
|
||||
description="Default rule for administrative APIs."
|
||||
)
|
||||
|
||||
policy.RuleDefault(
|
||||
name="project_reader",
|
||||
check_str="role:reader and project_id:%(project_id)s",
|
||||
description="Default rule for Project level read only APIs."
|
||||
)
|
||||
|
||||
Using it in policy rule (with admin + reader access): (because we want to
|
||||
keep legacy admin behavior the same we need to give access of reader APIs
|
||||
to admin role too.)
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
policy.DocumentedRuleDefault(
|
||||
name='os_nfv_orchestration_api:vnf_instances:show',
|
||||
check_str='role:admin or (' + 'role:reader and project_id:%(project_id)s)',
|
||||
description="Query an Individual VNF instance.",
|
||||
operations=[
|
||||
{
|
||||
'method': 'GET',
|
||||
'path': '/vnflcm/v1/vnf_instances/{vnfInstanceId}'
|
||||
}
|
||||
],
|
||||
scope_types=['project'],
|
||||
)
|
||||
|
||||
OR
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
policy.DocumentedRuleDefault(
|
||||
name='os_nfv_orchestration_api:vnf_instances:show',
|
||||
check_str='rule: admin or rule:project_reader',
|
||||
description="Query an Individual VNF instance.",
|
||||
operations=[
|
||||
{
|
||||
'method': 'GET',
|
||||
'path': '/vnflcm/v1/vnf_instances/{vnfInstanceId}'
|
||||
}
|
||||
],
|
||||
scope_types=['project'],
|
||||
)
|
||||
|
||||
.. rubric:: ``member``
|
||||
|
||||
project-member is denoted by someone with the member role on a project. It is
|
||||
intended to be used by end users who consume resources within a project which
|
||||
requires higher permission than reader role but less than admin role. It
|
||||
inherits all the permissions of a project-reader.
|
||||
|
||||
project-member persona in the policy check string:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
policy.RuleDefault(
|
||||
name="admin_api",
|
||||
check_str="role:admin",
|
||||
description="Default rule for administrative APIs."
|
||||
)
|
||||
|
||||
policy.RuleDefault(
|
||||
name="project_member",
|
||||
check_str="role:member and project_id:%(project_id)s",
|
||||
description="Default rule for Project level non admin APIs."
|
||||
)
|
||||
|
||||
Using it in policy rule (with admin + member access): (because we want to keep
|
||||
legacy admin behavior, admin role gets access to the project level member APIs.)
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
policy.DocumentedRuleDefault(
|
||||
name='os_nfv_orchestration_api:vnf_instances:create',
|
||||
check_str='role:admin or (' + 'role:member and project_id:%(project_id)s)',
|
||||
description="Creates vnf instance.",
|
||||
operations=[
|
||||
{
|
||||
'method': 'POST',
|
||||
'path': '/vnflcm/v1/vnf_instances/{vnfInstanceId}'
|
||||
}
|
||||
],
|
||||
scope_types=['project'],
|
||||
)
|
||||
|
||||
OR
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
policy.DocumentedRuleDefault(
|
||||
name='os_nfv_orchestration_api:vnf_instances:create',
|
||||
check_str='rule: admin or rule:project_member',
|
||||
description="Query an Individual VNF instance.",
|
||||
operations=[
|
||||
{
|
||||
'method': 'POST',
|
||||
'path': '/vnflcm/v1/vnf_instances/{vnfInstanceId}'
|
||||
}
|
||||
],
|
||||
scope_types=['project'],
|
||||
)
|
||||
|
||||
'project_id:%(project_id)s' in the check_str is important to restrict the
|
||||
access within the requested project.
|
||||
|
||||
.. rubric:: ``admin``
|
||||
|
||||
This role is to perform the admin level write operations. Tacker policies are
|
||||
defaulted to below rules:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
policy.DocumentedRuleDefault(
|
||||
name='Polciy name',
|
||||
check_str='role:admin',
|
||||
scope_types=['project']
|
||||
)
|
||||
|
||||
Tacker supported scope & Roles
|
||||
------------------------------
|
||||
|
||||
Tacker supports the below combination of scopes and roles where roles can
|
||||
be overridden in the policy.yaml file but scope is not override-able.
|
||||
|
||||
#. ADMIN: ``admin`` role on ``project`` scope. This is an administrator to
|
||||
perform the admin level operations.
|
||||
|
||||
#. PROJECT_MEMBER: ``member`` role on ``project`` scope. This is used to
|
||||
perform resource owner level operation within project. For example:
|
||||
create vnf instance.
|
||||
|
||||
#. PROJECT_READER: ``reader`` role on ``project`` scope. This is used to
|
||||
perform read-only operation within project. For example: Get vnf instance.
|
||||
|
||||
#. PROJECT_MEMBER_OR_ADMIN: ``admin`` or ``member`` role on ``project`` scope.
|
||||
Such policy rules are default to most of the owner level APIs and align
|
||||
with `member` role legacy admin can continue to access those APIs.
|
||||
|
||||
#. PROJECT_READER_OR_ADMIN: ``admin`` or ``reader`` role on ``project`` scope.
|
||||
Such policy rules are default to most of the read only APIs so that legacy
|
||||
admin can continue to access those APIs.
|
||||
|
||||
Backward Compatibility
|
||||
----------------------
|
||||
|
||||
Backward compatibility with versions prior to Tacker 11.0.0 (OpenStack
|
||||
2024.1 Caracal) is maintained by supporting the old defaults by default.
|
||||
This means the old defaults and deployments that use them will keep working
|
||||
as-is. However, we encourage every deployment to switch to the new policy.
|
||||
The new defaults will be enabled by default in Tacker 12.0.0 (OpenStack
|
||||
2024.2 Dalmatian) release but we will keep the old default in deprecated
|
||||
defaults will be removed starting in the Tacker 15.0.0 (OpenStack 2026.1)
|
||||
release.
|
||||
|
||||
Migration Plan
|
||||
--------------
|
||||
|
||||
To have a graceful migration, Tacker provides two flags to switch to the new
|
||||
policy completely. You do not need to overwrite the policy file to adopt the
|
||||
new policy defaults.
|
||||
|
||||
Here is step wise guide for migration:
|
||||
|
||||
#. Create scoped token:
|
||||
|
||||
You need to create the project scoped token via below CLI:
|
||||
|
||||
- `Create Project Scoped Token
|
||||
<https://docs.openstack.org/keystone/latest//admin/tokens-overview.html#operation_create_project_scoped_token>`_.
|
||||
|
||||
#. Create new default roles in keystone if not done:
|
||||
|
||||
If you do not have new defaults in Keystone then you can create and re-run
|
||||
the `Keystone Bootstrap <https://docs.openstack.org/keystone/latest//admin/bootstrap.html>`_.
|
||||
|
||||
#. Enable Scope Checks
|
||||
|
||||
The :oslo.config:option:`oslo_policy.enforce_scope` flag is to enable the
|
||||
``scope_type`` features. The scope of the token used in the request is
|
||||
always compared to the ``scope_type`` of the policy. If the scopes do not
|
||||
match, one of two things can happen.
|
||||
If :oslo.config:option:`oslo_policy.enforce_scope` is True, the request
|
||||
will be rejected. If :oslo.config:option:`oslo_policy.enforce_scope` is
|
||||
False, an warning will be logged, but the request will be accepted
|
||||
(assuming the rest of the policy passes). The default value of this flag
|
||||
is False.
|
||||
|
||||
#. Enable new defaults
|
||||
|
||||
The :oslo.config:option:`oslo_policy.enforce_new_defaults` flag switches
|
||||
the policy to new defaults-only. This flag controls whether or not to use
|
||||
old deprecated defaults when evaluating policies. If True, the old
|
||||
deprecated defaults are not evaluated. This means if any existing token
|
||||
is allowed for old defaults but is disallowed for new defaults, it will be
|
||||
rejected. The default value of this flag is False.
|
||||
|
||||
.. note:: Before you enable this flag, you need to educate users about the
|
||||
different roles they need to use to continue using Tacker APIs.
|
||||
|
||||
NOTE::
|
||||
|
||||
We recommend to enable the both scope as well new defaults together
|
||||
otherwise you may experience some late failures with unclear error
|
||||
messages. For example, if you enable new defaults and disable scope
|
||||
check then it will allow system users to access the APIs but fail
|
||||
later due to the project check which can be difficult to debug.
|
||||
|
||||
Below table show how legacy rules are mapped to new rules:
|
||||
|
||||
+--------------------+---------------------------+----------------+-----------+
|
||||
| Legacy Rule | New Rules |Operation |scope_type |
|
||||
+====================+===========================+================+===========+
|
||||
| RULE_ADMIN_API |-> ADMIN |Global resource | [project] |
|
||||
| | |Write & Read | |
|
||||
+--------------------+---------------------------+----------------+-----------+
|
||||
| |-> ADMIN |Project admin | [project] |
|
||||
| | |level operation | |
|
||||
| +---------------------------+----------------+-----------+
|
||||
| RULE_ADMIN_OR_OWNER|-> PROJECT_MEMBER_OR_ADMIN |Project resource| [project] |
|
||||
| | |Write | |
|
||||
| +---------------------------+----------------+-----------+
|
||||
| |-> PROJECT_READER_OR_ADMIN |Project resource| [project] |
|
||||
| | |Read | |
|
||||
+--------------------+---------------------------+----------------+-----------+
|
||||
|
||||
We expect all deployments to migrate to the new policy by Tacker
|
||||
13.0.0 (OpenStack 2025.1) release so that we can remove the support
|
||||
of old policies in future release.
|
||||
@ -0,0 +1,41 @@
|
||||
---
|
||||
features:
|
||||
- |
|
||||
The Tacker v1 API policies implemented the SRBAC project personas with
|
||||
new default roles (``admin``, ``member``, and ``reader``) provided
|
||||
by keystone. Also, v1 API policies are scoped to ``project``.
|
||||
upgrade:
|
||||
- |
|
||||
Tacker v1 API policies defaults have been changed to SRBAC new defaults
|
||||
roles (``admin``, ``member``, and ``reader``) and scoped to ``project``.
|
||||
Legacy ``admin`` is unchanged instead project reader role is introduced.
|
||||
The old defaults are deprecated but they are still supported and enabled
|
||||
by defaults. In future release, new defaults will be enabled by defaults
|
||||
and old defaults will be removed.
|
||||
Please refer `Policy Concepts`_ and `SRBAC Project Personas`_ for
|
||||
detail about policy new defaults and migration plan.
|
||||
|
||||
* **New Defaults(Admin, Member and Reader)**
|
||||
Policies are default to Admin, Member and Reader roles. Old roles
|
||||
are also supported. You can switch to new defaults by setting the
|
||||
config option ``[oslo_policy]enforce_new_defaults`` to True in
|
||||
``tacker.conf`` file.
|
||||
|
||||
* **Scope**
|
||||
Each policy is protected with appropriate ``scope_type``. API policies
|
||||
are scoped to ``project`` only which mean no change in current access
|
||||
level but it will give better error message if system user try to
|
||||
access Tacker APIs. The scope checks are disabled by default and you
|
||||
can enable them by setting the config option
|
||||
``[oslo_policy]enforce_scope`` to True in ``tacker.conf`` file.
|
||||
|
||||
To know the new defaults, please refer the `Policy Reference`_ doc.
|
||||
This feature is disabled by default can be enabled via config option
|
||||
deprecations:
|
||||
- |
|
||||
Tacker v1 APIs policies old defaults are deprecated and will be removed
|
||||
in future release.
|
||||
|
||||
.. _SRBAC Project Personas: https://specs.openstack.org/openstack/tacker-specs/specs/2023.1/srbac-implement-project-personas.html
|
||||
.. _Policy Reference: https://docs.openstack.org/tacker/latest/configuration/policy.html
|
||||
.. _Policy Concepts: https://docs.openstack.org/tacker/latest/configuration/index.html#policy
|
||||
Loading…
x
Reference in New Issue
Block a user