62810ddf28
Fixes output of tools/validate.py --force (except training-guide and generated files) Change-Id: I720846d97ab150915b26fb56926f0971d1808a2a
184 lines
9.7 KiB
XML
184 lines
9.7 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<chapter xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
|
|
xml:id="ch_auth">
|
|
<title>Authentication and Authorization</title>
|
|
<para>OpenStack Networking uses the OpenStack Identity Service
|
|
(project name keystone) as the default authentication service.
|
|
When OpenStack Identity is enabled, users who submit requests
|
|
to the OpenStack Networking service must provide an
|
|
authentication token in X-Auth-Token request header. Users get
|
|
this token by authenticating with the OpenStack Identity
|
|
endpoint. For more information about authentication with
|
|
OpenStack Identity Service, see the OpenStack Identity
|
|
documentation.</para>
|
|
<para>When OpenStack Identity is enabled, it is not mandatory to
|
|
specify tenant_id for resources in create requests because the
|
|
tenant identifier is derived from the authentication
|
|
token.</para>
|
|
<note>
|
|
<para>The default authorization settings only allow
|
|
administrative users to create resources on behalf of a
|
|
different tenant.</para>
|
|
</note>
|
|
<para>OpenStack Networking uses information received from
|
|
OpenStack Identity to authorize user requests. OpenStack
|
|
Networking handles two kind of authorization policies:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis role="bold">Operation-based</emphasis>:
|
|
policies specify access criteria for specific
|
|
operations, possibly with fine-grained control over
|
|
specific attributes; </para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis role="bold">Resource-based:</emphasis>
|
|
whether access to specific resource might be granted
|
|
or not according to the permissions configured for the
|
|
resource (currently available only for the network
|
|
resource). The actual authorization policies enforced
|
|
in OpenStack Networking might vary from deployment to
|
|
deployment.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>The policy engine reads entries from the <emphasis
|
|
role="italic">policy.json</emphasis> file. The 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. That is to say,
|
|
every time the policy file is updated, the policies will be
|
|
automatically reloaded. Currently the only way of updating
|
|
such policies is to edit the policy file.</para>
|
|
<para>In this section, the terms "policy" and "rule" both 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
|
|
OpenStack Networking policy engine. A rule is a component of
|
|
policies, which are then evaluated. For instance in
|
|
<code>create_subnet: [["admin_or_network_owner"]]</code>,
|
|
<emphasis role="italic">create_subnet</emphasis> is a
|
|
policy, and <emphasis role="italic"
|
|
>admin_or_network_owner</emphasis> is a rule.</para>
|
|
<para>Policies are triggered by the OpenStack Networking policy
|
|
engine whenever one of them matches an OpenStack Networking
|
|
API operation or a specific attribute being used in a given
|
|
operation. For instance the <code>create_subnet</code> policy
|
|
is triggered every time a <code>POST /v2.0/subnets</code>
|
|
request is sent to the OpenStack Networking server; on the
|
|
other hand <code>create_network:shared</code> is triggered
|
|
every time the <emphasis role="italic">shared</emphasis>
|
|
attribute is explicitly specified (and set to a value
|
|
different from its default) in a <code>POST
|
|
/v2.0/networks</code> request. It is also worth mentioning
|
|
that policies can be also related to specific API extensions;
|
|
for instance <code>extension:provider_network:set</code> will
|
|
be triggered if the attributes defined by the Provider Network
|
|
extensions are specified in an API request.</para>
|
|
<para>An authorization policy can be composed by one or more
|
|
rules. If more rules are specified, evaluation policy will be
|
|
successful if any of the rules evaluates successfully; if an
|
|
API operation matches multiple policies, all the policies must
|
|
evaluate successfully. Also, authorization rules are
|
|
recursive. Once a rule is matched, it can be resolved to
|
|
another rule until a terminal rule is reached.</para>
|
|
<para>The OpenStack Networking policy engine currently defines the
|
|
following kinds of terminal rules:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis role="bold">Role-based rules</emphasis>:
|
|
evaluate successfully if the user submitting the
|
|
request has the specified role. For instance
|
|
<code>"role:admin"</code>is successful if the user
|
|
submitting the request is an administrator.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis role="bold">Field-based rules:
|
|
</emphasis>evaluate successfully if a field of the
|
|
resource specified in the current request matches a
|
|
specific value. For instance
|
|
<code>"field:networks:shared=True"</code> is
|
|
successful if the attribute <emphasis role="italic"
|
|
>shared</emphasis> of the <emphasis role="italic"
|
|
>network</emphasis> resource is set to
|
|
true.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis role="bold">Generic rules:</emphasis>
|
|
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
|
|
<code>"tenant_id:%(tenant_id)s"</code> is
|
|
successful if the tenant identifier in the resource is
|
|
equal to the tenant identifier of the user submitting
|
|
the request.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>The following is an extract from the default policy.json
|
|
file:</para>
|
|
<programlisting language="bash">{
|
|
[1] "admin_or_owner": [["role:admin"], ["tenant_id:%(tenant_id)s"]],
|
|
"admin_or_network_owner": [["role:admin"], ["tenant_id:%(network_tenant_id)s"]],
|
|
"admin_only": [["role:admin"]], "regular_user": [],
|
|
"shared": [["field:networks:shared=True"]],
|
|
[2] "default": [["rule:admin_or_owner"]],
|
|
"create_subnet": [["rule:admin_or_network_owner"]],
|
|
"get_subnet": [["rule:admin_or_owner"], ["rule:shared"]],
|
|
"update_subnet": [["rule:admin_or_network_owner"]],
|
|
"delete_subnet": [["rule:admin_or_network_owner"]],
|
|
"create_network": [],
|
|
[3] "get_network": [["rule:admin_or_owner"], ["rule:shared"]],
|
|
[4] "create_network:shared": [["rule:admin_only"]],
|
|
"update_network": [["rule:admin_or_owner"]],
|
|
"delete_network": [["rule:admin_or_owner"]],
|
|
"create_port": [],
|
|
[5] "create_port:mac_address": [["rule:admin_or_network_owner"]],
|
|
"create_port:fixed_ips": [["rule:admin_or_network_owner"]],
|
|
"get_port": [["rule:admin_or_owner"]],
|
|
"update_port": [["rule:admin_or_owner"]],
|
|
"delete_port": [["rule:admin_or_owner"]]
|
|
}</programlisting>
|
|
<para>[1] is a rule which evaluates successfully if the current
|
|
user is an administrator or the owner of the resource
|
|
specified in the request (tenant identifier is equal).</para>
|
|
<para>[2] is the default policy which is always evaluated if an
|
|
API operation does not match any of the policies in
|
|
policy.json.</para>
|
|
<para>[3] This policy will evaluate successfully if either
|
|
<emphasis role="italic">admin_or_owner</emphasis>, or
|
|
<emphasis role="italic">shared</emphasis> evaluates
|
|
successfully.</para>
|
|
<para>[4] This policy will restrict the ability of manipulating
|
|
the <emphasis role="italic">shared</emphasis> attribute for a
|
|
network to administrators only.</para>
|
|
<para>[5] This policy will restrict the ability of manipulating
|
|
the <emphasis role="italic">mac_address</emphasis> attribute
|
|
for a port only to administrators and the owner of the network
|
|
where the port is attached.</para>
|
|
<para>In some cases, some operations should be restricted to
|
|
administrators only; therefore, as a further example, let us
|
|
consider how this sample policy file should be modified in a
|
|
scenario where tenants are allowed only to define networks and
|
|
see their resources, and all the other operations can be
|
|
performed only in an administrative context:</para>
|
|
<programlisting language="bash">{
|
|
"admin_or_owner": [["role:admin"], ["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"]],
|
|
"delete_port": [["rule:admin_only"]]
|
|
}</programlisting>
|
|
</chapter>
|