41c1a82ae2
We are revaming the networking chapter of the Cloud Admin Guide into a new stand-alone Networking Guide. Part of that process is revamping the networking chapter itself. To make that easier, we are breaking it out into separate files for each section to facilitate editing by multiple authors. This change contains no content changes; all changes are structural. Change-Id: I644168cac44607e9b5657d52110daf36e0ee76a4 Closes-Bug: #1273553
190 lines
10 KiB
XML
190 lines
10 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<section 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="section_networking_auth">
|
|
<title>Authentication and authorization</title>
|
|
<para>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
|
|
<literal>X-Auth-Token</literal> request header. Users
|
|
obtain this token by authenticating with the Identity
|
|
Service endpoint. For more information about
|
|
authentication with the Identity Service, see <link
|
|
xlink:href="http://docs.openstack.org/api/openstack-identity-service/2.0/content/"
|
|
><citetitle>OpenStack Identity Service API v2.0
|
|
Reference</citetitle></link>. When the Identity
|
|
Service is enabled, it is not mandatory to specify the
|
|
tenant ID for resources in create requests because the
|
|
tenant ID 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. Networking uses information
|
|
received from Identity to authorize user requests.
|
|
Networking handles two kind of authorization
|
|
policies:</para>
|
|
</note>
|
|
<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>
|
|
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.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>The policy engine reads entries from the
|
|
<filename>policy.json</filename> 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. 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
|
|
<emphasis role="italic">policy</emphasis> and
|
|
<emphasis role="italic">rule</emphasis> 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
|
|
<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 Networking policy engine
|
|
whenever one of them matches an 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 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> is 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
|
|
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.</para>
|
|
<para>The 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 who submits the request has the specified
|
|
role. For instance <code>"role:admin"</code> is
|
|
successful if the user who submits 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 <literal>shared</literal>
|
|
attribute of the <literal>network</literal>
|
|
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>This extract is from the default
|
|
<filename>policy.json</filename> 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
|
|
<filename>policy.json</filename>.</para>
|
|
<para>[3] This policy evaluates successfully if either
|
|
<emphasis role="italic">admin_or_owner</emphasis>, or
|
|
<emphasis role="italic">shared</emphasis> evaluates
|
|
successfully.</para>
|
|
<para>[4] This policy restricts the ability to manipulate the
|
|
<emphasis role="italic">shared</emphasis> attribute
|
|
for a network to administrators only.</para>
|
|
<para>[5] This policy restricts the ability to manipulate 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 are restricted to
|
|
administrators only. This example shows you how to modify
|
|
a policy file to permit tenants to define networks and see
|
|
their resources and permit administrative users to perform
|
|
all other operations:</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>
|
|
</section>
|