security-doc/security-guide/section_api-endpoint-configuration-recommendations.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="api-endpoint-configuration-recommendations">
  <?dbhtml stop-chunking?>
    <title>API endpoint configuration recommendations</title>
    <section xml:id="api-endpoint-configuration-recommendations-internal-api-communications">
      <title>Internal API communications</title>
      <para>
        OpenStack provides both public facing and private API
        endpoints. By default, OpenStack components use the publicly
        defined endpoints. The recommendation is to configure these
        components to use the API endpoint within the proper security
        domain.</para>
      <para>
        Services select their respective API endpoints based on the
        OpenStack service catalog. These services might not
        obey the listed public or internal API end point
        values. This can lead to internal management traffic being
        routed to external API endpoints.</para>
      <section xml:id="api-endpoint-configuration-recommendations-internal-api-communications-configure-internal-urls-in-identity-service-catalog">
        <title>Configure internal URLs in the Identity service catalog</title>
        <para>
          The Identity service catalog should be aware of your
          internal URLs. While this feature is not utilized by
          default, it may be leveraged through
          configuration. Additionally, it should be forward-compatible
          with expectant changes once this behavior becomes the
          default.</para>
        <para>To register an internal URL for an endpoint:</para>
        <screen><prompt>$</prompt> <userinput>keystone endpoint-create \
 --region RegionOne \
 --service-id=1ff4ece13c3e48d8a6461faebd9cd38f \
 --publicurl='https://public-ip:8776/v1/%(tenant_id)s' \
 --internalurl='https://management-ip:8776/v1/%(tenant_id)s' \
 --adminurl='https://management-ip:8776/v1/%(tenant_id)s'</userinput></screen>
      </section>
      <section xml:id="api-endpoint-configuration-recommendations-internal-api-communications-configure-applications-for-internal-urls">
        <title>Configure applications for internal URLs</title>
        <para>
          You can force some services to use specific API
          endpoints. Therefore, it is recommended that each OpenStack
          service communicating to the API of another service must be
          explicitly configured to access the proper internal API
          endpoint.</para>
        <para>
          Each project may present an inconsistent way of defining
          target API endpoints. Future releases of OpenStack seek to
          resolve these inconsistencies through consistent use of the
          Identity service catalog.</para>
        <section xml:id="api-endpoint-configuration-recommendations-internal-api-communications-configure-applications-for-internal-urls-configuration-example-1">
          <title>Configuration example #1: nova</title>
          <programlisting language="ini">[DEFAULT]
cinder_catalog_info='volume:cinder:internalURL'
glance_protocol='https'
neutron_url='https://neutron-host:9696'
neutron_admin_auth_url='https://neutron-host:9696'
s3_host='s3-host'
s3_use_ssl=True</programlisting>
        </section>
        <section xml:id="api-endpoint-configuration-recommendations-internal-api-communications-configure-applications-for-internal-urls-configuration-example-2">
          <title>Configuration example #2: cinder</title>
          <programlisting language="ini">glance_host='https://glance-server'</programlisting>
        </section>
      </section>
    </section>
    <section xml:id="api-endpoint-configuration-recommendations-paste-and-middleware">
          <title>Paste and middleware</title>
      <para>
        Most API endpoints and other HTTP services in OpenStack use
        the Python Paste Deploy library. From a security perspective,
        this library enables manipulation of the request filter
        pipeline through the application's configuration. Each element
        in this chain is referred to as
        <emphasis>middleware</emphasis>. Changing the order of filters
        in the pipeline or adding additional middleware might have
        unpredictable security impact.</para>
      <para>
        Commonly, implementers add middleware to extend OpenStack's
        base functionality. We recommend implementers make careful
        consideration of the potential exposure introduced by the
        addition of non-standard software components to their HTTP
        request pipeline.</para>
      <para>For more information about Paste Deploy, see
        <link xlink:href="http://pythonpaste.org/deploy/">http://pythonpaste.org/deploy/</link>.
      </para>
    </section>
    <section xml:id="api-endpoint-configuration-recommendations-api-endpoint-process-isolation-and-policy">
      <title>API endpoint process isolation and policy</title>
      <para>
        You should isolate API endpoint
        processes, especially those that reside within the public
        security domain should be isolated as much as possible. Where
        deployments allow, API endpoints should be deployed on
        separate hosts for increased isolation.</para>
      <section xml:id="api-endpoint-configuration-recommendations-api-endpoint-process-isolation-and-policy-namespaces">
        <title>Namespaces</title>
        <para>
          Many operating systems now provide compartmentalization
          support. Linux supports namespaces to assign processes into
          independent domains. Other parts of this guide cover system
          compartmentalization in more detail.</para>
      </section>
      <section xml:id="api-endpoint-configuration-recommendations-api-endpoint-process-isolation-and-policy-network-policy">
        <title>Network policy</title>
        <para>
          Because API endpoints typically bridge multiple security
          domains, you must pay particular attention to the
          compartmentalization of the API processes. See <xref
          linkend="security-boundaries-and-threats-bridging-security-domains"/>
          for additional information in this area.</para>
        <para>
          With careful modeling, you can use network ACLs and IDS
          technologies to enforce explicit point to point
          communication between network services. As a critical cross
          domain service, this type of explicit enforcement works well
          for OpenStack's message queue service.</para>
        <para>
          To enforce policies, you can configure services, host-based
          firewalls (such as iptables), local policy (SELinux or
          AppArmor), and optionally global network policy.</para>
      </section>
      <section xml:id="api-endpoint-configuration-recommendations-api-endpoint-process-isolation-and-policy-mandatory-access-controls">
        <title>Mandatory access controls</title>
        <para>
          You should isolate API endpoint processes from each other
          and other processes on a machine. The configuration for
          those processes should be restricted to those processes not
          only by Discretionary Access Controls, but through Mandatory
          Access Controls. The goal of these enhanced access controls
          is to aid in the containment and escalation of API endpoint
          security breaches. With mandatory access controls, such
          breaches severely limit access to resources and provide
          earlier alerting on such events.</para>
      </section>
    </section>
</section>