2017-07-14 13:29:37 +00:00
|
|
|
.. _Authentication and authorization:
|
|
|
|
|
|
|
|
================================
|
|
|
|
Authentication and authorization
|
|
|
|
================================
|
|
|
|
|
|
|
|
Networking uses the Identity service as the default authentication
|
|
|
|
service. When the Identity service is enabled, users who submit requests
|
|
|
|
to the Networking service must provide an authentication token in
|
|
|
|
``X-Auth-Token`` request header. Users obtain this token by
|
|
|
|
authenticating with the Identity service endpoint. For more information
|
|
|
|
about authentication with the Identity service, see `OpenStack Identity
|
2018-06-22 11:58:16 +00:00
|
|
|
service API v3
|
2019-07-25 17:40:06 +02:00
|
|
|
Reference <https://docs.openstack.org/api-ref/identity/v3/>`__.
|
2017-07-14 13:29:37 +00:00
|
|
|
When the Identity service is enabled, it is not mandatory to specify the
|
|
|
|
project ID for resources in create requests because the project ID is
|
|
|
|
derived from the authentication token.
|
|
|
|
|
|
|
|
The default authorization settings only allow administrative users
|
|
|
|
to create resources on behalf of a different project. Networking uses
|
|
|
|
information received from Identity to authorize user requests.
|
|
|
|
Networking handles two kind of authorization policies:
|
|
|
|
|
|
|
|
- **Operation-based** policies specify access criteria for specific
|
|
|
|
operations, possibly with fine-grained control over specific
|
|
|
|
attributes.
|
|
|
|
|
|
|
|
- **Resource-based** policies specify whether access to specific
|
|
|
|
resource is granted or not according to the permissions configured
|
|
|
|
for the resource (currently available only for the network resource).
|
|
|
|
The actual authorization policies enforced in Networking might vary
|
|
|
|
from deployment to deployment.
|
|
|
|
|
2020-11-26 21:16:46 -06:00
|
|
|
The policy engine reads entries from the ``policy.yaml`` file. The
|
2017-07-14 13:29:37 +00:00
|
|
|
actual location of this file might vary from distribution to
|
|
|
|
distribution. Entries can be updated while the system is running, and no
|
|
|
|
service restart is required. Every time the policy file is updated, the
|
|
|
|
policies are automatically reloaded. Currently the only way of updating
|
|
|
|
such policies is to edit the policy file. In this section, the terms
|
|
|
|
*policy* and *rule* refer to objects that are specified in the same way
|
|
|
|
in the policy file. There are no syntax differences between a rule and a
|
|
|
|
policy. A policy is something that is matched directly from the
|
|
|
|
Networking policy engine. A rule is an element in a policy, which is
|
|
|
|
evaluated. For instance in ``"create_subnet":
|
|
|
|
"rule:admin_or_network_owner"``, *create_subnet* is a
|
|
|
|
policy, and *admin_or_network_owner* is a rule.
|
|
|
|
|
|
|
|
Policies are triggered by the Networking policy engine whenever one of
|
|
|
|
them matches a Networking API operation or a specific attribute being
|
|
|
|
used in a given operation. For instance the ``create_subnet`` policy is
|
|
|
|
triggered every time a ``POST /v2.0/subnets`` request is sent to the
|
|
|
|
Networking server; on the other hand ``create_network:shared`` is
|
|
|
|
triggered every time the *shared* attribute is explicitly specified (and
|
|
|
|
set to a value different from its default) in a ``POST /v2.0/networks``
|
|
|
|
request. It is also worth mentioning that policies can also be related
|
|
|
|
to specific API extensions; for instance
|
|
|
|
``extension:provider_network:set`` is triggered if the attributes
|
|
|
|
defined by the Provider Network extensions are specified in an API
|
|
|
|
request.
|
|
|
|
|
|
|
|
An authorization policy can be composed by one or more rules. If more
|
|
|
|
rules are specified then the evaluation policy succeeds if any of the
|
|
|
|
rules evaluates successfully; if an API operation matches multiple
|
|
|
|
policies, then all the policies must evaluate successfully. Also,
|
|
|
|
authorization rules are recursive. Once a rule is matched, the rule(s)
|
|
|
|
can be resolved to another rule, until a terminal rule is reached.
|
|
|
|
|
|
|
|
The Networking policy engine currently defines the following kinds of
|
|
|
|
terminal rules:
|
|
|
|
|
|
|
|
- **Role-based rules** evaluate successfully if the user who submits
|
|
|
|
the request has the specified role. For instance ``"role:admin"`` is
|
|
|
|
successful if the user who submits the request is an administrator.
|
|
|
|
|
|
|
|
- **Field-based rules** evaluate successfully if a field of the
|
|
|
|
resource specified in the current request matches a specific value.
|
|
|
|
For instance ``"field:networks:shared=True"`` is successful if the
|
|
|
|
``shared`` attribute of the ``network`` resource is set to true.
|
|
|
|
|
|
|
|
- **Generic rules** compare an attribute in the resource with an
|
|
|
|
attribute extracted from the user's security credentials and
|
|
|
|
evaluates successfully if the comparison is successful. For instance
|
|
|
|
``"tenant_id:%(tenant_id)s"`` is successful if the project identifier
|
|
|
|
in the resource is equal to the project identifier of the user
|
|
|
|
submitting the request.
|
|
|
|
|
2020-11-26 21:16:46 -06:00
|
|
|
This extract is from the default ``policy.yaml`` file:
|
2017-07-14 13:29:37 +00:00
|
|
|
|
|
|
|
- A rule that evaluates successfully if the current user is an
|
|
|
|
administrator or the owner of the resource specified in the request
|
|
|
|
(project identifier is equal).
|
|
|
|
|
|
|
|
.. code-block:: none
|
|
|
|
|
2020-11-26 21:16:46 -06:00
|
|
|
"admin_or_owner": "role:admin or tenant_id:%(tenant_id)s"
|
|
|
|
"admin_or_network_owner": "role:admin or tenant_id:%(network_tenant_id)s"
|
|
|
|
"admin_only": "role:admin"
|
|
|
|
"regular_user": ""
|
|
|
|
"shared": "field:networks:shared=True"
|
2017-07-14 13:29:37 +00:00
|
|
|
|
|
|
|
- The default policy that is always evaluated if an API operation does
|
2020-11-26 21:16:46 -06:00
|
|
|
not match any of the policies in ``policy.yaml``.
|
2017-07-14 13:29:37 +00:00
|
|
|
|
|
|
|
.. code-block:: none
|
|
|
|
|
2020-11-26 21:16:46 -06:00
|
|
|
"default": "rule:admin_or_owner"
|
|
|
|
"create_subnet": "rule:admin_or_network_owner"
|
|
|
|
"get_subnet": "rule:admin_or_owner or rule:shared"
|
|
|
|
"update_subnet": "rule:admin_or_network_owner"
|
|
|
|
"delete_subnet": "rule:admin_or_network_owner"
|
|
|
|
"create_network": ""
|
2017-07-14 13:29:37 +00:00
|
|
|
|
|
|
|
- This policy evaluates successfully if either *admin_or_owner*, or
|
|
|
|
*shared* evaluates successfully.
|
|
|
|
|
|
|
|
.. code-block:: none
|
|
|
|
|
2020-11-26 21:16:46 -06:00
|
|
|
"get_network": "rule:admin_or_owner or rule:shared"
|
|
|
|
"create_network:shared": "rule:admin_only"
|
2017-07-14 13:29:37 +00:00
|
|
|
|
|
|
|
- This policy restricts the ability to manipulate the *shared*
|
|
|
|
attribute for a network to administrators only.
|
|
|
|
|
|
|
|
.. code-block:: none
|
|
|
|
|
2020-11-26 21:16:46 -06:00
|
|
|
"update_network": "rule:admin_or_owner"
|
|
|
|
"delete_network": "rule:admin_or_owner"
|
|
|
|
"create_port": ""
|
|
|
|
"create_port:mac_address": "rule:admin_or_network_owner"
|
|
|
|
"create_port:fixed_ips": "rule:admin_or_network_owner"
|
2017-07-14 13:29:37 +00:00
|
|
|
|
|
|
|
- This policy restricts the ability to manipulate the *mac_address*
|
|
|
|
attribute for a port only to administrators and the owner of the
|
|
|
|
network where the port is attached.
|
|
|
|
|
|
|
|
.. code-block:: none
|
|
|
|
|
2020-11-26 21:16:46 -06:00
|
|
|
"get_port": "rule:admin_or_owner"
|
|
|
|
"update_port": "rule:admin_or_owner"
|
|
|
|
"delete_port": "rule:admin_or_owner"
|
2017-07-14 13:29:37 +00:00
|
|
|
|
|
|
|
In some cases, some operations are restricted to administrators only.
|
|
|
|
This example shows you how to modify a policy file to permit project to
|
|
|
|
define networks, see their resources, and permit administrative users to
|
|
|
|
perform all other operations:
|
|
|
|
|
|
|
|
.. code-block:: none
|
|
|
|
|
2020-11-26 21:16:46 -06:00
|
|
|
"admin_or_owner": "role:admin or tenant_id:%(tenant_id)s"
|
|
|
|
"admin_only": "role:admin"
|
|
|
|
"regular_user": ""
|
|
|
|
"default": "rule:admin_only"
|
|
|
|
"create_subnet": "rule:admin_only"
|
|
|
|
"get_subnet": "rule:admin_or_owner"
|
|
|
|
"update_subnet": "rule:admin_only"
|
|
|
|
"delete_subnet": "rule:admin_only"
|
|
|
|
"create_network": ""
|
|
|
|
"get_network": "rule:admin_or_owner"
|
|
|
|
"create_network:shared": "rule:admin_only"
|
|
|
|
"update_network": "rule:admin_or_owner"
|
|
|
|
"delete_network": "rule:admin_or_owner"
|
|
|
|
"create_port": "rule:admin_only"
|
|
|
|
"get_port": "rule:admin_or_owner"
|
|
|
|
"update_port": "rule:admin_only"
|
2017-07-14 13:29:37 +00:00
|
|
|
"delete_port": "rule:admin_only"
|