<div id="docs-body">
 <div class="section">
  <div class="titlepage">
   <div>
    <div>
     <h4 class="title">
      <a name="ldap-pluggable-authentication">
      </a>
      8.4.1.7 LDAP Pluggable Authentication
     </h4>
    </div>
   </div>
  </div>
  <a class="indexterm" name="idm46045245399120">
  </a>
  <a class="indexterm" name="idm46045245397616">
  </a>
  <a class="indexterm" name="idm46045245396112">
  </a>
  <a class="indexterm" name="idm46045245394608">
  </a>
  <a class="indexterm" name="idm46045245393120">
  </a>
  <a class="indexterm" name="idm46045245392032">
  </a>
  <a class="indexterm" name="idm46045245390528">
  </a>
  <a class="indexterm" name="idm46045245389040">
  </a>
  <a class="indexterm" name="idm46045245387552">
  </a>
  <a class="indexterm" name="idm46045245386064">
  </a>
  <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
   <div class="admon-title">
    Note
   </div>
   <p>
    LDAP pluggable authentication is an extension included in
          MySQL Enterprise Edition, a commercial product. To learn more about commercial
          products, see
    <a class="ulink" href="https://www.mysql.com/products/" target="_blank">
     https://www.mysql.com/products/
    </a>
    .
   </p>
  </div>
  <p>
   MySQL Enterprise Edition supports an authentication method that enables MySQL
        Server to use LDAP (Lightweight Directory Access Protocol) to
        authenticate MySQL users by accessing directory services such as
        X.500. MySQL uses LDAP to fetch user, credential, and group
        information.
  </p>
  <p>
   LDAP pluggable authentication provides these capabilities:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      External authentication: LDAP authentication enables MySQL
            Server to accept connections from users defined outside the
            MySQL grant tables in LDAP directories.
     </p>
    </li>
    <li class="listitem">
     <p>
      Proxy user support: LDAP authentication can return to MySQL
            a user name different from the external user name passed by
            the client program, based on the LDAP groups the external
            user is a member of. This means that an LDAP plugin can
            return the MySQL user that defines the privileges the
            external LDAP-authenticated user should have. For example,
            an LDAP user named
      <code class="literal">
       joe
      </code>
      can connect and
            have the privileges of a MySQL user named
      <code class="literal">
       developer
      </code>
      , if the LDAP group for
      <code class="literal">
       joe
      </code>
      is
      <code class="literal">
       developer
      </code>
      .
     </p>
    </li>
    <li class="listitem">
     <p>
      Security: Using TLS, connections to the LDAP server can be
            secure.
     </p>
    </li>
   </ul>
  </div>
  <p>
   Server and client plugins are available for simple and
        SASL-based LDAP authentication. On Microsoft Windows, the server
        plugin for SASL-based LDAP authentication is not supported, but
        the client plugin is.
  </p>
  <p>
   The following tables show the plugin and library file names for
        simple and SASL-based LDAP authentication. The file name suffix
        might differ on your system. The files must be located in the
        directory named by the
   <a class="link" href="server-system-variables.html#sysvar_plugin_dir">
    <code class="literal">
     plugin_dir
    </code>
   </a>
   system variable.
  </p>
  <div class="table">
   <a name="idm46045245372912">
   </a>
   <p class="title">
    <b>
     Table 8.20 Plugin and Library Names for Simple LDAP Authentication
    </b>
   </p>
   <div class="table-contents">
    <table summary="Names for the plugins and library file used for simple LDAP password authentication.">
     <colgroup>
      <col style="width: 30%"/>
      <col style="width: 70%"/>
     </colgroup>
     <thead>
      <tr>
       <th>
        Plugin or File
       </th>
       <th>
        Plugin or File Name
       </th>
      </tr>
     </thead>
     <tbody>
      <tr>
       <td>
        Server-side plugin name
       </td>
       <td>
        <code class="literal">
         authentication_ldap_simple
        </code>
       </td>
      </tr>
      <tr>
       <td>
        Client-side plugin name
       </td>
       <td>
        <code class="literal">
         mysql_clear_password
        </code>
       </td>
      </tr>
      <tr>
       <td>
        Library file name
       </td>
       <td>
        <code class="filename">
         authentication_ldap_simple.so
        </code>
       </td>
      </tr>
     </tbody>
    </table>
   </div>
  </div>
  <br class="table-break"/>
  <div class="table">
   <a name="idm46045245359504">
   </a>
   <p class="title">
    <b>
     Table 8.21 Plugin and Library Names for SASL-Based LDAP Authentication
    </b>
   </p>
   <div class="table-contents">
    <table summary="Names for the plugins and library file used for SASL-based LDAP password authentication.">
     <colgroup>
      <col style="width: 30%"/>
      <col style="width: 70%"/>
     </colgroup>
     <thead>
      <tr>
       <th>
        Plugin or File
       </th>
       <th>
        Plugin or File Name
       </th>
      </tr>
     </thead>
     <tbody>
      <tr>
       <td>
        Server-side plugin name
       </td>
       <td>
        <code class="literal">
         authentication_ldap_sasl
        </code>
       </td>
      </tr>
      <tr>
       <td>
        Client-side plugin name
       </td>
       <td>
        <code class="literal">
         authentication_ldap_sasl_client
        </code>
       </td>
      </tr>
      <tr>
       <td>
        Library file names
       </td>
       <td>
        <code class="filename">
         authentication_ldap_sasl.so
        </code>
        ,
        <code class="filename">
         authentication_ldap_sasl_client.so
        </code>
       </td>
      </tr>
     </tbody>
    </table>
   </div>
  </div>
  <br class="table-break"/>
  <p>
   The library files include only the
   <code class="literal">
    authentication_ldap_
    <em class="replaceable">
     <code>
      XXX
     </code>
    </em>
   </code>
   authentication plugins. The client-side
   <code class="literal">
    mysql_clear_password
   </code>
   plugin is built into the
   <code class="literal">
    libmysqlclient
   </code>
   client library.
  </p>
  <p>
   Each server-side LDAP plugin works with a specific client-side
        plugin:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      The server-side
      <code class="literal">
       authentication_ldap_simple
      </code>
      plugin
            performs simple LDAP authentication. For connections by
            accounts that use this plugin, client programs use the
            client-side
      <code class="literal">
       mysql_clear_password
      </code>
      plugin,
            which sends the password to the server as cleartext. No
            password hashing or encryption is used, so a secure
            connection between the MySQL client and server is
            recommended to prevent password exposure.
     </p>
    </li>
    <li class="listitem">
     <p>
      The server-side
      <code class="literal">
       authentication_ldap_sasl
      </code>
      plugin performs SASL-based LDAP authentication. For
            connections by accounts that use this plugin, client
            programs use the client-side
      <code class="literal">
       authentication_ldap_sasl_client
      </code>
      plugin.
            The client-side and server-side SASL LDAP plugins use SASL
            messages for secure transmission of credentials within the
            LDAP protocol, to avoid sending the cleartext password
            between the MySQL client and server.
     </p>
     <p>
      On Microsoft Windows platforms, both the server plugin and
            the client plugin are supported for SASL-based LDAP
            authentication.
     </p>
    </li>
   </ul>
  </div>
  <p>
   The server-side LDAP authentication plugins are included only in
        MySQL Enterprise Edition. They are not included in MySQL community distributions.
        The client-side SASL LDAP plugin is included in all
        distributions, including community distributions, and, as
        mentioned previously, the client-side
   <code class="literal">
    mysql_clear_password
   </code>
   plugin is built into the
   <code class="literal">
    libmysqlclient
   </code>
   client library, which also is
        included in all distributions. This enables clients from any
        distribution to connect to a server that has the appropriate
        server-side plugin loaded.
  </p>
  <p>
   The following sections provide installation and usage
        information specific to LDAP pluggable authentication:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      <a class="xref" href="ldap-pluggable-authentication.html#ldap-pluggable-authentication-prerequisites" title="Prerequisites for LDAP Pluggable Authentication">
       Prerequisites for LDAP Pluggable Authentication
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="ldap-pluggable-authentication.html#ldap-pluggable-authentication-process" title="How LDAP Authentication of MySQL Users Works">
       How LDAP Authentication of MySQL Users Works
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="ldap-pluggable-authentication.html#ldap-pluggable-authentication-installation" title="Installing LDAP Pluggable Authentication">
       Installing LDAP Pluggable Authentication
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="ldap-pluggable-authentication.html#ldap-pluggable-authentication-uninstallation" title="Uninstalling LDAP Pluggable Authentication">
       Uninstalling LDAP Pluggable Authentication
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="ldap-pluggable-authentication.html#ldap-pluggable-authentication-ldap-conf" title="LDAP Pluggable Authentication and ldap.conf">
       LDAP Pluggable Authentication and ldap.conf
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="ldap-pluggable-authentication.html#ldap-pluggable-authentication-timeouts" title="Setting Timeouts for LDAP Pluggable Authentication">
       Setting Timeouts for LDAP Pluggable Authentication
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="ldap-pluggable-authentication.html#ldap-pluggable-authentication-usage" title="Using LDAP Pluggable Authentication">
       Using LDAP Pluggable Authentication
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="ldap-pluggable-authentication.html#ldap-pluggable-authentication-usage-simple" title="Simple LDAP Authentication (Without Proxying)">
       Simple LDAP Authentication (Without Proxying)
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="ldap-pluggable-authentication.html#ldap-pluggable-authentication-usage-sasl" title="SASL-Based LDAP Authentication (Without Proxying)">
       SASL-Based LDAP Authentication (Without Proxying)
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="ldap-pluggable-authentication.html#ldap-pluggable-authentication-usage-proxying" title="LDAP Authentication with Proxying">
       LDAP Authentication with Proxying
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="ldap-pluggable-authentication.html#ldap-pluggable-authentication-usage-group-mapping" title="LDAP Authentication Group Preference and Mapping Specification">
       LDAP Authentication Group Preference and Mapping Specification
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="ldap-pluggable-authentication.html#ldap-pluggable-authentication-usage-user-dn-suffix" title="LDAP Authentication User DN Suffixes">
       LDAP Authentication User DN Suffixes
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="ldap-pluggable-authentication.html#ldap-pluggable-authentication-auth-methods" title="LDAP Authentication Methods">
       LDAP Authentication Methods
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="ldap-pluggable-authentication.html#ldap-pluggable-authentication-gssapi" title="The GSSAPI/Kerberos Authentication Method">
       The GSSAPI/Kerberos Authentication Method
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="ldap-pluggable-authentication.html#ldap-pluggable-authentication-ldap-referral" title="LDAP Search Referral">
       LDAP Search Referral
      </a>
     </p>
    </li>
   </ul>
  </div>
  <p>
   For general information about pluggable authentication in MySQL,
        see
   <a class="xref" href="pluggable-authentication.html" title="8.2.17 Pluggable Authentication">
    Section 8.2.17, “Pluggable Authentication”
   </a>
   . For information
        about the
   <code class="literal">
    mysql_clear_password
   </code>
   plugin, see
   <a class="xref" href="cleartext-pluggable-authentication.html" title="8.4.1.4 Client-Side Cleartext Pluggable Authentication">
    Section 8.4.1.4, “Client-Side Cleartext Pluggable Authentication”
   </a>
   . For proxy
        user information, see
   <a class="xref" href="proxy-users.html" title="8.2.19 Proxy Users">
    Section 8.2.19, “Proxy Users”
   </a>
   .
  </p>
  <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
   <div class="admon-title">
    Note
   </div>
   <p>
    If your system supports PAM and permits LDAP as a PAM
          authentication method, another way to use LDAP for MySQL user
          authentication is to use the server-side
    <code class="literal">
     authentication_pam
    </code>
    plugin. See
    <a class="xref" href="pam-pluggable-authentication.html" title="8.4.1.5 PAM Pluggable Authentication">
     Section 8.4.1.5, “PAM Pluggable Authentication”
    </a>
    .
   </p>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="ldap-pluggable-authentication-prerequisites">
       </a>
       Prerequisites for LDAP Pluggable Authentication
      </h5>
     </div>
    </div>
   </div>
   <p>
    To use LDAP pluggable authentication for MySQL, these
          prerequisites must be satisfied:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       An LDAP server must be available for the LDAP
              authentication plugins to communicate with.
      </p>
     </li>
     <li class="listitem">
      <p>
       LDAP users to be authenticated by MySQL must be present in
              the directory managed by the LDAP server.
      </p>
     </li>
     <li class="listitem">
      <p>
       An LDAP client library must be available on systems where
              the server-side
       <code class="literal">
        authentication_ldap_sasl
       </code>
       or
       <code class="literal">
        authentication_ldap_simple
       </code>
       plugin is
              used. Currently, supported libraries are the Windows
              native LDAP library, or the OpenLDAP library on
              non-Windows systems.
      </p>
     </li>
     <li class="listitem">
      <p>
       To use SASL-based LDAP authentication:
      </p>
      <div class="itemizedlist">
       <ul class="itemizedlist" style="list-style-type: circle; ">
        <li class="listitem">
         <p>
          The LDAP server must be configured to communicate with
                  a SASL server.
         </p>
        </li>
        <li class="listitem">
         <p>
          A SASL client library must be available on systems
                  where the client-side
          <code class="literal">
           authentication_ldap_sasl_client
          </code>
          plugin is used. Currently, the only supported library
                  is the Cyrus SASL library.
         </p>
        </li>
        <li class="listitem">
         <p>
          To use a particular SASL authentication method, any
                  other services required by that method must be
                  available. For example, to use GSSAPI/Kerberos, a
                  GSSAPI library and Kerberos services must be
                  available.
         </p>
        </li>
       </ul>
      </div>
     </li>
    </ul>
   </div>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="ldap-pluggable-authentication-process">
       </a>
       How LDAP Authentication of MySQL Users Works
      </h5>
     </div>
    </div>
   </div>
   <p>
    This section provides an overview of how MySQL and LDAP work
          together to authenticate MySQL users. For examples showing how
          to set up MySQL accounts to use specific LDAP authentication
          plugins, see
    <a class="xref" href="ldap-pluggable-authentication.html#ldap-pluggable-authentication-usage" title="Using LDAP Pluggable Authentication">
     Using LDAP Pluggable Authentication
    </a>
    . For
          information about authentication methods available to the LDAP
          plugins, see
    <a class="xref" href="ldap-pluggable-authentication.html#ldap-pluggable-authentication-auth-methods" title="LDAP Authentication Methods">
     LDAP Authentication Methods
    </a>
    .
   </p>
   <p>
    The client connects to the MySQL server, providing the MySQL
          client user name and a password:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       For simple LDAP authentication, the client-side and
              server-side plugins communicate the password as cleartext.
              A secure connection between the MySQL client and server is
              recommended to prevent password exposure.
      </p>
     </li>
     <li class="listitem">
      <p>
       For SASL-based LDAP authentication, the client-side and
              server-side plugins avoid sending the cleartext password
              between the MySQL client and server. For example, the
              plugins might use SASL messages for secure transmission of
              credentials within the LDAP protocol. For the GSSAPI
              authentication method, the client-side and server-side
              plugins communicate securely using Kerberos without using
              LDAP messages directly.
      </p>
     </li>
    </ul>
   </div>
   <p>
    If the client user name and host name match no MySQL account,
          the connection is rejected.
   </p>
   <p>
    If there is a matching MySQL account, authentication against
          LDAP occurs. The LDAP server looks for an entry matching the
          user and authenticates the entry against the LDAP password:
   </p>
   <a class="indexterm" name="idm46045245290928">
   </a>
   <a class="indexterm" name="idm46045245289440">
   </a>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       If the MySQL account names an LDAP user distinguished name
              (DN), LDAP authentication uses that value and the LDAP
              password provided by the client. (To associate an LDAP
              user DN with a MySQL account, include a
       <code class="literal">
        BY
       </code>
       clause that specifies an
              authentication string in the
       <a class="link" href="create-user.html" title="15.7.1.3 CREATE USER Statement">
        <code class="literal">
         CREATE
              USER
        </code>
       </a>
       statement that creates the account.)
      </p>
     </li>
     <li class="listitem">
      <p>
       If the MySQL account names no LDAP user DN, LDAP
              authentication uses the user name and LDAP password
              provided by the client. In this case, the authentication
              plugin first binds to the LDAP server using the root DN
              and password as credentials to find the user DN based on
              the client user name, then authenticates that user DN
              against the LDAP password. This bind using the root
              credentials fails if the root DN and password are set to
              incorrect values, or are empty (not set) and the LDAP
              server does not permit anonymous connections.
      </p>
     </li>
    </ul>
   </div>
   <p>
    If the LDAP server finds no match or multiple matches,
          authentication fails and the client connection is rejected.
   </p>
   <p>
    If the LDAP server finds a single match, LDAP authentication
          succeeds (assuming that the password is correct), the LDAP
          server returns the LDAP entry, and the authentication plugin
          determines the name of the authenticated user based on that
          entry:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       If the LDAP entry has a group attribute (by default, the
       <code class="literal">
        cn
       </code>
       attribute), the plugin returns its
              value as the authenticated user name.
      </p>
     </li>
     <li class="listitem">
      <p>
       If the LDAP entry has no group attribute, the
              authentication plugin returns the client user name as the
              authenticated user name.
      </p>
     </li>
    </ul>
   </div>
   <p>
    The MySQL server compares the client user name with the
          authenticated user name to determine whether proxying occurs
          for the client session:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       If the names are the same, no proxying occurs: The MySQL
              account matching the client user name is used for
              privilege checking.
      </p>
     </li>
     <li class="listitem">
      <p>
       If the names differ, proxying occurs: MySQL looks for an
              account matching the authenticated user name. That account
              becomes the proxied user, which is used for privilege
              checking. The MySQL account that matched the client user
              name is treated as the external proxy user.
      </p>
     </li>
    </ul>
   </div>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="ldap-pluggable-authentication-installation">
       </a>
       Installing LDAP Pluggable Authentication
      </h5>
     </div>
    </div>
   </div>
   <p>
    This section describes how to install the server-side LDAP
          authentication plugins. For general information about
          installing plugins, see
    <a class="xref" href="plugin-loading.html" title="7.6.1 Installing and Uninstalling Plugins">
     Section 7.6.1, “Installing and Uninstalling Plugins”
    </a>
    .
   </p>
   <p>
    To be usable by the server, the plugin library files must be
          located in the MySQL plugin directory (the directory named by
          the
    <a class="link" href="server-system-variables.html#sysvar_plugin_dir">
     <code class="literal">
      plugin_dir
     </code>
    </a>
    system
          variable). If necessary, configure the plugin directory
          location by setting the value of
    <a class="link" href="server-system-variables.html#sysvar_plugin_dir">
     <code class="literal">
      plugin_dir
     </code>
    </a>
    at server startup.
   </p>
   <p>
    The server-side plugin library file base names are
    <code class="literal">
     authentication_ldap_simple
    </code>
    and
    <code class="literal">
     authentication_ldap_sasl
    </code>
    . The file name
          suffix differs per platform (for example,
    <code class="filename">
     .so
    </code>
    for Unix and Unix-like systems,
    <code class="filename">
     .dll
    </code>
    for Windows).
   </p>
   <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
    <div class="admon-title">
     Note
    </div>
    <p>
     On Microsoft Windows, the server plugin for SASL-based LDAP
            authentication is not supported, but the client plugin is
            supported. On other platforms, both the server and client
            plugins are supported.
    </p>
   </div>
   <p>
    To load the plugins at server startup, use
    <a class="link" href="server-options.html#option_mysqld_plugin-load-add">
     <code class="option">
      --plugin-load-add
     </code>
    </a>
    options to
          name the library files that contain them. With this
          plugin-loading method, the options must be given each time the
          server starts. Also, specify values for any plugin-provided
          system variables you wish to configure.
   </p>
   <p>
    Each server-side LDAP plugin exposes a set of system variables
          that enable its operation to be configured. Setting most of
          these is optional, but you must set the variables that specify
          the LDAP server host (so the plugin knows where to connect)
          and base distinguished name for LDAP bind operations (to limit
          the scope of searches and obtain faster searches). For details
          about all LDAP system variables, see
    <a class="xref" href="pluggable-authentication-system-variables.html" title="8.4.1.13 Pluggable Authentication System Variables">
     Section 8.4.1.13, “Pluggable Authentication System Variables”
    </a>
    .
   </p>
   <p>
    To load the plugins and set the LDAP server host and base
          distinguished name for LDAP bind operations, put lines such as
          these in your
    <code class="filename">
     my.cnf
    </code>
    file, adjusting the
    <code class="filename">
     .so
    </code>
    suffix for your platform as
          necessary:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-ini"><div class="docs-select-all right" id="sa12278739"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-ini"><span class="token selector">[mysqld]</span>
