openstack-manuals/doc/common/section_keystone_config_ldap.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="configuring-keystone-for-ldap-backend">
    <title>Integrate Identity with LDAP</title>
    <para>The Openstack Identity Service supports integration with
        existing LDAP directories for authentication and authorization
        services.</para>
    <para>When the Openstack Identity service is configured to use LDAP
        back ends, you can split authentication (using the
        <emphasis>identity</emphasis> feature) and
            authorization (using the
            <emphasis>assignment</emphasis> feature).</para>
        <para>The identity feature enables administrators to manage
        users and groups by each domain or the Openstack Identity Service entirely.</para>
        <para>The Assignments feature enables administrators to manage
        project role authorization using the Openstack Identity service SQL
        database, while providing user authentication through the
        LDAP directory.</para>
    <important os="rhel;fedora;centos">
        <para>For OpenStack Identity service to access LDAP servers, you must
            enable the <option>authlogin_nsswitch_use_ldap</option> boolean
            value for SELinux on the Openstack Identity server. To enable and
            make the option persistent across reboots:</para>
        <screen><prompt>#</prompt> <userinput>setsebool -P authlogin_nsswitch_use_ldap</userinput></screen>
    </important>
    <para>Identity configuration is split into two separate back ends: identity
        (back end for users and groups) and assignments (back end for domains,
        projects, roles, role assignments). To configure identity, set options in the
        <filename>/etc/keystone/keystone.conf</filename> file.
        See <xref linkend="configuring-keystone-for-ldap-backend-identity"/>
        for identity back end configuration examples and
        <xref linkend="configuring-keystone-for-ldap-backend-assignments"/>
        for assignment back end configuration examples.
        Modify these examples as needed.</para>
    <note>
        <para>Multiple back ends are supported. You can integrate the Openstack Identity service
            with a single LDAP server (configure both identity and assignments to
            LDAP, or set identity and assignments back end with SQL or LDAP),
            or multiple back ends using domain-specific configuration files.</para>
    </note>
    <formalpara>
        <title>To define the destination LDAP server</title>
        <para>Define the destination LDAP server in the
                <filename>keystone.conf</filename> file:</para>
    </formalpara>
    <programlisting language="ini">[ldap]
url = ldap://localhost
user = dc=Manager,dc=example,dc=org
password = samplepassword
suffix = dc=example,dc=org
use_dumb_member = False
allow_subtree_delete = False</programlisting>
    <note>
        <para>Configure <option>dumb_member</option> if you set <option>use_dumb_member</option> to true.</para>
        <programlisting language="ini">[ldap]
dumb_member = cn=dumb,dc=nonexistent</programlisting>
    </note>
    <formalpara>
        <title>Additional LDAP integration settings</title>
        <para>Set these options in the
          <filename>/etc/keystone/keystone.conf</filename> file for a single LDAP server, or
          <filename>/etc/keystone/domains/keystone.<replaceable>DOMAIN_NAME</replaceable>.conf</filename> files for
          multiple back ends.</para>
    </formalpara>
    <variablelist>
        <varlistentry>
            <term>Query option</term>
            <listitem>
                <para>Use <option>query_scope</option>
                    to control the scope level of data
                    presented (search only the first level or search an entire
                    sub-tree) through LDAP.</para>
                <para>Use <option>page_size</option> to control the maximum
                    results per page. A value of zero disables paging.</para>
                <para>Use <option>alias_dereferencing</option> to control
                    the LDAP dereferencing option for queries.</para>
                <para>Use <option>chase_referrals</option> to override the
                    system's default referral chasing behavior for queries.</para>
                <programlisting language="ini">[ldap]
query_scope = sub
page_size = 0
alias_dereferencing = default
chase_referrals = </programlisting>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term>Debug</term>
            <listitem>
                <para>Use <option>debug_level</option> to set
                    the LDAP debugging level for LDAP calls. A value of zero means that
                    debugging is not enabled.</para>
                <programlisting language="ini">[ldap]
debug_level = 0</programlisting>
                <warning><para>This value is a bitmask, consult your LDAP
                    documentation for possible values.</para></warning>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term>Connection pooling</term>
            <listitem>
                <para>Use <option>use_pool</option> to enable LDAP connection
                    pooling. Configure connection pool size, maximum retry,
                    reconnect trials, timeout (-1 indicates indefinite
                    wait) and lifetime in seconds.</para>
                <programlisting language="ini">[ldap]
use_pool = true
pool_size = 10
pool_retry_max = 3
pool_retry_delay = 0.1
pool_connection_timeout = -1
pool_connection_lifetime = 600</programlisting>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term>Connection pooling for end user authentication</term>
            <listitem>
                <para>Use <option>use_auth_pool</option> to enable LDAP
                    connection pooling for end user authentication.
                    Configure connection pool size and lifetime in seconds.</para>
                <programlisting language="ini">[ldap]
use_auth_pool = false
auth_pool_size = 100
auth_pool_connection_lifetime = 60</programlisting>
            </listitem>
        </varlistentry>
    </variablelist>
    <para>When you have finished configuration, restart the Openstack Identity service:</para>
        <screen><prompt>#</prompt> <userinput>service keystone restart</userinput></screen>
        <warning><para>During service restart, authentication and
        authorization are unavailable.</para></warning>
    <xi:include href="section_keystone_config_ldap-identity.xml"/>
    <xi:include href="section_keystone_config_ldap-assignments.xml"/>
    <xi:include href="section_keystone_config_ldap-hardening.xml"/>
</section>