175 lines
9.3 KiB
XML
175 lines
9.3 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 submitting requests
|
|
to the OpenStack Networking service must provide an
|
|
authentication token in X-Auth-Token request header. The
|
|
aforementioned token should have been obtained by
|
|
authenticating with the OpenStack Identity endpoint.</para>
|
|
<para>For more information concerning authentication with
|
|
OpenStack Identity, please refer to the OpenStack Identity
|
|
documentation. When OpenStack Identity is enabled, it is not
|
|
mandatory to specify tenant_id for resources in create
|
|
requests, as the tenant identifier will be derived from the
|
|
Authentication token. Please note that the default
|
|
authorization settings only allow administrative users to
|
|
create resources on behalf of a different tenant. 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. Please note that in
|
|
this section we will use both the terms "policy" and "rule" to
|
|
refer to objects which are specified in the same way in the
|
|
policy file; in other words, there are no syntax differences
|
|
between a rule and a policy. We will define a policy something
|
|
which is matched directly from the OpenStack Networking policy
|
|
engine, whereas we will define a rule as the elements of such
|
|
policies which are then evaluated. For instance in
|
|
<code>create_subnet: [["admin_or_network_owner"]]</code>,
|
|
<emphasis role="italic">create_subnet</emphasis> is
|
|
regarded as a policy, whereas <emphasis role="italic"
|
|
>admin_or_network_owner</emphasis> is regarded as 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, 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 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>
|
|
<example xml:id="xml_example">
|
|
<title>policy.json file</title>
|
|
<programlistingco>
|
|
<areaspec>
|
|
<area xml:id="policy.json.rule1" units="linecolumn"
|
|
coords="2 23"/>
|
|
<area xml:id="policy.json.rule2" units="linecolumn"
|
|
coords="31 16"/>
|
|
<area xml:id="policy.json.rule3" units="linecolumn"
|
|
coords="62 20"/>
|
|
<area xml:id="policy.json.rule4" units="linecolumn"
|
|
coords="70 30"/>
|
|
<area xml:id="policy.json.rule5" units="linecolumn"
|
|
coords="88 32"/>
|
|
</areaspec>
|
|
<programlisting language="json"><xi:include href="samples/policy.json" parse="text"/></programlisting>
|
|
</programlistingco>
|
|
</example>
|
|
<calloutlist>
|
|
<callout arearefs="policy.json.rule1">
|
|
<para>A rule that evaluates successfully if the current
|
|
user is an administrator or the owner of the resource
|
|
specified in the request (tenant identifier is
|
|
equal).</para>
|
|
</callout>
|
|
<callout arearefs="policy.json.rule2">
|
|
<para>The default policy that is always evaluated if an
|
|
API operation does not match any of the policies in
|
|
policy.json.</para>
|
|
</callout>
|
|
<callout arearefs="policy.json.rule3">
|
|
<para>This policy evaluates successfully if either
|
|
<literal>admin_or_owner</literal>, or
|
|
<literal>shared</literal> evaluates
|
|
successfully.</para>
|
|
</callout>
|
|
<callout arearefs="policy.json.rule4">
|
|
<para>This policy restricts the ability of manipulating
|
|
the <literal>shared</literal> attribute for a network
|
|
to administrators only.</para>
|
|
</callout>
|
|
<callout arearefs="policy.json.rule5">
|
|
<para>This policy restricts the ability of manipulating
|
|
the <literal>mac_address</literal> attribute for a
|
|
port only to administrators and the owner of the
|
|
network where the port is attached.</para>
|
|
</callout>
|
|
</calloutlist>
|
|
<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="json"><xi:include href="samples/policy2.json" parse="text"/></programlisting>
|
|
</chapter>
|