<span class="token constant">plugin-load-add</span><span class="token attr-value"><span class="token punctuation">=</span>authentication_ldap_simple.so</span>
<span class="token constant">authentication_ldap_simple_server_host</span><span class="token attr-value"><span class="token punctuation">=</span>127.0.0.1</span>
<span class="token constant">authentication_ldap_simple_bind_base_dn</span><span class="token attr-value"><span class="token punctuation">=</span>"dc=example,dc=com"</span>
<span class="token constant">plugin-load-add</span><span class="token attr-value"><span class="token punctuation">=</span>authentication_ldap_sasl.so</span>
<span class="token constant">authentication_ldap_sasl_server_host</span><span class="token attr-value"><span class="token punctuation">=</span>127.0.0.1</span>
<span class="token constant">authentication_ldap_sasl_bind_base_dn</span><span class="token attr-value"><span class="token punctuation">=</span>"dc=example,dc=com"</span></code></pre>
   </div>
   <p>
    After modifying
    <code class="filename">
     my.cnf
    </code>
    , restart the
          server to cause the new settings to take effect.
   </p>
   <p>
    Alternatively, to load the plugins at runtime, use these
          statements, adjusting the
    <code class="filename">
     .so
    </code>
    suffix for
          your platform as necessary:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa36975520"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token keyword">INSTALL</span> <span class="token keyword">PLUGIN</span> authentication_ldap_simple
  <span class="token keyword">SONAME</span> <span class="token string">'authentication_ldap_simple.so'</span><span class="token punctuation">;</span>
<span class="token keyword">INSTALL</span> <span class="token keyword">PLUGIN</span> authentication_ldap_sasl
  <span class="token keyword">SONAME</span> <span class="token string">'authentication_ldap_sasl.so'</span><span class="token punctuation">;</span></code></pre>
   </div>
   <p>
    <a class="link" href="install-plugin.html" title="15.7.4.4 INSTALL PLUGIN Statement">
     <code class="literal">
      INSTALL PLUGIN
     </code>
    </a>
    loads the plugin
          immediately, and also registers it in the
    <code class="literal">
     mysql.plugins
    </code>
    system table to cause the
          server to load it for each subsequent normal startup without
          the need for
    <a class="link" href="server-options.html#option_mysqld_plugin-load-add">
     <code class="option">
      --plugin-load-add
     </code>
    </a>
    .
   </p>
   <p>
    After installing the plugins at runtime, the system variables
          that they expose become available and you can add settings for
          them to your
    <code class="filename">
     my.cnf
    </code>
    file to configure the
          plugins for subsequent restarts. For example:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-ini"><div class="docs-select-all right" id="sa37153604"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-ini"><span class="token selector">[mysqld]</span>
<span class="token constant">authentication_ldap_simple_server_host</span><span class="token attr-value"><span class="token punctuation">=</span>127.0.0.1</span>
<span class="token constant">authentication_ldap_simple_bind_base_dn</span><span class="token attr-value"><span class="token punctuation">=</span>"dc=example,dc=com"</span>
<span class="token constant">authentication_ldap_sasl_server_host</span><span class="token attr-value"><span class="token punctuation">=</span>127.0.0.1</span>
<span class="token constant">authentication_ldap_sasl_bind_base_dn</span><span class="token attr-value"><span class="token punctuation">=</span>"dc=example,dc=com"</span></code></pre>
   </div>
   <p>
    After modifying
    <code class="filename">
     my.cnf
    </code>
    , restart the
          server to cause the new settings to take effect.
   </p>
   <p>
    To set and persist each value at runtime rather than at
          startup, use these statements:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa96299696"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token keyword">SET</span> <span class="token keyword">PERSIST</span> authentication_ldap_simple_server_host<span class="token operator">=</span><span class="token string">'127.0.0.1'</span><span class="token punctuation">;</span>
<span class="token keyword">SET</span> <span class="token keyword">PERSIST</span> authentication_ldap_simple_bind_base_dn<span class="token operator">=</span><span class="token string">'dc=example,dc=com'</span><span class="token punctuation">;</span>
<span class="token keyword">SET</span> <span class="token keyword">PERSIST</span> authentication_ldap_sasl_server_host<span class="token operator">=</span><span class="token string">'127.0.0.1'</span><span class="token punctuation">;</span>
<span class="token keyword">SET</span> <span class="token keyword">PERSIST</span> authentication_ldap_sasl_bind_base_dn<span class="token operator">=</span><span class="token string">'dc=example,dc=com'</span><span class="token punctuation">;</span></code></pre>
   </div>
   <p>
    <a class="link" href="set-variable.html" title="15.7.6.1 SET Syntax for Variable Assignment">
     <code class="literal">
      SET
          PERSIST
     </code>
    </a>
    sets a value for the running MySQL instance.
          It also saves the value, causing it to carry over to
          subsequent server restarts. To change a value for the running
          MySQL instance without having it carry over to subsequent
          restarts, use the
    <code class="literal">
     GLOBAL
    </code>
    keyword rather
          than
    <code class="literal">
     PERSIST
    </code>
    . See
    <a class="xref" href="set-variable.html" title="15.7.6.1 SET Syntax for Variable Assignment">
     Section 15.7.6.1, “SET Syntax for Variable Assignment”
    </a>
    .
   </p>
   <p>
    To verify plugin installation, examine the Information Schema
    <a class="link" href="information-schema-plugins-table.html" title="28.3.22 The INFORMATION_SCHEMA PLUGINS Table">
     <code class="literal">
      PLUGINS
     </code>
    </a>
    table or use the
    <a class="link" href="show-plugins.html" title="15.7.7.27 SHOW PLUGINS Statement">
     <code class="literal">
      SHOW PLUGINS
     </code>
    </a>
    statement (see
    <a class="xref" href="obtaining-plugin-information.html" title="7.6.2 Obtaining Server Plugin Information">
     Section 7.6.2, “Obtaining Server Plugin Information”
    </a>
    ). For example:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa52778819"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token prompt">mysql&gt;</span> <span class="token keyword">SELECT</span> PLUGIN_NAME<span class="token punctuation">,</span> PLUGIN_STATUS
       <span class="token keyword">FROM</span> INFORMATION_SCHEMA<span class="token punctuation">.</span><span class="token keyword">PLUGINS</span>
       <span class="token keyword">WHERE</span> PLUGIN_NAME <span class="token operator">LIKE</span> <span class="token string">'%ldap%'</span><span class="token punctuation">;</span>
<span class="token output"><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span></span>
<span class="token output"><span class="token punctuation">|</span> PLUGIN_NAME                <span class="token punctuation">|</span> PLUGIN_STATUS <span class="token punctuation">|</span></span>
<span class="token output"><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span></span>
<span class="token output"><span class="token punctuation">|</span> authentication_ldap_sasl   <span class="token punctuation">|</span> ACTIVE        <span class="token punctuation">|</span></span>
<span class="token output"><span class="token punctuation">|</span> authentication_ldap_simple <span class="token punctuation">|</span> ACTIVE        <span class="token punctuation">|</span></span>
<span class="token output"><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span></span></code></pre>
   </div>
   <p>
    If a plugin fails to initialize, check the server error log
          for diagnostic messages.
   </p>
   <p>
    To associate MySQL accounts with an LDAP plugin, see
    <a class="xref" href="ldap-pluggable-authentication.html#ldap-pluggable-authentication-usage" title="Using LDAP Pluggable Authentication">
     Using LDAP Pluggable Authentication
    </a>
    .
   </p>
   <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
    <div class="admon-title">
     Additional Notes for SELinux
    </div>
    <a class="indexterm" name="idm46045245232496">
    </a>
    <p>
     On systems running EL6 or EL that have SELinux enabled,
            changes to the SELinux policy are required to enable the
            MySQL LDAP plugins to communicate with the LDAP service:
    </p>
    <div class="orderedlist">
     <ol class="orderedlist" type="1">
      <li class="listitem">
       <p>
        Create a file
        <code class="filename">
         mysqlldap.te
        </code>
        with
                these contents:
       </p>
       <div class="copytoclipboard-wrapper">
        <pre class="programlisting language-simple"><div class="docs-select-all right" id="sa41818513"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-simple">module mysqlldap 1<span class="token punctuation">.</span>0<span class="token punctuation">;</span>

require <span class="token punctuation">{</span>
        type ldap_port_t<span class="token punctuation">;</span>
        type mysqld_t<span class="token punctuation">;</span>
        class tcp_socket name_connect<span class="token punctuation">;</span>
<span class="token punctuation">}</span>

<span class="token comment" spellcheck="true">#============= mysqld_t ==============</span>

allow mysqld_t ldap_port_t<span class="token operator">:</span>tcp_socket name_connect<span class="token punctuation">;</span></code></pre>
       </div>
      </li>
      <li class="listitem">
       <p>
        Compile the security policy module into a binary
                representation:
       </p>
       <div class="copytoclipboard-wrapper">
        <pre class="programlisting one-line language-terminal"><div class="docs-select-all right" id="sa32673821"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal">checkmodule <span class="token property">-M</span> <span class="token property">-m</span> mysqlldap<span class="token punctuation">.</span>te <span class="token property">-o</span> mysqlldap<span class="token punctuation">.</span>mod</code></pre>
       </div>
      </li>
      <li class="listitem">
       <p>
        Create an SELinux policy module package:
       </p>
       <div class="copytoclipboard-wrapper">
        <pre class="programlisting one-line language-terminal"><div class="docs-select-all right" id="sa22979606"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal">semodule_package <span class="token property">-m</span> mysqlldap<span class="token punctuation">.</span>mod  <span class="token property">-o</span> mysqlldap<span class="token punctuation">.</span>pp</code></pre>
       </div>
      </li>
      <li class="listitem">
       <p>
        Install the module package:
       </p>
       <div class="copytoclipboard-wrapper">
        <pre class="programlisting one-line language-terminal"><div class="docs-select-all right" id="sa88637431"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal">semodule <span class="token property">-i</span> mysqlldap<span class="token punctuation">.</span>pp</code></pre>
       </div>
      </li>
      <li class="listitem">
       <p>
        When the SELinux policy changes have been made, restart
                the MySQL server:
       </p>
       <div class="copytoclipboard-wrapper">
        <pre class="programlisting one-line language-terminal"><div class="docs-select-all right" id="sa72346311"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal">service mysqld restart</code></pre>
       </div>
      </li>
     </ol>
    </div>
   </div>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="ldap-pluggable-authentication-uninstallation">
       </a>
       Uninstalling LDAP Pluggable Authentication
      </h5>
     </div>
    </div>
   </div>
   <p>
    The method used to uninstall the LDAP authentication plugins
          depends on how you installed them:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       If you installed the plugins at server startup using
       <a class="link" href="server-options.html#option_mysqld_plugin-load-add">
        <code class="option">
         --plugin-load-add
        </code>
       </a>
       options,
              restart the server without those options.
      </p>
     </li>
     <li class="listitem">
      <p>
       If you installed the plugins at runtime using
       <a class="link" href="install-plugin.html" title="15.7.4.4 INSTALL PLUGIN Statement">
        <code class="literal">
         INSTALL PLUGIN
        </code>
       </a>
       , they remain
              installed across server restarts. To uninstall them, use
       <a class="link" href="uninstall-plugin.html" title="15.7.4.6 UNINSTALL PLUGIN Statement">
        <code class="literal">
         UNINSTALL PLUGIN
        </code>
       </a>
       :
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa48573854"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token keyword">UNINSTALL</span> <span class="token keyword">PLUGIN</span> authentication_ldap_simple<span class="token punctuation">;</span>
<span class="token keyword">UNINSTALL</span> <span class="token keyword">PLUGIN</span> authentication_ldap_sasl<span class="token punctuation">;</span></code></pre>
      </div>
     </li>
    </ul>
   </div>
   <p>
    In addition, remove from your
    <code class="filename">
     my.cnf
    </code>
    file
          any startup options that set LDAP plugin-related system
          variables. If you used
    <a class="link" href="set-variable.html" title="15.7.6.1 SET Syntax for Variable Assignment">
     <code class="literal">
      SET
          PERSIST
     </code>
    </a>
    to persist LDAP system variables, use
    <a class="link" href="reset-persist.html" title="15.7.8.7 RESET PERSIST Statement">
     <code class="literal">
      RESET PERSIST
     </code>
    </a>
    to remove the
          settings.
   </p>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="ldap-pluggable-authentication-ldap-conf">
       </a>
       LDAP Pluggable Authentication and ldap.conf
      </h5>
     </div>
    </div>
   </div>
   <a class="indexterm" name="idm46045245205504">
   </a>
   <a class="indexterm" name="idm46045245204464">
   </a>
   <p>
    For installations that use OpenLDAP, the
    <code class="filename">
     ldap.conf
    </code>
    file provides global defaults
          for LDAP clients. Options can be set in this file to affect
          LDAP clients, including the LDAP authentication plugins.
          OpenLDAP uses configuration options in this order of
          precedence:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       Configuration specified by the LDAP client.
      </p>
     </li>
     <li class="listitem">
      <p>
       Configuration specified in the
       <code class="filename">
        ldap.conf
       </code>
       file. To disable use of
              this file, set the
       <code class="literal">
        LDAPNOINIT
       </code>
       environment variable.
      </p>
      <a class="indexterm" name="idm46045245198208">
      </a>
      <a class="indexterm" name="idm46045245197120">
      </a>
     </li>
     <li class="listitem">
      <p>
       OpenLDAP library built-in defaults.
      </p>
     </li>
    </ul>
   </div>
   <p>
    If the library defaults or
    <code class="filename">
     ldap.conf
    </code>
    values do not yield appropriate option values, an LDAP
          authentication plugin may be able to set related variables to
          affect the LDAP configuration directly. For example, LDAP
          plugins can override
    <code class="filename">
     ldap.conf
    </code>
    for
          parameters such as these:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       TLS configuration: System variables are available to
              enable TLS and control CA configuration, such as
       <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_ldap_simple_tls">
        <code class="literal">
         authentication_ldap_simple_tls
        </code>
       </a>
       and
       <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_ldap_simple_ca_path">
        <code class="literal">
         authentication_ldap_simple_ca_path
        </code>
       </a>
       for simple LDAP authentication, and
       <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_ldap_sasl_tls">
        <code class="literal">
         authentication_ldap_sasl_tls
        </code>
       </a>
       and
       <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_ldap_sasl_ca_path">
        <code class="literal">
         authentication_ldap_sasl_ca_path
        </code>
       </a>
       for SASL LDAP authentication.
      </p>
     </li>
     <li class="listitem">
      <p>
       LDAP referral. See
       <a class="xref" href="ldap-pluggable-authentication.html#ldap-pluggable-authentication-ldap-referral" title="LDAP Search Referral">
        LDAP Search Referral
       </a>
       .
      </p>
     </li>
    </ul>
   </div>
   <p>
    For more information about
    <code class="filename">
     ldap.conf
    </code>
    consult the
    <code class="literal">
     ldap.conf(5)
    </code>
    man page.
   </p>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="ldap-pluggable-authentication-timeouts">
       </a>
       Setting Timeouts for LDAP Pluggable Authentication
      </h5>
     </div>
    </div>
   </div>
   <p>
    For MySQL accounts to connect to a MySQL server using LDAP
          pluggable authentication, the LDAP server must be available
          and operational. The interaction between the MySQL and LDAP
          servers involves two steps. First, the MySQL server
          establishes a connection to the LDAP server over TCP. Second,
          the MySQL server sends an LDAP binding request over the
          connection to the LDAP server and waits for a reply before
          authenticating the account. If either step fails, the MySQL
          account cannot connect to the MySQL server.
   </p>
   <p>
    Short-duration timeouts that supersede a host system's
          timeout values are applied to both the connection and response
          steps by default. In all cases, the account user receives
          notification that their attempt to connect to MySQL is denied
          if the timeout expires. Client-side and server-side logging
          can provide additional information. On the client side, set
          the following environmental variable to elevate the detail
          level and then restart MySQL client:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-ini"><div class="docs-select-all right" id="sa34831305"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-ini"><span class="token constant">AUTHENTICATION_LDAP_CLIENT_LOG</span><span class="token attr-value"><span class="token punctuation">=</span>5</span>
export AUTHENTICATION_LDAP_CLIENT_LOG</code></pre>
   </div>
   <p>
    The following system variables support default timeouts for
          SASL-based and simple LDAP authentication on Linux platforms
          only.
   </p>
   <div class="table">
    <a name="idm46045245177536">
    </a>
    <p class="title">
     <b>
      Table 8.22 System variables for SASL-based and simple LDAP Authentication
     </b>
    </p>
    <div class="table-contents">
     <table summary="System variables used for simple and SASL-based LDAP password authentication.">
      <colgroup>
       <col style="width: 75%"/>
       <col style="width: 25%"/>
      </colgroup>
      <thead>
       <tr>
        <th>
         System Variable Name
        </th>
        <th>
         Default Timeout Value
        </th>
       </tr>
      </thead>
      <tbody>
       <tr>
        <td>
         <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_ldap_sasl_connect_timeout">
          <code class="literal">
           authentication_ldap_sasl_connect_timeout
          </code>
         </a>
        </td>
        <td>
         30 seconds
        </td>
       </tr>
       <tr>
        <td>
         <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_ldap_sasl_response_timeout">
          <code class="literal">
           authentication_ldap_sasl_response_timeout
          </code>
         </a>
        </td>
        <td>
         30 seconds
        </td>
       </tr>
       <tr>
        <td>
         <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_ldap_simple_connect_timeout">
          <code class="literal">
           authentication_ldap_simple_connect_timeout
          </code>
         </a>
        </td>
        <td>
         30 seconds
        </td>
       </tr>
       <tr>
        <td>
         <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_ldap_simple_response_timeout">
          <code class="literal">
           authentication_ldap_simple_response_timeout
          </code>
         </a>
        </td>
        <td>
         30 seconds
        </td>
       </tr>
      </tbody>
     </table>
    </div>
   </div>
   <br class="table-break"/>
   <p>
    Timeout values for LDAP authentication are adjustable at
          server startup and at runtime. If you set a timeout to zero
          using one of these variables, you effectively disengage it and
          MySQL server reverts to using the host system's default
          timeout.
   </p>
   <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
    <div class="admon-title">
     Note
    </div>
    <p>
     Under the following combination of conditions, the actual
            wait time of the
     <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_ldap_sasl_connect_timeout">
      <code class="literal">
       authentication_ldap_sasl_connect_timeout
      </code>
     </a>
     setting doubles because (internally) the server must invoke
            the TCP connection twice:
    </p>
    <div class="itemizedlist">
     <ul class="itemizedlist" style="list-style-type: disc; ">
      <li class="listitem">
       <p>
        The LDAP server is offline.
       </p>
      </li>
      <li class="listitem">
       <p>
        <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_ldap_sasl_connect_timeout">
         <code class="literal">
          authentication_ldap_sasl_connect_timeout
         </code>
        </a>
        has a value greater than zero.
       </p>
      </li>
      <li class="listitem">
       <p>
        Connection pooling is in use (specifically, the
        <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_ldap_sasl_max_pool_size">
         <code class="literal">
          authentication_ldap_sasl_max_pool_size
         </code>
        </a>
        system variable has a value greater than zero, which
                enables pooling).
       </p>
      </li>
     </ul>
    </div>
   </div>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="ldap-pluggable-authentication-usage">
       </a>
       Using LDAP Pluggable Authentication
      </h5>
     </div>
    </div>
   </div>
   <p>
    This section describes how to enable MySQL accounts to connect
          to the MySQL server using LDAP pluggable authentication. It is
          assumed that the server is running with the appropriate
          server-side plugins enabled, as described in
    <a class="xref" href="ldap-pluggable-authentication.html#ldap-pluggable-authentication-installation" title="Installing LDAP Pluggable Authentication">
     Installing LDAP Pluggable Authentication
    </a>
    ,
          and that the appropriate client-side plugins are available on
          the client host.
   </p>
   <p>
    This section does not describe LDAP configuration or
          administration. You are assumed to be familiar with those
          topics.
   </p>
   <p>
    The two server-side LDAP plugins each work with a specific
          client-side plugin:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       The server-side
       <code class="literal">
        authentication_ldap_simple
       </code>
       plugin
              performs simple LDAP authentication. For connections by
              accounts that use this plugin, client programs use the
              client-side
       <code class="literal">
        mysql_clear_password
       </code>
       plugin, which sends the password to the server as
              cleartext. No password hashing or encryption is used, so a
              secure connection between the MySQL client and server is
              recommended to prevent password exposure.
      </p>
     </li>
     <li class="listitem">
      <p>
       The server-side
       <code class="literal">
        authentication_ldap_sasl
       </code>
       plugin
              performs SASL-based LDAP authentication. For connections
              by accounts that use this plugin, client programs use the
              client-side
       <code class="literal">
        authentication_ldap_sasl_client
       </code>
       plugin.
              The client-side and server-side SASL LDAP plugins use SASL
              messages for secure transmission of credentials within the
              LDAP protocol, to avoid sending the cleartext password
              between the MySQL client and server.
      </p>
     </li>
    </ul>
   </div>
   <p>
    Overall requirements for LDAP authentication of MySQL users:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       There must be an LDAP directory entry for each user to be
              authenticated.
      </p>
     </li>
     <li class="listitem">
      <p>
       There must be a MySQL user account that specifies a
              server-side LDAP authentication plugin and optionally
              names the associated LDAP user distinguished name (DN).
              (To associate an LDAP user DN with a MySQL account,
              include a
       <code class="literal">
        BY
       </code>
       clause in the
       <a class="link" href="create-user.html" title="15.7.1.3 CREATE USER Statement">
        <code class="literal">
         CREATE USER
        </code>
       </a>
       statement that
              creates the account.) If an account names no LDAP string,
              LDAP authentication uses the user name specified by the
              client to find the LDAP entry.
      </p>
     </li>
     <li class="listitem">
      <p>
       Client programs connect using the connection method
              appropriate for the server-side authentication plugin the
              MySQL account uses. For LDAP authentication, connections
              require the MySQL user name and LDAP password. In
              addition, for accounts that use the server-side
       <code class="literal">
        authentication_ldap_simple
       </code>
       plugin,
              invoke client programs with the
       <code class="option">
        --enable-cleartext-plugin
       </code>
       option to
              enable the client-side
       <code class="literal">
        mysql_clear_password
       </code>
       plugin.
      </p>
     </li>
    </ul>
   </div>
   <p>
    The instructions here assume the following scenario:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       MySQL users
       <code class="literal">
        betsy
       </code>
       and
       <code class="literal">
        boris
       </code>
       authenticate to the LDAP entries
              for
       <code class="literal">
        betsy_ldap
       </code>
       and
       <code class="literal">
        boris_ldap
       </code>
       , respectively. (It is not
              necessary that the MySQL and LDAP user names differ. The
              use of different names in this discussion helps clarify
              whether an operation context is MySQL or LDAP.)
      </p>
     </li>
     <li class="listitem">
      <p>
       LDAP entries use the
       <code class="literal">
        uid
       </code>
       attribute to
              specify user names. This may vary depending on LDAP
              server. Some LDAP servers use the
       <code class="literal">
        cn
       </code>
       attribute for user names rather than
       <code class="literal">
        uid
       </code>
       . To change the attribute, modify
              the
       <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_ldap_simple_user_search_attr">
        <code class="literal">
         authentication_ldap_simple_user_search_attr
        </code>
       </a>
       or
       <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_ldap_sasl_user_search_attr">
        <code class="literal">
         authentication_ldap_sasl_user_search_attr
        </code>
       </a>
       system variable appropriately.
      </p>
     </li>
     <li class="listitem">
      <p>
       These LDAP entries are available in the directory managed
              by the LDAP server, to provide distinguished name values
              that uniquely identify each user:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-ini"><div class="docs-select-all right" id="sa76721930"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-ini"><span class="token constant">uid</span><span class="token attr-value"><span class="token punctuation">=</span>betsy_ldap,ou=People,dc=example,dc=com</span>
<span class="token constant">uid</span><span class="token attr-value"><span class="token punctuation">=</span>boris_ldap,ou=People,dc=example,dc=com</span></code></pre>
      </div>
     </li>
     <li class="listitem">
      <p>
       <a class="link" href="create-user.html" title="15.7.1.3 CREATE USER Statement">
        <code class="literal">
         CREATE USER
        </code>
       </a>
       statements that
              create MySQL accounts name an LDAP user in the
       <code class="literal">
        BY
       </code>
       clause, to indicate which LDAP entry
              the MySQL account authenticates against.
      </p>
     </li>
    </ul>
   </div>
   <p>
    The instructions for setting up an account that uses LDAP
          authentication depend on which server-side LDAP plugin is
          used. The following sections describe several usage scenarios.
   </p>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="ldap-pluggable-authentication-usage-simple">
       </a>
       Simple LDAP Authentication (Without Proxying)
      </h5>
     </div>
    </div>
   </div>
   <p>
    The procedure outlined in this section requires that
    <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_ldap_simple_group_search_attr">
     <code class="literal">
      authentication_ldap_simple_group_search_attr
     </code>
    </a>
    be set to an empty string, like this:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting one-line language-sql"><div class="docs-select-all right" id="sa81538395"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token keyword">SET</span> <span class="token keyword">GLOBAL</span><span class="token punctuation">.</span>authentication_ldap_simple_group_search_attr<span class="token operator">=</span><span class="token string">''</span><span class="token punctuation">;</span></code></pre>
   </div>
   <p>
    Otherwise, proxying is used by default.
   </p>
   <p>
    To set up a MySQL account for simple LDAP authentication, use
          a
    <a class="link" href="create-user.html" title="15.7.1.3 CREATE USER Statement">
     <code class="literal">
      CREATE USER
     </code>
    </a>
    statement to
          specify the
    <code class="literal">
     authentication_ldap_simple
    </code>
    plugin, optionally including the LDAP user distinguished name
          (DN), as shown here:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa270559"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token keyword">CREATE</span> <span class="token keyword">USER</span> <span class="token keyword"><em class="replaceable">user</em></span>
  <span class="token keyword">IDENTIFIED</span> <span class="token keyword">WITH</span> authentication_ldap_simple
  <span class="token punctuation">[</span><span class="token keyword">BY</span> <span class="token string">'<em class="replaceable">LDAP user DN</em>'</span><span class="token punctuation">]</span><span class="token punctuation">;</span></code></pre>
   </div>
   <p>
    Suppose that MySQL user
    <code class="literal">
     betsy
    </code>
    has this
          entry in the LDAP directory:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting one-line language-ini"><div class="docs-select-all right" id="sa78001596"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-ini"><span class="token constant">uid</span><span class="token attr-value"><span class="token punctuation">=</span>betsy_ldap,ou=People,dc=example,dc=com</span></code></pre>
   </div>
   <p>
    Then the statement to create the MySQL account for
    <code class="literal">
     betsy
    </code>
    looks like this:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa93057826"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token keyword">CREATE</span> <span class="token keyword">USER</span> <span class="token string">'betsy'</span>@<span class="token string">'localhost'</span>
  <span class="token keyword">IDENTIFIED</span> <span class="token keyword">WITH</span> authentication_ldap_simple
  <span class="token keyword">AS</span> <span class="token string">'uid=betsy_ldap,ou=People,dc=example,dc=com'</span><span class="token punctuation">;</span></code></pre>
   </div>
   <p>
    The authentication string specified in the
    <code class="literal">
     BY
    </code>
    clause does not include the LDAP
          password. That must be provided by the client user at connect
          time.
   </p>
   <p>
    Clients connect to the MySQL server by providing the MySQL
          user name and LDAP password, and by enabling the client-side
    <code class="literal">
     mysql_clear_password
    </code>
    plugin:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-terminal"><div class="docs-select-all right" id="sa34116465"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal"><span class="token prompt">$&gt; </span><span class="token command">mysql</span> <span class="token constant">--user</span><span class="token attr-value"><span class="token punctuation">=</span>betsy</span> <span class="token property">--password</span> <span class="token property">--enable-cleartext-plugin</span>
Enter password<span class="token punctuation">:</span> <em class="replaceable">betsy_ldap_password</em></code></pre>
   </div>
   <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
    <div class="admon-title">
     Note
    </div>
    <p>
     The client-side
     <code class="literal">
      mysql_clear_password
     </code>
     authentication plugin leaves the password untouched, so
            client programs send it to the MySQL server as cleartext.
            This enables the password to be passed as is to the LDAP
            server. A cleartext password is necessary to use the
            server-side LDAP library without SASL, but may be a security
            problem in some configurations. These measures minimize the
            risk:
    </p>
    <div class="itemizedlist">
     <ul class="itemizedlist" style="list-style-type: disc; ">
      <li class="listitem">
       <p>
        To make inadvertent use of the
        <code class="literal">
         mysql_clear_password
        </code>
        plugin less
                likely, MySQL clients must explicitly enable it (for
                example, with the
        <code class="option">
         --enable-cleartext-plugin
        </code>
        option). See
        <a class="xref" href="cleartext-pluggable-authentication.html" title="8.4.1.4 Client-Side Cleartext Pluggable Authentication">
         Section 8.4.1.4, “Client-Side Cleartext Pluggable Authentication”
        </a>
        .
       </p>
      </li>
      <li class="listitem">
       <p>
        To avoid password exposure with the
        <code class="literal">
         mysql_clear_password
        </code>
        plugin enabled,
                MySQL clients should connect to the MySQL server using
                an encrypted connection. See
        <a class="xref" href="using-encrypted-connections.html" title="8.3.1 Configuring MySQL to Use Encrypted Connections">
         Section 8.3.1, “Configuring MySQL to Use Encrypted Connections”
        </a>
        .
       </p>
      </li>
     </ul>
    </div>
   </div>
   <p>
    The authentication process occurs as follows:
   </p>
   <div class="orderedlist">
    <ol class="orderedlist" type="1">
     <li class="listitem">
      <p>
       The client-side plugin sends
       <code class="literal">
        betsy
       </code>
       and
       <em class="replaceable">
        <code>
         betsy_password
        </code>
       </em>
       as the client
              user name and LDAP password to the MySQL server.
      </p>
     </li>
     <li class="listitem">
      <p>
       The connection attempt matches the
       <code class="literal">
        'betsy'@'localhost'
       </code>
       account. The
              server-side LDAP plugin finds that this account has an
              authentication string of
       <code class="literal">
        'uid=betsy_ldap,ou=People,dc=example,dc=com'
       </code>
       to name the LDAP user DN. The plugin sends this string and
              the LDAP password to the LDAP server.
      </p>
     </li>
     <li class="listitem">
      <p>
       The LDAP server finds the LDAP entry for
       <code class="literal">
        betsy_ldap
       </code>
       and the password matches, so
              LDAP authentication succeeds.
      </p>
     </li>
     <li class="listitem">
      <p>
       The LDAP entry has no group attribute, so the server-side
              plugin returns the client user name
              (
       <code class="literal">
        betsy
       </code>
       ) as the authenticated user. This
              is the same user name supplied by the client, so no
              proxying occurs and the client session uses the
       <code class="literal">
        'betsy'@'localhost'
       </code>
       account for
              privilege checking.
      </p>
     </li>
    </ol>
   </div>
   <p>
    Had the
    <a class="link" href="create-user.html" title="15.7.1.3 CREATE USER Statement">
     <code class="literal">
      CREATE USER
     </code>
    </a>
    statement
          contained no
    <code class="literal">
     BY
    </code>
    clause to specify the
    <code class="literal">
     betsy_ldap
    </code>
    LDAP distinguished name,
          authentication attempts would use the user name provided by
          the client (in this case,
    <code class="literal">
     betsy
    </code>
    ). In the
          absence of an LDAP entry for
    <code class="literal">
     betsy
    </code>
    ,
          authentication would fail.
   </p>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="ldap-pluggable-authentication-usage-sasl">
       </a>
       SASL-Based LDAP Authentication (Without Proxying)
      </h5>
     </div>
    </div>
   </div>
   <p>
    The procedure outlined in this section requires that
    <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_ldap_sasl_group_search_attr">
     <code class="literal">
      authentication_ldap_sasl_group_search_attr
     </code>
    </a>
    be set to an empty string, like this:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting one-line language-sql"><div class="docs-select-all right" id="sa95433871"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token keyword">SET</span> <span class="token keyword">GLOBAL</span><span class="token punctuation">.</span>authentication_ldap_sasl_group_search_attr<span class="token operator">=</span><span class="token string">''</span><span class="token punctuation">;</span></code></pre>
   </div>
   <p>
    Otherwise, proxying is used by default.
   </p>
   <p>
    To set up a MySQL account for SALS LDAP authentication, use a
    <a class="link" href="create-user.html" title="15.7.1.3 CREATE USER Statement">
     <code class="literal">
      CREATE USER
     </code>
    </a>
    statement to
          specify the
    <code class="literal">
     authentication_ldap_sasl
    </code>
    plugin, optionally including the LDAP user distinguished name
          (DN), as shown here:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa36201370"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token keyword">CREATE</span> <span class="token keyword">USER</span> <span class="token keyword"><em class="replaceable">user</em></span>
  <span class="token keyword">IDENTIFIED</span> <span class="token keyword">WITH</span> authentication_ldap_sasl
  <span class="token punctuation">[</span><span class="token keyword">BY</span> <span class="token string">'<em class="replaceable">LDAP user DN</em>'</span><span class="token punctuation">]</span><span class="token punctuation">;</span></code></pre>
   </div>
   <p>
    Suppose that MySQL user
    <code class="literal">
     boris
    </code>
    has this
          entry in the LDAP directory:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting one-line language-ini"><div class="docs-select-all right" id="sa85409826"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-ini"><span class="token constant">uid</span><span class="token attr-value"><span class="token punctuation">=</span>boris_ldap,ou=People,dc=example,dc=com</span></code></pre>
   </div>
   <p>
    Then the statement to create the MySQL account for
    <code class="literal">
     boris
    </code>
    looks like this:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa37646472"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token keyword">CREATE</span> <span class="token keyword">USER</span> <span class="token string">'boris'</span>@<span class="token string">'localhost'</span>
  <span class="token keyword">IDENTIFIED</span> <span class="token keyword">WITH</span> authentication_ldap_sasl
  <span class="token keyword">AS</span> <span class="token string">'uid=boris_ldap,ou=People,dc=example,dc=com'</span><span class="token punctuation">;</span></code></pre>
   </div>
   <p>
    The authentication string specified in the
    <code class="literal">
     BY
    </code>
    clause does not include the LDAP
          password. That must be provided by the client user at connect
          time.
   </p>
   <p>
    Clients connect to the MySQL server by providing the MySQL
          user name and LDAP password:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-terminal"><div class="docs-select-all right" id="sa96294778"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal"><span class="token prompt">$&gt; </span><span class="token command">mysql</span> <span class="token constant">--user</span><span class="token attr-value"><span class="token punctuation">=</span>boris</span> <span class="token property">--password</span>
Enter password<span class="token punctuation">:</span> <em class="replaceable">boris_ldap_password</em></code></pre>
   </div>
   <p>
    For the server-side
    <code class="literal">
     authentication_ldap_sasl
    </code>
    plugin, clients
          use the client-side
    <code class="literal">
     authentication_ldap_sasl_client
    </code>
    plugin. If
          a client program does not find the client-side plugin, specify
          a
    <a class="link" href="connection-options.html#option_general_plugin-dir">
     <code class="option">
      --plugin-dir
     </code>
    </a>
    option that
          names the directory where the plugin library file is
          installed.
   </p>
   <p>
    The authentication process for
    <code class="literal">
     boris
    </code>
    is
          similar to that previously described for
    <code class="literal">
     betsy
    </code>
    with simple LDAP authentication,
          except that the client-side and server-side SASL LDAP plugins
          use SASL messages for secure transmission of credentials
          within the LDAP protocol, to avoid sending the cleartext
          password between the MySQL client and server.
   </p>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="ldap-pluggable-authentication-usage-proxying">
       </a>
       LDAP Authentication with Proxying
      </h5>
     </div>
    </div>
   </div>
   <a class="indexterm" name="idm46045245051024">
   </a>
   <p>
    LDAP authentication plugins support proxying, enabling a user
          to connect to the MySQL server as one user but assume the
          privileges of a different user. This section describes basic
          LDAP plugin proxy support. The LDAP plugins also support
          specification of group preference and proxy user mapping; see
    <a class="xref" href="ldap-pluggable-authentication.html#ldap-pluggable-authentication-usage-group-mapping" title="LDAP Authentication Group Preference and Mapping Specification">
     LDAP Authentication Group Preference and Mapping Specification
    </a>
    .
   </p>
   <p>
    The proxying implementation described here is based on use of
          LDAP group attribute values to map connecting MySQL users who
          authenticate using LDAP onto other MySQL accounts that define
          different sets of privileges. Users do not connect directly
          through the accounts that define the privileges. Instead, they
          connect through a default proxy account authenticated with
          LDAP, such that all external logins are mapped to the proxied
          MySQL accounts that hold the privileges. Any user who connects
          using the proxy account is mapped to one of those proxied
          MySQL accounts, the privileges for which determine the
          database operations permitted to the external user.
   </p>
   <p>
    The instructions here assume the following scenario:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       LDAP entries use the
       <code class="literal">
        uid
       </code>
       and
       <code class="literal">
        cn
       </code>
       attributes to specify user name and
              group values, respectively. To use different user and
              group attribute names, set the appropriate plugin-specific
              system variables:
      </p>
      <div class="itemizedlist">
       <ul class="itemizedlist" style="list-style-type: circle; ">
        <li class="listitem">
         <p>
          For the
          <code class="literal">
           authentication_ldap_simple
          </code>
          plugin: Set
          <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_ldap_simple_user_search_attr">
           <code class="literal">
            authentication_ldap_simple_user_search_attr
           </code>
          </a>
          and
          <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_ldap_simple_group_search_attr">
           <code class="literal">
            authentication_ldap_simple_group_search_attr
           </code>
          </a>
          .
         </p>
        </li>
        <li class="listitem">
         <p>
          For the
          <code class="literal">
           authentication_ldap_sasl
          </code>
          plugin: Set
          <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_ldap_sasl_user_search_attr">
           <code class="literal">
            authentication_ldap_sasl_user_search_attr
           </code>
          </a>
          and
          <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_ldap_sasl_group_search_attr">
           <code class="literal">
            authentication_ldap_sasl_group_search_attr
           </code>
          </a>
          .
         </p>
        </li>
       </ul>
      </div>
     </li>
     <li class="listitem">
      <p>
       These LDAP entries are available in the directory managed
              by the LDAP server, to provide distinguished name values
              that uniquely identify each user:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-ini"><div class="docs-select-all right" id="sa18055174"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-ini"><span class="token constant">uid</span><span class="token attr-value"><span class="token punctuation">=</span>basha,ou=People,dc=example,dc=com,cn=accounting</span>
<span class="token constant">uid</span><span class="token attr-value"><span class="token punctuation">=</span>basil,ou=People,dc=example,dc=com,cn=front_office</span></code></pre>
      </div>
      <p>
       At connect time, the group attribute values become the
              authenticated user names, so they name the
       <code class="literal">
        accounting
       </code>
       and
       <code class="literal">
        front_office
       </code>
       proxied accounts.
      </p>
     </li>
     <li class="listitem">
      <p>
       The examples assume use of SASL LDAP authentication. Make
              the appropriate adjustments for simple LDAP
              authentication.
      </p>
     </li>
    </ul>
   </div>
   <p>
    Create the default proxy MySQL account:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa82514406"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token keyword">CREATE</span> <span class="token keyword">USER</span> <span class="token string">''</span>@<span class="token string">'%'</span>
  <span class="token keyword">IDENTIFIED</span> <span class="token keyword">WITH</span> authentication_ldap_sasl<span class="token punctuation">;</span></code></pre>
   </div>
   <p>
    The proxy account definition has no
    <code class="literal">
     AS
          '
     <em class="replaceable">
      <code>
       auth_string
      </code>
     </em>
     '
    </code>
    clause to
          name an LDAP user DN. Thus:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       When a client connects, the client user name becomes the
              LDAP user name to search for.
      </p>
     </li>
     <li class="listitem">
      <p>
       The matching LDAP entry is expected to include a group
              attribute naming the proxied MySQL account that defines
              the privileges the client should have.
      </p>
     </li>
    </ul>
   </div>
   <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
    <div class="admon-title">
     Note
    </div>
    <p>
     If your MySQL installation has anonymous users, they might
            conflict with the default proxy user. For more information
            about this issue, and ways of dealing with it, see
     <a class="xref" href="proxy-users.html#proxy-users-conflicts" title="Default Proxy User and Anonymous User Conflicts">
      Default Proxy User and Anonymous User Conflicts
     </a>
     .
    </p>
   </div>
   <p>
    Create the proxied accounts and grant to each one the
          privileges it should have:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa16503762"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token keyword">CREATE</span> <span class="token keyword">USER</span> <span class="token string">'accounting'</span>@<span class="token string">'localhost'</span>
  <span class="token keyword">IDENTIFIED</span> <span class="token keyword">WITH</span> mysql_no_login<span class="token punctuation">;</span>
<span class="token keyword">CREATE</span> <span class="token keyword">USER</span> <span class="token string">'front_office'</span>@<span class="token string">'localhost'</span>
  <span class="token keyword">IDENTIFIED</span> <span class="token keyword">WITH</span> mysql_no_login<span class="token punctuation">;</span>

<span class="token keyword">GRANT</span> <span class="token keyword">ALL</span> <span class="token keyword">PRIVILEGES</span>
  <span class="token keyword">ON</span> accountingdb<span class="token punctuation">.</span><span class="token operator">*</span>
  <span class="token keyword">TO</span> <span class="token string">'accounting'</span>@<span class="token string">'localhost'</span><span class="token punctuation">;</span>
<span class="token keyword">GRANT</span> <span class="token keyword">ALL</span> <span class="token keyword">PRIVILEGES</span>
  <span class="token keyword">ON</span> frontdb<span class="token punctuation">.</span><span class="token operator">*</span>
  <span class="token keyword">TO</span> <span class="token string">'front_office'</span>@<span class="token string">'localhost'</span><span class="token punctuation">;</span></code></pre>
   </div>
   <p>
    The proxied accounts use the
    <code class="literal">
     mysql_no_login
    </code>
    authentication plugin to prevent clients from using the
          accounts to log in directly to the MySQL server. Instead,
          users who authenticate using LDAP are expected to use the
          default
    <code class="literal">
     ''@'%'
    </code>
    proxy account. (This assumes
          that the
    <code class="literal">
     mysql_no_login
    </code>
    plugin is
          installed. For instructions, see
    <a class="xref" href="no-login-pluggable-authentication.html" title="8.4.1.9 No-Login Pluggable Authentication">
     Section 8.4.1.9, “No-Login Pluggable Authentication”
    </a>
    .) For
          alternative methods of protecting proxied accounts against
          direct use, see
    <a class="xref" href="proxy-users.html#preventing-proxied-account-direct-login" title="Preventing Direct Login to Proxied Accounts">
     Preventing Direct Login to Proxied Accounts
    </a>
    .
   </p>
   <p>
    Grant to the proxy account the
    <a class="link" href="privileges-provided.html#priv_proxy">
     <code class="literal">
      PROXY
     </code>
    </a>
    privilege for each
          proxied account:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa58011275"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token keyword">GRANT</span> <span class="token keyword">PROXY</span>
  <span class="token keyword">ON</span> <span class="token string">'accounting'</span>@<span class="token string">'localhost'</span>
  <span class="token keyword">TO</span> <span class="token string">''</span>@<span class="token string">'%'</span><span class="token punctuation">;</span>
<span class="token keyword">GRANT</span> <span class="token keyword">PROXY</span>
  <span class="token keyword">ON</span> <span class="token string">'front_office'</span>@<span class="token string">'localhost'</span>
  <span class="token keyword">TO</span> <span class="token string">''</span>@<span class="token string">'%'</span><span class="token punctuation">;</span></code></pre>
   </div>
   <p>
    Use the
    <a class="link" href="mysql.html" title="6.5.1 mysql — The MySQL Command-Line Client">
     <span class="command">
      <strong>
       mysql
      </strong>
     </span>
    </a>
    command-line client to
          connect to the MySQL server as
    <code class="literal">
     basha
    </code>
    .
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-terminal"><div class="docs-select-all right" id="sa91662328"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal"><span class="token prompt">$&gt; </span><span class="token command">mysql</span> <span class="token constant">--user</span><span class="token attr-value"><span class="token punctuation">=</span>basha</span> <span class="token property">--password</span>
Enter password<span class="token punctuation">:</span> <em class="replaceable">basha_password</em> <span class="token punctuation"></span><em class="replaceable"><span class="token punctuation">(</span>basha LDAP password<span class="token punctuation">)</span></em><span class="token punctuation"></span></code></pre>
   </div>
   <p>
    Authentication occurs as follows:
   </p>
   <div class="orderedlist">
    <ol class="orderedlist" type="1">
     <li class="listitem">
      <p>
       The server authenticates the connection using the default
       <code class="literal">
        ''@'%'
       </code>
       proxy account, for client user
       <code class="literal">
        basha
       </code>
       .
      </p>
     </li>
     <li class="listitem">
      <p>
       The matching LDAP entry is:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting one-line language-ini"><div class="docs-select-all right" id="sa21691612"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-ini"><span class="token constant">uid</span><span class="token attr-value"><span class="token punctuation">=</span>basha,ou=People,dc=example,dc=com,cn=accounting</span></code></pre>
      </div>
     </li>
     <li class="listitem">
      <p>
       The matching LDAP entry has group attribute
       <code class="literal">
        cn=accounting
       </code>
       , so
       <code class="literal">
        accounting
       </code>
       becomes the authenticated
              proxied user.
      </p>
     </li>
     <li class="listitem">
      <p>
       The authenticated user differs from the client user name
       <code class="literal">
        basha
       </code>
       , with the result that
       <code class="literal">
        basha
       </code>
       is treated as a proxy for
       <code class="literal">
        accounting
       </code>
       , and
       <code class="literal">
        basha
       </code>
       assumes the privileges of the
              proxied
       <code class="literal">
        accounting
       </code>
       account. The
              following query returns output as shown:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa89426664"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token prompt">mysql&gt;</span> <span class="token keyword">SELECT</span> <span class="token function">USER</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">,</span> <span class="token function">CURRENT_USER</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">,</span> <span class="token variable">@@proxy_user</span><span class="token punctuation">;</span>
<span class="token output"><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span></span>
<span class="token output"><span class="token punctuation">|</span> USER()          <span class="token punctuation">|</span> CURRENT_USER()       <span class="token punctuation">|</span> @@proxy_user <span class="token punctuation">|</span></span>
<span class="token output"><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span></span>
<span class="token output"><span class="token punctuation">|</span> basha@localhost <span class="token punctuation">|</span> accounting@localhost <span class="token punctuation">|</span> ''@'%'       <span class="token punctuation">|</span></span>
<span class="token output"><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span></span></code></pre>
      </div>
     </li>
    </ol>
   </div>
   <p>
    This demonstrates that
    <code class="literal">
     basha
    </code>
    uses the
          privileges granted to the proxied
    <code class="literal">
     accounting
    </code>
    MySQL account, and that proxying
          occurs through the default proxy user account.
   </p>
   <p>
    Now connect as
    <code class="literal">
     basil
    </code>
    instead:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-terminal"><div class="docs-select-all right" id="sa75469793"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal"><span class="token prompt">$&gt; </span><span class="token command">mysql</span> <span class="token constant">--user</span><span class="token attr-value"><span class="token punctuation">=</span>basil</span> <span class="token property">--password</span>
Enter password<span class="token punctuation">:</span> <em class="replaceable">basil_password</em> <span class="token punctuation"></span><em class="replaceable"><span class="token punctuation">(</span>basil LDAP password<span class="token punctuation">)</span></em><span class="token punctuation"></span></code></pre>
   </div>
   <p>
    The authentication process for
    <code class="literal">
     basil
    </code>
    is
          similar to that previously described for
    <code class="literal">
     basha
    </code>
    :
   </p>
   <div class="orderedlist">
    <ol class="orderedlist" type="1">
     <li class="listitem">
      <p>
       The server authenticates the connection using the default
       <code class="literal">
        ''@'%'
       </code>
       proxy account, for client user
       <code class="literal">
        basil
       </code>
       .
      </p>
     </li>
     <li class="listitem">
      <p>
       The matching LDAP entry is:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting one-line language-ini"><div class="docs-select-all right" id="sa70353229"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-ini"><span class="token constant">uid</span><span class="token attr-value"><span class="token punctuation">=</span>basil,ou=People,dc=example,dc=com,cn=front_office</span></code></pre>
      </div>
     </li>
     <li class="listitem">
      <p>
       The matching LDAP entry has group attribute
       <code class="literal">
        cn=front_office
       </code>
       , so
       <code class="literal">
        front_office
       </code>
       becomes the authenticated
              proxied user.
      </p>
     </li>
     <li class="listitem">
      <p>
       The authenticated user differs from the client user name
       <code class="literal">
        basil
       </code>
       , with the result that
       <code class="literal">
        basil
       </code>
       is treated as a proxy for
       <code class="literal">
        front_office
       </code>
       , and
       <code class="literal">
        basil
       </code>
       assumes the privileges of the
              proxied
       <code class="literal">
        front_office
       </code>
       account. The
              following query returns output as shown:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa9596318"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token prompt">mysql&gt;</span> <span class="token keyword">SELECT</span> <span class="token function">USER</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">,</span> <span class="token function">CURRENT_USER</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">,</span> <span class="token variable">@@proxy_user</span><span class="token punctuation">;</span>
<span class="token output"><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span></span>
<span class="token output"><span class="token punctuation">|</span> USER()          <span class="token punctuation">|</span> CURRENT_USER()         <span class="token punctuation">|</span> @@proxy_user <span class="token punctuation">|</span></span>
<span class="token output"><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span></span>
<span class="token output"><span class="token punctuation">|</span> basil@localhost <span class="token punctuation">|</span> front_office@localhost <span class="token punctuation">|</span> ''@'%'       <span class="token punctuation">|</span></span>
<span class="token output"><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span></span></code></pre>
      </div>
     </li>
    </ol>
   </div>
   <p>
    This demonstrates that
    <code class="literal">
     basil
    </code>
    uses the
          privileges granted to the proxied
    <code class="literal">
     front_office
    </code>
    MySQL account, and that
          proxying occurs through the default proxy user account.
   </p>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="ldap-pluggable-authentication-usage-group-mapping">
       </a>
       LDAP Authentication Group Preference and Mapping Specification
      </h5>
     </div>
    </div>
   </div>
   <a class="indexterm" name="idm46045244968688">
   </a>
   <a class="indexterm" name="idm46045244967200">
   </a>
   <p>
    As described in
    <a class="xref" href="ldap-pluggable-authentication.html#ldap-pluggable-authentication-usage-proxying" title="LDAP Authentication with Proxying">
     LDAP Authentication with Proxying
    </a>
    ,
          basic LDAP authentication proxying works by the principle that
          the plugin uses the first group name returned by the LDAP
          server as the MySQL proxied user account name. This simple
          capability does not enable specifying any preference about
          which group name to use if the LDAP server returns multiple
          group names, or specifying any name other than the group name
          as the proxied user name.
   </p>
   <p>
    For MySQL accounts that use LDAP authentication, the
          authentication string can specify the following information to
          enable greater proxying flexibility:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       A list of groups in preference order, such that the plugin
              uses the first group name in the list that matches a group
              returned by the LDAP server.
      </p>
     </li>
     <li class="listitem">
      <p>
       A mapping from group names to proxied user names, such
              that a group name when matched can provide a specified
              name to use as the proxied user. This provides an
              alternative to using the group name as the proxied user.
      </p>
     </li>
    </ul>
   </div>
   <p>
    Consider the following MySQL proxy account definition:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa87018829"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token keyword">CREATE</span> <span class="token keyword">USER</span> <span class="token string">''</span>@<span class="token string">'%'</span>
  <span class="token keyword">IDENTIFIED</span> <span class="token keyword">WITH</span> authentication_ldap_sasl
  <span class="token keyword">AS</span> <span class="token string">'+ou=People,dc=example,dc=com#grp1=usera,grp2,grp3=userc'</span><span class="token punctuation">;</span></code></pre>
   </div>
   <p>
    The authentication string has a user DN suffix
    <code class="literal">
     ou=People,dc=example,dc=com
    </code>
    prefixed by the
    <code class="literal">
     +
    </code>
    character. Thus, as described in
    <a class="xref" href="ldap-pluggable-authentication.html#ldap-pluggable-authentication-usage-user-dn-suffix" title="LDAP Authentication User DN Suffixes">
     LDAP Authentication User DN Suffixes
    </a>
    ,
          the full user DN is constructed from the user DN suffix as
          specified, plus the client user name as the
    <code class="literal">
     uid
    </code>
    attribute.
   </p>
   <p>
    The remaining part of the authentication string begins with
    <code class="literal">
     #
    </code>
    , which signifies the beginning of group
          preference and mapping information. This part of the
          authentication string lists group names in the order
    <code class="literal">
     grp1
    </code>
    ,
    <code class="literal">
     grp2
    </code>
    ,
    <code class="literal">
     grp3
    </code>
    . The LDAP plugin compares that list
          with the set of group names returned by the LDAP server,
          looking in list order for a match against the returned names.
          The plugin uses the first match, or if there is no match,
          authentication fails.
   </p>
   <p>
    Suppose that the LDAP server returns groups
    <code class="literal">
     grp3
    </code>
    ,
    <code class="literal">
     grp2
    </code>
    , and
    <code class="literal">
     grp7
    </code>
    . The LDAP plugin uses
    <code class="literal">
     grp2
    </code>
    because it is the first group in the
          authentication string that matches, even though it is not the
          first group returned by the LDAP server. If the LDAP server
          returns
    <code class="literal">
     grp4
    </code>
    ,
    <code class="literal">
     grp2
    </code>
    , and
    <code class="literal">
     grp1
    </code>
    , the plugin uses
    <code class="literal">
     grp1
    </code>
    even though
    <code class="literal">
     grp2
    </code>
    also matches.
    <code class="literal">
     grp1
    </code>
    has a precedence higher
          than
    <code class="literal">
     grp2
    </code>
    because it is listed earlier in
          the authentication string.
   </p>
   <p>
    Assuming that the plugin finds a group name match, it performs
          mapping from that group name to the MySQL proxied user name,
          if there is one. For the example proxy account, mapping occurs
          as follows:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       If the matching group name is
       <code class="literal">
        grp1
       </code>
       or
       <code class="literal">
        grp3
       </code>
       , those are associated in the
              authentication string with user names
       <code class="literal">
        usera
       </code>
       and
       <code class="literal">
        userc
       </code>
       ,
              respectively. The plugin uses the corresponding associated
              user name as the proxied user name.
      </p>
     </li>
     <li class="listitem">
      <p>
       If the matching group name is
       <code class="literal">
        grp2
       </code>
       ,
              there is no associated user name in the authentication
              string. The plugin uses
       <code class="literal">
        grp2
       </code>
       as the
              proxied user name.
      </p>
     </li>
    </ul>
   </div>
   <p>
    If the LDAP server returns a group in DN format, the LDAP
          plugin parses the group DN to extract the group name from it.
   </p>
   <p>
    To specify LDAP group preference and mapping information,
          these principles apply:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       Begin the group preference and mapping part of the
              authentication string with a
       <code class="literal">
        #
       </code>
       prefix
              character.
      </p>
     </li>
     <li class="listitem">
      <p>
       The group preference and mapping specification is a list
              of one or more items, separated by commas. Each item has
              the form
       <code class="literal">
        <em class="replaceable">
         <code>
          group_name
         </code>
        </em>
        =
        <em class="replaceable">
         <code>
          user_name
         </code>
        </em>
       </code>
       or
       <em class="replaceable">
        <code>
         group_name
        </code>
       </em>
       . Items should be
              listed in group name preference order. For a group name
              selected by the plugin as a match from set of group names
              returned by the LDAP server, the two syntaxes differ in
              effect as follows:
      </p>
      <div class="itemizedlist">
       <ul class="itemizedlist" style="list-style-type: circle; ">
        <li class="listitem">
         <p>
          For an item specified as
          <code class="literal">
           <em class="replaceable">
            <code>
             group_name
            </code>
           </em>
           =
           <em class="replaceable">
            <code>
             user_name
            </code>
           </em>
          </code>
          (with a user name), the group name maps to the user
                  name, which is used as the MySQL proxied user name.
         </p>
        </li>
        <li class="listitem">
         <p>
          For an item specified as
          <em class="replaceable">
           <code>
            group_name
           </code>
          </em>
          (with no user
                  name), the group name is used as the MySQL proxied
                  user name.
         </p>
        </li>
       </ul>
      </div>
     </li>
     <li class="listitem">
      <p>
       To quote a group or user name that contains special
              characters such as space, surround it by double quote
              (
       <code class="literal">
        "
       </code>
       ) characters. For example, if an item
              has group and user names of
       <code class="literal">
        my group
              name
       </code>
       and
       <code class="literal">
        my user name
       </code>
       , it
              must be written in a group mapping using quotes:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting one-line language-none"><div class="docs-select-all right" id="sa57655303"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-none">"my group name"="my user name"</code></pre>
      </div>
      <p>
       If an item has group and user names of
       <code class="literal">
        my_group_name
       </code>
       and
       <code class="literal">
        my_user_name
       </code>
       (which contain no special
              characters), it may but need not be written using quotes.
              Any of the following are valid:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-none"><div class="docs-select-all right" id="sa33335711"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-none">my_group_name=my_user_name
my_group_name="my_user_name"
"my_group_name"=my_user_name
"my_group_name"="my_user_name"</code></pre>
      </div>
     </li>
     <li class="listitem">
      <p>
       To escape a character, precede it by a backslash
              (
       <code class="literal">
        \
       </code>
       ). This is useful particularly to
              include a literal double quote or backslash, which are
              otherwise not included literally.
      </p>
     </li>
     <li class="listitem">
      <p>
       A user DN need not be present in the authentication
              string, but if present, it must precede the group
              preference and mapping part. A user DN can be given as a
              full user DN, or as a user DN suffix with a
       <code class="literal">
        +
       </code>
       prefix character. (See
       <a class="xref" href="ldap-pluggable-authentication.html#ldap-pluggable-authentication-usage-user-dn-suffix" title="LDAP Authentication User DN Suffixes">
        LDAP Authentication User DN Suffixes
       </a>
       .)
      </p>
     </li>
    </ul>
   </div>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="ldap-pluggable-authentication-usage-user-dn-suffix">
       </a>
       LDAP Authentication User DN Suffixes
      </h5>
     </div>
    </div>
   </div>
   <p>
    LDAP authentication plugins permit the authentication string
          that provides user DN information to begin with a
    <code class="literal">
     +
    </code>
    prefix character:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       In the absence of a
       <code class="literal">
        +
       </code>
       character, the
              authentication string value is treated as is without
              modification.
      </p>
     </li>
     <li class="listitem">
      <p>
       If the authentication string begins with
       <code class="literal">
        +
       </code>
       , the plugin constructs the full user
              DN value from the user name sent by the client, together
              with the DN specified in the authentication string (with
              the
       <code class="literal">
        +
       </code>
       removed). In the constructed DN,
              the client user name becomes the value of the attribute
              that specifies LDAP user names. This is
       <code class="literal">
        uid
       </code>
       by default; to change the
              attribute, modify the appropriate system variable
              (
       <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_ldap_simple_user_search_attr">
        <code class="literal">
         authentication_ldap_simple_user_search_attr
        </code>
       </a>
       or
       <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_ldap_sasl_user_search_attr">
        <code class="literal">
         authentication_ldap_sasl_user_search_attr
        </code>
       </a>
       ).
              The authentication string is stored as given in the
       <code class="literal">
        mysql.user
       </code>
       system table, with the full
              user DN constructed on the fly before authentication.
      </p>
     </li>
    </ul>
   </div>
   <p>
    This account authentication string does not have
    <code class="literal">
     +
    </code>
    at the beginning, so it is taken as the
          full user DN:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa95230773"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token keyword">CREATE</span> <span class="token keyword">USER</span> <span class="token string">'baldwin'</span>
  <span class="token keyword">IDENTIFIED</span> <span class="token keyword">WITH</span> authentication_ldap_simple
  <span class="token keyword">AS</span> <span class="token string">'uid=admin,ou=People,dc=example,dc=com'</span><span class="token punctuation">;</span></code></pre>
   </div>
   <p>
    The client connects with the user name specified in the
          account (
    <code class="literal">
     baldwin
    </code>
    ). In this case, that name
          is not used because the authentication string has no prefix
          and thus fully specifies the user DN.
   </p>
   <p>
    This account authentication string does have
    <code class="literal">
     +
    </code>
    at the beginning, so it is taken as just
          part of the user DN:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa62080184"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token keyword">CREATE</span> <span class="token keyword">USER</span> <span class="token string">'accounting'</span>
  <span class="token keyword">IDENTIFIED</span> <span class="token keyword">WITH</span> authentication_ldap_simple
  <span class="token keyword">AS</span> <span class="token string">'+ou=People,dc=example,dc=com'</span><span class="token punctuation">;</span></code></pre>
   </div>
   <p>
    The client connects with the user name specified in the
          account (
    <code class="literal">
     accounting
    </code>
    ), which in this case is
          used as the
    <code class="literal">
     uid
    </code>
    attribute together with the
          authentication string to construct the user DN:
    <code class="literal">
     uid=accounting,ou=People,dc=example,dc=com
    </code>
   </p>
   <p>
    The accounts in the preceding examples have a nonempty user
          name, so the client always connects to the MySQL server using
          the same name as specified in the account definition. If an
          account has an empty user name, such as the default anonymous
    <code class="literal">
     ''@'%'
    </code>
    proxy account described in
    <a class="xref" href="ldap-pluggable-authentication.html#ldap-pluggable-authentication-usage-proxying" title="LDAP Authentication with Proxying">
     LDAP Authentication with Proxying
    </a>
    ,
          clients might connect to the MySQL server with varying user
          names. But the principle is the same: If the authentication
          string begins with
    <code class="literal">
     +
    </code>
    , the plugin uses the
          user name sent by the client together with the authentication
          string to construct the user DN.
   </p>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="ldap-pluggable-authentication-auth-methods">
       </a>
       LDAP Authentication Methods
      </h5>
     </div>
    </div>
   </div>
   <p>
    The LDAP authentication plugins use a configurable
          authentication method. The appropriate system variable and
          available method choices are plugin-specific:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       For the
       <code class="literal">
        authentication_ldap_simple
       </code>
       plugin: Set the
       <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_ldap_simple_auth_method_name">
        <code class="literal">
         authentication_ldap_simple_auth_method_name
        </code>
       </a>
       system variable to configure the method. The permitted
              choices are
       <code class="literal">
        SIMPLE
       </code>
       and
       <code class="literal">
        AD-FOREST
       </code>
       .
      </p>
     </li>
     <li class="listitem">
      <p>
       For the
       <code class="literal">
        authentication_ldap_sasl
       </code>
       plugin: Set the
       <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_ldap_sasl_auth_method_name">
        <code class="literal">
         authentication_ldap_sasl_auth_method_name
        </code>
       </a>
       system variable to configure the method. The permitted
              choices are
       <code class="literal">
        SCRAM-SHA-1
       </code>
       ,
       <code class="literal">
        SCRAM-SHA-256
       </code>
       , and
       <code class="literal">
        GSSAPI
       </code>
       . (To determine which SASL LDAP
              methods are actually available on the host system, check
              the value of the
       <a class="link" href="server-status-variables.html#statvar_Authentication_ldap_sasl_supported_methods">
        <code class="literal">
         Authentication_ldap_sasl_supported_methods
        </code>
       </a>
       status variable.)
      </p>
     </li>
    </ul>
   </div>
   <p>
    See the system variable descriptions for information about
          each permitted method. Also, depending on the method,
          additional configuration may be needed, as described in the
          following sections.
   </p>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="ldap-pluggable-authentication-gssapi">
       </a>
       The GSSAPI/Kerberos Authentication Method
      </h5>
     </div>
    </div>
   </div>
   <a class="indexterm" name="idm46045244876576">
   </a>
   <a class="indexterm" name="idm46045244875120">
   </a>
   <a class="indexterm" name="idm46045244873616">
   </a>
   <a class="indexterm" name="idm46045244872112">
   </a>
   <p>
    Generic Security Service Application Program Interface
          (GSSAPI) is a security abstraction interface. Kerberos is an
          instance of a specific security protocol that can be used
          through that abstract interface. Using GSSAPI, applications
          authenticate to Kerberos to obtain service credentials, then
          use those credentials in turn to enable secure access to other
          services.
   </p>
   <p>
    One such service is LDAP, which is used by the client-side and
          server-side SASL LDAP authentication plugins. When the
    <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_ldap_sasl_auth_method_name">
     <code class="literal">
      authentication_ldap_sasl_auth_method_name
     </code>
    </a>
    system variable is set to
    <code class="literal">
     GSSAPI
    </code>
    , these
          plugins use the GSSAPI/Kerberos authentication method. In this
          case, the plugins communicate securely using Kerberos without
          using LDAP messages directly. The server-side plugin then
          communicates with the LDAP server to interpret LDAP
          authentication messages and retrieve LDAP groups.
   </p>
   <p>
    GSSAPI/Kerberos is supported as an LDAP authentication method
          for MySQL servers and clients on Linux. It is useful in Linux
          environments where applications have access to LDAP through
          Microsoft Active Directory, which has Kerberos enabled by
          default.
   </p>
   <p>
    The following discussion provides information about the
          configuration requirements for using the GSSAPI method.
          Familiarity is assumed with Kerberos concepts and operation.
          The following list briefly defines several common Kerberos
          terms. You may also find the Glossary section of
    <a class="ulink" href="https://tools.ietf.org/html/rfc4120" target="_blank">
     RFC
          4120
    </a>
    helpful.
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       <a class="link" href="glossary.html#glos_principal" title="principal">
        Principal
       </a>
       : A named
              entity, such as a user or server.
      </p>
     </li>
     <li class="listitem">
      <p>
       <a class="link" href="glossary.html#glos_key_distribution_center" title="key distribution center">
        KDC
       </a>
       :
              The key distribution center, comprising the AS and TGS:
      </p>
      <div class="itemizedlist">
       <ul class="itemizedlist" style="list-style-type: circle; ">
        <li class="listitem">
         <p>
          <a class="link" href="glossary.html#glos_authentication_server" title="authentication server">
           AS
          </a>
          :
                  The authentication server; provides the initial
                  ticket-granting ticket needed to obtain additional
                  tickets.
         </p>
        </li>
        <li class="listitem">
         <p>
          <a class="link" href="glossary.html#glos_ticket_granting_server" title="ticket-granting server">
           TGS
          </a>
          :
                  The ticket-granting server; provides additional
                  tickets to Kerberos clients that possess a valid TGT.
         </p>
        </li>
       </ul>
      </div>
     </li>
     <li class="listitem">
      <p>
       <a class="link" href="glossary.html#glos_ticket_granting_ticket" title="ticket-granting ticket">
        TGT
       </a>
       :
              The ticket-granting ticket; presented to the TGS to obtain
              service tickets for service access.
      </p>
     </li>
    </ul>
   </div>
   <p>
    LDAP authentication using Kerberos requires both a KDC server
          and an LDAP server. This requirement can be satisfied in
          different ways:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       Active Directory includes both servers, with Kerberos
              authentication enabled by default in the Active Directory
              LDAP server.
      </p>
     </li>
     <li class="listitem">
      <p>
       OpenLDAP provides an LDAP server, but a separate KDC
              server may be needed, with additional Kerberos setup
              required.
      </p>
     </li>
    </ul>
   </div>
   <p>
    Kerberos must also be available on the client host. A client
          contacts the AS using a password to obtain a TGT. The client
          then uses the TGT to obtain access from the TGS to other
          services, such as LDAP.
   </p>
   <p>
    The following sections discuss the configuration steps to use
          GSSAPI/Kerberos for SASL LDAP authentication in MySQL:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       <a class="xref" href="ldap-pluggable-authentication.html#ldap-gssapi-kerberos-setup" title="Verify Kerberos and LDAP Availability">
        Verify Kerberos and LDAP Availability
       </a>
      </p>
     </li>
     <li class="listitem">
      <p>
       <a class="xref" href="ldap-pluggable-authentication.html#ldap-gssapi-ldap-setup" title="Configure the Server-Side SASL LDAP Authentication Plugin for GSSAPI/Kerberos">
        Configure the Server-Side SASL LDAP Authentication Plugin for GSSAPI/Kerberos
       </a>
      </p>
     </li>
     <li class="listitem">
      <p>
       <a class="xref" href="ldap-pluggable-authentication.html#ldap-gssapi-mysql-account-setup" title="Create a MySQL Account That Uses GSSAPI/Kerberos for LDAP Authentication">
        Create a MySQL Account That Uses GSSAPI/Kerberos for LDAP Authentication
       </a>
      </p>
     </li>
     <li class="listitem">
      <p>
       <a class="xref" href="ldap-pluggable-authentication.html#ldap-gssapi-mysql-client-usage" title="Use the MySQL Account to Connect to the MySQL Server">
        Use the MySQL Account to Connect to the MySQL Server
       </a>
      </p>
     </li>
     <li class="listitem">
      <p>
       <a class="xref" href="ldap-pluggable-authentication.html#ldap-gssapi-mysql-client-config-parameters" title="Client Configuration Parameters for LDAP Authentication">
        Client Configuration Parameters for LDAP Authentication
       </a>
      </p>
     </li>
    </ul>
   </div>
   <h6>
    <a name="ldap-gssapi-kerberos-setup">
    </a>
    Verify Kerberos and LDAP Availability
   </h6>
   <p>
    The following example shows how to test availability of
          Kerberos in Active Directory. The example makes these
          assumptions:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       Active Directory is running on the host named
       <code class="literal">
        ldap_auth.example.com
       </code>
       with IP address
       <code class="literal">
        198.51.100.10
       </code>
       .
      </p>
     </li>
     <li class="listitem">
      <p>
       MySQL-related Kerberos authentication and LDAP lookups use
              the
       <code class="literal">
        MYSQL.LOCAL
       </code>
       domain.
      </p>
     </li>
     <li class="listitem">
      <p>
       A principal named
       <code class="literal">
        bredon@MYSQL.LOCAL
       </code>
       is
              registered with the KDC. (In later discussion, this
              principal name is also associated with the MySQL account
              that authenticates to the MySQL server using
              GSSAPI/Kerberos.)
      </p>
     </li>
    </ul>
   </div>
   <p>
    With those assumptions satisfied, follow this procedure:
   </p>
   <div class="orderedlist">
    <ol class="orderedlist" type="1">
     <li class="listitem">
      <p>
       Verify that the Kerberos library is installed and
              configured correctly in the operating system. For example,
              to configure a
       <code class="literal">
        MYSQL.LOCAL
       </code>
       domain for
              use during MySQL authentication, the
       <code class="filename">
        /etc/krb5.conf
       </code>
       Kerberos configuration
              file should contain something like this:
      </p>
      <a class="indexterm" name="idm46045244832608">
      </a>
      <a class="indexterm" name="idm46045244831120">
      </a>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-ini"><div class="docs-select-all right" id="sa44943597"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-ini"><span class="token selector">[realms]</span>
<span class="token constant">  MYSQL.LOCAL</span> <span class="token attr-value"><span class="token punctuation">=</span> {</span>
<span class="token constant">    kdc</span> <span class="token attr-value"><span class="token punctuation">=</span> ldap_auth.example.com</span>
<span class="token constant">    admin_server</span> <span class="token attr-value"><span class="token punctuation">=</span> ldap_auth.example.com</span>
<span class="token constant">    default_domain</span> <span class="token attr-value"><span class="token punctuation">=</span> MYSQL.LOCAL</span>
  }</code></pre>
      </div>
     </li>
     <li class="listitem">
      <p>
       You may need to add an entry to
       <code class="filename">
        /etc/hosts
       </code>
       for the server host:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting one-line language-simple"><div class="docs-select-all right" id="sa73727839"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-simple">198<span class="token punctuation">.</span>51<span class="token punctuation">.</span>100<span class="token punctuation">.</span>10 ldap_auth ldap_auth<span class="token punctuation">.</span>example<span class="token punctuation">.</span>com</code></pre>
      </div>
     </li>
     <li class="listitem">
      <p>
       Check whether Kerberos authentication works correctly:
      </p>
      <div class="orderedlist">
       <ol class="orderedlist" type="a">
        <li class="listitem">
         <p>
          Use
          <span class="command">
           <strong>
            kinit
           </strong>
          </span>
          to authenticate to
                  Kerberos:
         </p>
         <div class="copytoclipboard-wrapper">
          <pre class="programlisting language-terminal"><div class="docs-select-all right" id="sa37747153"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal"><span class="token prompt">$&gt; </span><span class="token command">kinit</span> bredon@MYSQL<span class="token punctuation">.</span>LOCAL
Password for bredon@MYSQL<span class="token punctuation">.</span>LOCAL<span class="token punctuation">:</span> <span class="token punctuation"></span><em class="replaceable"><span class="token punctuation">(</span>enter password here<span class="token punctuation">)</span></em><span class="token punctuation"></span></code></pre>
         </div>
         <p>
          The command authenticates for the Kerberos principal
                  named
          <code class="literal">
           bredon@MYSQL.LOCAL
          </code>
          . Enter the
                  principal's password when the command prompts for
                  it. The KDC returns a TGT that is cached on the client
                  side for use by other Kerberos-aware applications.
         </p>
        </li>
        <li class="listitem">
         <p>
          Use
          <span class="command">
           <strong>
            klist
           </strong>
          </span>
          to check whether the TGT
                  was obtained correctly. The output should be similar
                  to this:
         </p>
         <div class="copytoclipboard-wrapper">
          <pre class="programlisting language-terminal"><div class="docs-select-all right" id="sa80166448"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal"><span class="token prompt">$&gt; </span><span class="token command">klist</span>
Ticket cache<span class="token punctuation">:</span> FILE<span class="token punctuation">:</span>/tmp/krb5cc_244306
Default principal<span class="token punctuation">:</span> bredon@MYSQL<span class="token punctuation">.</span>LOCAL

Valid starting       Expires              Service principal
03/23/2021 08<span class="token punctuation">:</span>18<span class="token punctuation">:</span>33  03/23/2021 18<span class="token punctuation">:</span>18<span class="token punctuation">:</span>33  krbtgt/MYSQL<span class="token punctuation">.</span>LOCAL@MYSQL<span class="token punctuation">.</span>LOCAL</code></pre>
         </div>
        </li>
       </ol>
      </div>
     </li>
     <li class="listitem">
      <p>
       Check whether
       <span class="command">
        <strong>
         ldapsearch
        </strong>
       </span>
       works with the
              Kerberos TGT using this command, which searches for users
              in the
       <code class="literal">
        MYSQL.LOCAL
       </code>
       domain:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting one-line language-terminal"><div class="docs-select-all right" id="sa81890148"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal">ldapsearch <span class="token property">-h</span> 198<span class="token punctuation">.</span>51<span class="token punctuation">.</span>100<span class="token punctuation">.</span>10 <span class="token property">-Y</span> GSSAPI <span class="token property">-b</span> <span class="token atrule">"dc=MYSQL,dc=LOCAL"</span></code></pre>
      </div>
     </li>
    </ol>
   </div>
   <h6>
    <a name="ldap-gssapi-ldap-setup">
    </a>
    Configure the Server-Side SASL LDAP Authentication Plugin for
          GSSAPI/Kerberos
   </h6>
   <p>
    Assuming that the LDAP server is accessible through Kerberos
          as just described, configure the server-side SASL LDAP
          authentication plugin to use the GSSAPI/Kerberos
          authentication method. (For general LDAP plugin installation
          information, see
    <a class="xref" href="ldap-pluggable-authentication.html#ldap-pluggable-authentication-installation" title="Installing LDAP Pluggable Authentication">
     Installing LDAP Pluggable Authentication
    </a>
    .)
          Here is an example of plugin-related settings the server
    <code class="filename">
     my.cnf
    </code>
    file might contain:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-ini"><div class="docs-select-all right" id="sa9114135"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-ini"><span class="token selector">[mysqld]</span>
<span class="token constant">plugin-load-add</span><span class="token attr-value"><span class="token punctuation">=</span>authentication_ldap_sasl.so</span>
<span class="token constant">authentication_ldap_sasl_auth_method_name</span><span class="token attr-value"><span class="token punctuation">=</span>"GSSAPI"</span>
<span class="token constant">authentication_ldap_sasl_server_host</span><span class="token attr-value"><span class="token punctuation">=</span>198.51.100.10</span>
<span class="token constant">authentication_ldap_sasl_server_port</span><span class="token attr-value"><span class="token punctuation">=</span>389</span>
<span class="token constant">authentication_ldap_sasl_bind_root_dn</span><span class="token attr-value"><span class="token punctuation">=</span>"cn=admin,cn=users,dc=MYSQL,dc=LOCAL"</span>
<span class="token constant">authentication_ldap_sasl_bind_root_pwd</span><span class="token attr-value"><span class="token punctuation">=</span>"<em class="replaceable">password</em>"</span>
<span class="token constant">authentication_ldap_sasl_bind_base_dn</span><span class="token attr-value"><span class="token punctuation">=</span>"cn=users,dc=MYSQL,dc=LOCAL"</span>
<span class="token constant">authentication_ldap_sasl_user_search_attr</span><span class="token attr-value"><span class="token punctuation">=</span>"sAMAccountName"</span></code></pre>
   </div>
   <p>
    Those option file settings configure the SASL LDAP plugin as
          follows:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       The
       <a class="link" href="server-options.html#option_mysqld_plugin-load-add">
        <code class="option">
         --plugin-load-add
        </code>
       </a>
       option loads the plugin (adjust the
       <code class="filename">
        .so
       </code>
       suffix for your platform as
              necessary). If you loaded the plugin previously using an
       <a class="link" href="install-plugin.html" title="15.7.4.4 INSTALL PLUGIN Statement">
        <code class="literal">
         INSTALL PLUGIN
        </code>
       </a>
       statement,
              this option is unnecessary.
      </p>
     </li>
     <li class="listitem">
      <p>
       <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_ldap_sasl_auth_method_name">
        <code class="literal">
         authentication_ldap_sasl_auth_method_name
        </code>
       </a>
       must be set to
       <code class="literal">
        GSSAPI
       </code>
       to use
              GSSAPI/Kerberos as the SASL LDAP authentication method.
      </p>
     </li>
     <li class="listitem">
      <p>
       <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_ldap_sasl_server_host">
        <code class="literal">
         authentication_ldap_sasl_server_host
        </code>
       </a>
       and
       <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_ldap_sasl_server_port">
        <code class="literal">
         authentication_ldap_sasl_server_port
        </code>
       </a>
       indicate the IP address and port number of the Active
              Directory server host for authentication.
      </p>
     </li>
     <li class="listitem">
      <p>
       <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_ldap_sasl_bind_root_dn">
        <code class="literal">
         authentication_ldap_sasl_bind_root_dn
        </code>
       </a>
       and
       <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_ldap_sasl_bind_root_pwd">
        <code class="literal">
         authentication_ldap_sasl_bind_root_pwd
        </code>
       </a>
       configure the root DN and password for group search
              capability. This capability is required, but users may not
              have privileges to search. In such cases, it is necessary
              to provide root DN information:
      </p>
      <div class="itemizedlist">
       <ul class="itemizedlist" style="list-style-type: circle; ">
        <li class="listitem">
         <p>
          In the DN option value,
          <code class="literal">
           admin
          </code>
          should be the name of an administrative LDAP account
                  that has privileges to perform user searches.
         </p>
        </li>
        <li class="listitem">
         <p>
          In the password option value,
          <em class="replaceable">
           <code>
            password
           </code>
          </em>
          should be the
          <code class="literal">
           admin
          </code>
          account password.
         </p>
        </li>
       </ul>
      </div>
     </li>
     <li class="listitem">
      <p>
       <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_ldap_sasl_bind_base_dn">
        <code class="literal">
         authentication_ldap_sasl_bind_base_dn
        </code>
       </a>
       indicates the user DN base path, so that searches look for
              users in the
       <code class="literal">
        MYSQL.LOCAL
       </code>
       domain.
      </p>
     </li>
     <li class="listitem">
      <p>
       <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_ldap_sasl_user_search_attr">
        <code class="literal">
         authentication_ldap_sasl_user_search_attr
        </code>
       </a>
       specifies a standard Active Directory search attribute,
       <code class="literal">
        sAMAccountName
       </code>
       . This attribute is used
              in searches to match logon names; attribute values are not
              the same as the user DN values.
      </p>
     </li>
    </ul>
   </div>
   <h6>
    <a name="ldap-gssapi-mysql-account-setup">
    </a>
    Create a MySQL Account That Uses GSSAPI/Kerberos for LDAP Authentication
   </h6>
   <p>
    MySQL authentication using the SASL LDAP authentication plugin
          with the GSSAPI/Kerberos method is based on a user that is a
          Kerberos principal. The following discussion uses a principal
          named
    <code class="literal">
     bredon@MYSQL.LOCAL
    </code>
    as this user,
          which must be registered in several places:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       The Kerberos administrator should register the user name
              as a Kerberos principal. This name should include a domain
              name. Clients use the principal name and password to
              authenticate with Kerberos and obtain a TGT.
      </p>
     </li>
     <li class="listitem">
      <p>
       The LDAP administrator should register the user name in an
              LDAP entry. For example:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting one-line language-none"><div class="docs-select-all right" id="sa38118371"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-none">uid=bredon,dc=MYSQL,dc=LOCAL</code></pre>
      </div>
      <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
       <div class="admon-title">
        Note
       </div>
       <p>
        In Active Directory (which uses Kerberos as the default
                authentication method), creating a user creates both the
                Kerberos principal and the LDAP entry.
       </p>
      </div>
     </li>
     <li class="listitem">
      <p>
       The MySQL DBA should create an account that has the
              Kerberos principal name as the user name and that
              authenticates using the SASL LDAP plugin.
      </p>
     </li>
    </ul>
   </div>
   <p>
    Assume that the Kerberos principal and LDAP entry have been
          registered by the appropriate service administrators, and
          that, as previously described in
    <a class="xref" href="ldap-pluggable-authentication.html#ldap-pluggable-authentication-installation" title="Installing LDAP Pluggable Authentication">
     Installing LDAP Pluggable Authentication
    </a>
    ,
          and
    <a class="xref" href="ldap-pluggable-authentication.html#ldap-gssapi-ldap-setup" title="Configure the Server-Side SASL LDAP Authentication Plugin for GSSAPI/Kerberos">
     Configure the Server-Side SASL LDAP Authentication Plugin for GSSAPI/Kerberos
    </a>
    , the MySQL server
          has been started with appropriate configuration settings for
          the server-side SASL LDAP plugin. The MySQL DBA then creates a
          MySQL account that corresponds to the Kerberos principal name,
          including the domain name.
   </p>
   <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
    <div class="admon-title">
     Note
    </div>
    <p>
     The SASL LDAP plugin uses a constant user DN for Kerberos
            authentication and ignores any user DN configured from
            MySQL. This has certain implications:
    </p>
    <div class="itemizedlist">
     <ul class="itemizedlist" style="list-style-type: disc; ">
      <li class="listitem">
       <p>
        For any MySQL account that uses GSSAPI/Kerberos
                authentication, the authentication string in
        <a class="link" href="create-user.html" title="15.7.1.3 CREATE USER Statement">
         <code class="literal">
          CREATE USER
         </code>
        </a>
        or
        <a class="link" href="alter-user.html" title="15.7.1.1 ALTER USER Statement">
         <code class="literal">
          ALTER USER
         </code>
        </a>
        statements
                should contain no user DN because it has no effect.
       </p>
      </li>
      <li class="listitem">
       <p>
        Because the authentication string contains no user DN,
                it should contain group mapping information, to enable
                the user to be handled as a proxy user that is mapped
                onto the desired proxied user. For information about
                proxying with the LDAP authentication plugin, see
        <a class="xref" href="ldap-pluggable-authentication.html#ldap-pluggable-authentication-usage-proxying" title="LDAP Authentication with Proxying">
         LDAP Authentication with Proxying
        </a>
        .
       </p>
      </li>
     </ul>
    </div>
   </div>
   <p>
    The following statements create a proxy user named
    <code class="literal">
     bredon@MYSQL.LOCAL
    </code>
    that assumes the
          privileges of the proxied user named
    <code class="literal">
     proxied_krb_usr
    </code>
    . Other GSSAPI/Kerberos
          users that should have the same privileges can similarly be
          created as proxy users for the same proxied user.
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa40453900"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token comment" spellcheck="true">-- create proxy account</span>
<span class="token keyword">CREATE</span> <span class="token keyword">USER</span> <span class="token string">'bredon@MYSQL.LOCAL'</span>
  <span class="token keyword">IDENTIFIED</span> <span class="token keyword">WITH</span> authentication_ldap_sasl
  <span class="token keyword">BY</span> <span class="token string">'#krb_grp=proxied_krb_user'</span><span class="token punctuation">;</span>

<span class="token comment" spellcheck="true">-- create proxied account and grant its privileges;</span>
<span class="token comment" spellcheck="true">-- use mysql_no_login plugin to prevent direct login</span>
<span class="token keyword">CREATE</span> <span class="token keyword">USER</span> <span class="token string">'proxied_krb_user'</span>
  <span class="token keyword">IDENTIFIED</span> <span class="token keyword">WITH</span> mysql_no_login<span class="token punctuation">;</span>
<span class="token keyword">GRANT</span> <span class="token keyword">ALL</span>
  <span class="token keyword">ON</span> krb_user_db<span class="token punctuation">.</span><span class="token operator">*</span>
  <span class="token keyword">TO</span> <span class="token string">'proxied_krb_user'</span><span class="token punctuation">;</span>

<span class="token comment" spellcheck="true">-- grant to proxy account the</span>
<span class="token comment" spellcheck="true">-- PROXY privilege for proxied account</span>
<span class="token keyword">GRANT</span> <span class="token keyword">PROXY</span>
  <span class="token keyword">ON</span> <span class="token string">'proxied_krb_user'</span>
  <span class="token keyword">TO</span> <span class="token string">'bredon@MYSQL.LOCAL'</span><span class="token punctuation">;</span></code></pre>
   </div>
   <p>
    Observe closely the quoting for the proxy account name in the
          first
    <a class="link" href="create-user.html" title="15.7.1.3 CREATE USER Statement">
     <code class="literal">
      CREATE USER
     </code>
    </a>
    statement and
          the
    <a class="link" href="grant.html" title="15.7.1.6 GRANT Statement">
     <code class="literal">
      GRANT
          PROXY
     </code>
    </a>
    statement:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       For most MySQL accounts, the user and host are separate
              parts of the account name, and thus are quoted separately
              as
       <code class="literal">
        '
        <em class="replaceable">
         <code>
          user_name
         </code>
        </em>
        '@'
        <em class="replaceable">
         <code>
          host_name
         </code>
        </em>
        '
       </code>
       .
      </p>
     </li>
     <li class="listitem">
      <p>
       For LDAP Kerberos authentication, the user part of the
              account name includes the principal domain, so
       <code class="literal">
        'bredon@MYSQL.LOCAL'
       </code>
       is quoted as a
              single value. Because no host part is given, the full
              MySQL account name uses the default of
       <code class="literal">
        '%'
       </code>
       as the host part:
       <code class="literal">
        'bredon@MYSQL.LOCAL'@'%'
       </code>
      </p>
     </li>
    </ul>
   </div>
   <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
    <div class="admon-title">
     Note
    </div>
    <p>
     When creating an account that authenticates using the
     <code class="literal">
      authentication_ldap_sasl
     </code>
     SASL LDAP
            authentication plugin with the GSSAPI/Kerberos
            authentication method, the
     <a class="link" href="create-user.html" title="15.7.1.3 CREATE USER Statement">
      <code class="literal">
       CREATE
            USER
      </code>
     </a>
     statement includes the realm as part of the
            user name. This differs from creating accounts that use the
     <code class="literal">
      authentication_kerberos
     </code>
     Kerberos plugin.
            For such accounts, the
     <a class="link" href="create-user.html" title="15.7.1.3 CREATE USER Statement">
      <code class="literal">
       CREATE
            USER
      </code>
     </a>
     statement does not include the realm as part
            of the user name. Instead, specify the realm as the
            authentication string in the
     <code class="literal">
      BY
     </code>
     clause.
            See
     <a class="xref" href="kerberos-pluggable-authentication.html#kerberos-usage-mysql-account-setup" title="Create a MySQL Account That Uses Kerberos Authentication">
      Create a MySQL Account That Uses Kerberos Authentication
     </a>
     .
    </p>
   </div>
   <p>
    The proxied account uses the
    <code class="literal">
     mysql_no_login
    </code>
    authentication plugin to prevent clients from using the
          account to log in directly to the MySQL server. Instead, it is
          expected that users who authenticate using LDAP use the
    <code class="literal">
     bredon@MYSQL.LOCAL
    </code>
    proxy account. (This
          assumes that the
    <code class="literal">
     mysql_no_login
    </code>
    plugin is
          installed. For instructions, see
    <a class="xref" href="no-login-pluggable-authentication.html" title="8.4.1.9 No-Login Pluggable Authentication">
     Section 8.4.1.9, “No-Login Pluggable Authentication”
    </a>
    .) For
          alternative methods of protecting proxied accounts against
          direct use, see
    <a class="xref" href="proxy-users.html#preventing-proxied-account-direct-login" title="Preventing Direct Login to Proxied Accounts">
     Preventing Direct Login to Proxied Accounts
    </a>
    .
   </p>
   <h6>
    <a name="ldap-gssapi-mysql-client-usage">
    </a>
    Use the MySQL Account to Connect to the MySQL Server
   </h6>
   <p>
    After a MySQL account that authenticates using GSSAPI/Kerberos
          has been set up, clients can use it to connect to the MySQL
          server. Kerberos authentication can take place either prior to
          or at the time of MySQL client program invocation:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       Prior to invoking the MySQL client program, the client
              user can obtain a TGT from the KDC independently of MySQL.
              For example, the client user can use
       <span class="command">
        <strong>
         kinit
        </strong>
       </span>
       to authenticate to Kerberos by
              providing a Kerberos principal name and the principal
              password:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-terminal"><div class="docs-select-all right" id="sa66008720"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal"><span class="token prompt">$&gt; </span><span class="token command">kinit</span> bredon@MYSQL<span class="token punctuation">.</span>LOCAL
Password for bredon@MYSQL<span class="token punctuation">.</span>LOCAL<span class="token punctuation">:</span> <span class="token punctuation"></span><em class="replaceable"><span class="token punctuation">(</span>enter password here<span class="token punctuation">)</span></em><span class="token punctuation"></span></code></pre>
      </div>
      <p>
       The resulting TGT is cached and becomes available for use
              by other Kerberos-aware applications, such as programs
              that use the client-side SASL LDAP authentication plugin.
              In this case, the MySQL client program authenticates to
              the MySQL server using the TGT, so invoke the client
              without specifying a user name or password:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting one-line language-terminal"><div class="docs-select-all right" id="sa36805530"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal">mysql <span class="token constant">--default-auth</span><span class="token attr-value"><span class="token punctuation">=</span>authentication_ldap_sasl_client</span></code></pre>
      </div>
      <p>
       As just described, when the TGT is cached, user-name and
              password options are not needed in the client command. If
              the command includes them anyway, they are handled as
              follows:
      </p>
      <div class="itemizedlist">
       <ul class="itemizedlist" style="list-style-type: circle; ">
        <li class="listitem">
         <p>
          If the command includes a user name, authentication
                  fails if that name does not match the principal name
                  in the TGT.
         </p>
        </li>
        <li class="listitem">
         <p>
          If the command includes a password, the client-side
                  plugin ignores it. Because authentication is based on
                  the TGT, it can succeed
          <span class="emphasis">
           <em>
            even if the
                  user-provided password is incorrect
           </em>
          </span>
          . For
                  this reason, the plugin produces a warning if a valid
                  TGT is found that causes a password to be ignored.
         </p>
        </li>
       </ul>
      </div>
     </li>
     <li class="listitem">
      <p>
       If the Kerberos cache contains no TGT, the client-side
              SASL LDAP authentication plugin itself can obtain the TGT
              from the KDC. Invoke the client with options for the name
              and password of the Kerberos principal associated with the
              MySQL account (enter the command on a single line, then
              enter the principal password when prompted):
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-terminal"><div class="docs-select-all right" id="sa82533636"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal">mysql <span class="token constant">--default-auth</span><span class="token attr-value"><span class="token punctuation">=</span>authentication_ldap_sasl_client</span>
  <span class="token constant">--user</span><span class="token attr-value"><span class="token punctuation">=</span>bredon@MYSQL.LOCAL</span>
  <span class="token property">--password</span></code></pre>
      </div>
     </li>
     <li class="listitem">
      <p>
       If the Kerberos cache contains no TGT and the client
              command specifies no principal name as the user name,
              authentication fails.
      </p>
     </li>
    </ul>
   </div>
   <p>
    If you are uncertain whether a TGT exists, you can use
    <span class="command">
     <strong>
      klist
     </strong>
    </span>
    to check.
   </p>
   <p>
    Authentication occurs as follows:
   </p>
   <div class="orderedlist">
    <ol class="orderedlist" type="1">
     <li class="listitem">
      <p>
       The client uses the TGT to authenticate using Kerberos.
      </p>
     </li>
     <li class="listitem">
      <p>
       The server finds the LDAP entry for the principal and uses
              it to authenticate the connection for the
       <code class="literal">
        bredon@MYSQL.LOCAL
       </code>
       MySQL proxy account.
      </p>
     </li>
     <li class="listitem">
      <p>
       The group mapping information in the proxy account
              authentication string
              (
       <code class="literal">
        '#krb_grp=proxied_krb_user'
       </code>
       ) indicates
              that the authenticated proxied user should be
       <code class="literal">
        proxied_krb_user
       </code>
       .
      </p>
     </li>
     <li class="listitem">
      <p>
       <code class="literal">
        bredon@MYSQL.LOCAL
       </code>
       is treated as a
              proxy for
       <code class="literal">
        proxied_krb_user
       </code>
       , and the
              following query returns output as shown:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa42706334"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token prompt">mysql&gt;</span> <span class="token keyword">SELECT</span> <span class="token function">USER</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">,</span> <span class="token function">CURRENT_USER</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">,</span> <span class="token variable">@@proxy_user</span><span class="token punctuation">;</span>
<span class="token output"><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span></span>
<span class="token output"><span class="token punctuation">|</span> USER()                       <span class="token punctuation">|</span> CURRENT_USER()     <span class="token punctuation">|</span> @@proxy_user             <span class="token punctuation">|</span></span>
<span class="token output"><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span></span>
<span class="token output"><span class="token punctuation">|</span> bredon@MYSQL.LOCAL@localhost <span class="token punctuation">|</span> proxied_krb_user@% <span class="token punctuation">|</span> 'bredon@MYSQL.LOCAL'@'%' <span class="token punctuation">|</span></span>
<span class="token output"><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span></span></code></pre>
      </div>
      <p>
       The
       <a class="link" href="information-functions.html#function_user">
        <code class="literal">
         USER()
        </code>
       </a>
       value indicates
              the user name used for the client command
              (
       <code class="literal">
        bredon@MYSQL.LOCAL
       </code>
       ) and the host from
              which the client connected (
       <code class="literal">
        localhost
       </code>
       ).
      </p>
      <p>
       The
       <a class="link" href="information-functions.html#function_current-user">
        <code class="literal">
         CURRENT_USER()
        </code>
       </a>
       value is
              the full name of the proxied user account, which consists
              of the
       <code class="literal">
        proxied_krb_user
       </code>
       user part and
              the
       <code class="literal">
        %
       </code>
       host part.
      </p>
      <p>
       The
       <a class="link" href="server-system-variables.html#sysvar_proxy_user">
        <code class="literal">
         @@proxy_user
        </code>
       </a>
       value indicates the full name of the account used to make
              the connection to the MySQL server, which consists of the
       <code class="literal">
        bredon@MYSQL.LOCAL
       </code>
       user part and the
       <code class="literal">
        %
       </code>
       host part.
      </p>
      <p>
       This demonstrates that proxying occurs through the
       <code class="literal">
        bredon@MYSQL.LOCAL
       </code>
       proxy user account,
              and that
       <code class="literal">
        bredon@MYSQL.LOCAL
       </code>
       assumes the
              privileges granted to the
       <code class="literal">
        proxied_krb_user
       </code>
       proxied user account.
      </p>
     </li>
    </ol>
   </div>
   <p>
    A TGT once obtained is cached on the client side and can be
          used until it expires without specifying the password again.
          However the TGT is obtained, the client-side plugin uses it to
          acquire service tickets and communicate with the server-side
          plugin.
   </p>
   <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
    <div class="admon-title">
     Note
    </div>
    <p>
     When the client-side authentication plugin itself obtains
            the TGT, the client user may not want the TGT to be reused.
            As described in
     <a class="xref" href="ldap-pluggable-authentication.html#ldap-gssapi-mysql-client-config-parameters" title="Client Configuration Parameters for LDAP Authentication">
      Client Configuration Parameters for LDAP Authentication
     </a>
     ,
            the local
     <code class="literal">
      /etc/krb5.conf
     </code>
     file can be used
            to cause the client-side plugin to destroy the TGT when done
            with it.
    </p>
   </div>
   <p>
    The server-side plugin has no access to the TGT itself or the
          Kerberos password used to obtain it.
   </p>
   <p>
    The LDAP authentication plugins have no control over the
          caching mechanism (storage in a local file, in memory, and so
          forth), but Kerberos utilities such as
    <span class="command">
     <strong>
      kswitch
     </strong>
    </span>
    may be available for this purpose.
   </p>
   <h6>
    <a name="ldap-gssapi-mysql-client-config-parameters">
    </a>
    Client Configuration Parameters for LDAP Authentication
   </h6>
   <p>
    The
    <code class="literal">
     authentication_ldap_sasl_client
    </code>
    client-side SASL LDAP plugin reads the local
    <code class="filename">
     /etc/krb5.conf
    </code>
    file. If this file is
          missing or inaccessible, an error occurs. Assuming that the
          file is accessible, it can include an optional
    <code class="literal">
     [appdefaults]
    </code>
    section to provide
          information used by the plugin. Place the information within
          the
    <code class="literal">
     mysql
    </code>
    part of the section. For example:
   </p>
   <a class="indexterm" name="idm46045244691904">
   </a>
   <a class="indexterm" name="idm46045244690416">
   </a>
   <a class="indexterm" name="idm46045244688928">
   </a>
   <a class="indexterm" name="idm46045244687424">
   </a>
   <a class="indexterm" name="idm46045244685920">
   </a>
   <a class="indexterm" name="idm46045244684416">
   </a>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-ini"><div class="docs-select-all right" id="sa78723544"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-ini"><span class="token selector">[appdefaults]</span>
<span class="token constant">  mysql</span> <span class="token attr-value"><span class="token punctuation">=</span> {</span>
<span class="token constant">    ldap_server_host</span> <span class="token attr-value"><span class="token punctuation">=</span> "ldap_host.example.com"</span>
<span class="token constant">    ldap_destroy_tgt</span> <span class="token attr-value"><span class="token punctuation">=</span> true</span>
  }</code></pre>
   </div>
   <p>
    The client-side plugin recognizes these parameters in the
    <code class="literal">
     mysql
    </code>
    section:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       The
       <code class="literal">
        ldap_server_host
       </code>
       value specifies
              the LDAP server host and can be useful when that host
              differs from the KDC server host specified in the
       <code class="literal">
        [realms]
       </code>
       section. By default, the
              plugin uses the KDC server host as the LDAP server host.
      </p>
     </li>
     <li class="listitem">
      <p>
       The
       <code class="literal">
        ldap_destroy_tgt
       </code>
       value indicates
              whether the client-side plugin destroys the TGT after
              obtaining and using it. By default,
       <code class="literal">
        ldap_destroy_tgt
       </code>
       is
       <code class="literal">
        false
       </code>
       , but can be set to
       <code class="literal">
        true
       </code>
       to avoid TGT reuse. (This setting
              applies only to TGTs created by the client-side plugin,
              not TGTs created by other plugins or externally to MySQL.)
      </p>
     </li>
    </ul>
   </div>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="ldap-pluggable-authentication-ldap-referral">
       </a>
       LDAP Search Referral
      </h5>
     </div>
    </div>
   </div>
   <p>
    An LDAP server can be configured to delegate LDAP searches to
          another LDAP server, a functionality known as LDAP referral.
          Suppose that the server
    <code class="literal">
     a.example.com
    </code>
    holds
          a
    <code class="literal">
     "dc=example,dc=com"
    </code>
    root DN and wishes to
          delegate searches to another server
    <code class="literal">
     b.example.com
    </code>
    . To enable this,
    <code class="literal">
     a.example.com
    </code>
    would be configured with a
          named referral object having these attributes:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-simple"><div class="docs-select-all right" id="sa47149693"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-simple">dn<span class="token operator">:</span> dc<span class="token operator">=</span>subtree<span class="token punctuation">,</span>dc<span class="token operator">=</span>example<span class="token punctuation">,</span>dc<span class="token operator">=</span>com
objectClass<span class="token operator">:</span> referral
objectClass<span class="token operator">:</span> extensibleObject
dc<span class="token operator">:</span> subtree
ref<span class="token operator">:</span> ldap<span class="token operator">:</span><span class="token operator">/</span><span class="token operator">/</span>b<span class="token punctuation">.</span>example<span class="token punctuation">.</span>com<span class="token operator">/</span>dc<span class="token operator">=</span>subtree<span class="token punctuation">,</span>dc<span class="token operator">=</span>example<span class="token punctuation">,</span>dc<span class="token operator">=</span>com</code></pre>
   </div>
   <p>
    An issue with enabling LDAP referral is that searches can fail
          with LDAP operation errors when the search base DN is the root
          DN, and referral objects are not set. A MySQL DBA might wish
          to avoid such referral errors for the LDAP authentication
          plugins, even though LDAP referral might be set globally in
          the
    <code class="filename">
     ldap.conf
    </code>
    configuration file. To
          configure on a plugin-specific basis whether the LDAP server
          should use LDAP referral when communicating with each plugin,
          set the
    <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_ldap_simple_referral">
     <code class="literal">
      authentication_ldap_simple_referral
     </code>
    </a>
    and
    <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_ldap_sasl_referral">
     <code class="literal">
      authentication_ldap_sasl_referral
     </code>
    </a>
    system variables. Setting either variable to
    <code class="literal">
     ON
    </code>
    or
    <code class="literal">
     OFF
    </code>
    causes the
          corresponding LDAP authentication plugin to tell the LDAP
          server whether to use referral during MySQL authentication.
          Each variable has a plugin-specific effect and does not affect
          other applications that communicate with the LDAP server. Both
          variables are
    <code class="literal">
     OFF
    </code>
    by default.
   </p>
  </div>
 </div>
 <br/>
</div>
