<div id="docs-body">
 <div class="section">
  <div class="titlepage">
   <div>
    <div>
     <h4 class="title">
      <a name="pam-pluggable-authentication">
      </a>
      8.4.1.5 PAM Pluggable Authentication
     </h4>
    </div>
   </div>
  </div>
  <a class="indexterm" name="idm46045245922480">
  </a>
  <a class="indexterm" name="idm46045245921376">
  </a>
  <a class="indexterm" name="idm46045245919888">
  </a>
  <a class="indexterm" name="idm46045245918416">
  </a>
  <a class="indexterm" name="idm46045245916944">
  </a>
  <a class="indexterm" name="idm46045245915856">
  </a>
  <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
   <div class="admon-title">
    Note
   </div>
   <p>
    PAM 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 PAM (Pluggable Authentication Modules) to
        authenticate MySQL users. PAM enables a system to use a standard
        interface to access various kinds of authentication methods,
        such as traditional Unix passwords or an LDAP directory.
  </p>
  <p>
   PAM pluggable authentication provides these capabilities:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      External authentication: PAM authentication enables MySQL
            Server to accept connections from users defined outside the
            MySQL grant tables and that authenticate using methods
            supported by PAM.
     </p>
    </li>
    <li class="listitem">
     <p>
      Proxy user support: PAM authentication can return to MySQL a
            user name different from the external user name passed by
            the client program, based on the PAM groups the external
            user is a member of and the authentication string provided.
            This means that the plugin can return the MySQL user that
            defines the privileges the external PAM-authenticated user
            should have. For example, an operating system user named
      <code class="literal">
       joe
      </code>
      can connect and have the privileges
            of a MySQL user named
      <code class="literal">
       developer
      </code>
      .
     </p>
    </li>
   </ul>
  </div>
  <p>
   PAM pluggable authentication has been tested on Linux and macOS;
        note that Windows does not support PAM.
  </p>
  <p>
   The following table shows the plugin and library file names. The
        file name suffix might differ on your system. The file 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. For
        installation information, see
   <a class="xref" href="pam-pluggable-authentication.html#pam-pluggable-authentication-installation" title="Installing PAM Pluggable Authentication">
    Installing PAM Pluggable Authentication
   </a>
   .
  </p>
  <div class="table">
   <a name="idm46045245904016">
   </a>
   <p class="title">
    <b>
     Table 8.18 Plugin and Library Names for PAM Authentication
    </b>
   </p>
   <div class="table-contents">
    <table summary="Names for the plugins and library file used for PAM 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
       </td>
       <td>
        <code class="literal">
         authentication_pam
        </code>
       </td>
      </tr>
      <tr>
       <td>
        Client-side plugin
       </td>
       <td>
        <code class="literal">
         mysql_clear_password
        </code>
       </td>
      </tr>
      <tr>
       <td>
        Library file
       </td>
       <td>
        <code class="filename">
         authentication_pam.so
        </code>
       </td>
      </tr>
     </tbody>
    </table>
   </div>
  </div>
  <br class="table-break"/>
  <p>
   The client-side
   <code class="literal">
    mysql_clear_password
   </code>
   cleartext plugin that communicates with the server-side PAM
        plugin is built into the
   <code class="literal">
    libmysqlclient
   </code>
   client library and is included in all distributions, including
        community distributions. Inclusion of the client-side cleartext
        plugin in all MySQL distributions enables clients from any
        distribution to connect to a server that has the server-side PAM
        plugin loaded.
  </p>
  <p>
   The following sections provide installation and usage
        information specific to PAM pluggable authentication:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      <a class="xref" href="pam-pluggable-authentication.html#pam-pluggable-authentication-process" title="How PAM Authentication of MySQL Users Works">
       How PAM Authentication of MySQL Users Works
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="pam-pluggable-authentication.html#pam-pluggable-authentication-installation" title="Installing PAM Pluggable Authentication">
       Installing PAM Pluggable Authentication
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="pam-pluggable-authentication.html#pam-pluggable-authentication-uninstallation" title="Uninstalling PAM Pluggable Authentication">
       Uninstalling PAM Pluggable Authentication
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="pam-pluggable-authentication.html#pam-pluggable-authentication-usage" title="Using PAM Pluggable Authentication">
       Using PAM Pluggable Authentication
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="pam-pluggable-authentication.html#pam-authentication-unix-without-proxy" title="PAM Unix Password Authentication without Proxy Users">
       PAM Unix Password Authentication without Proxy Users
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="pam-pluggable-authentication.html#pam-authentication-ldap-without-proxy" title="PAM LDAP Authentication without Proxy Users">
       PAM LDAP Authentication without Proxy Users
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="pam-pluggable-authentication.html#pam-authentication-unix-with-proxy" title="PAM Unix Password Authentication with Proxy Users and Group Mapping">
       PAM Unix Password Authentication with Proxy Users and Group Mapping
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="pam-pluggable-authentication.html#pam-authentication-unix-password-store" title="PAM Authentication Access to Unix Password Store">
       PAM Authentication Access to Unix Password Store
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="pam-pluggable-authentication.html#pam-pluggable-authentication-debugging" title="PAM Authentication Debugging">
       PAM Authentication Debugging
      </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="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="pam-pluggable-authentication-process">
       </a>
       How PAM Authentication of MySQL Users Works
      </h5>
     </div>
    </div>
   </div>
   <p>
    This section provides an overview of how MySQL and PAM work
          together to authenticate MySQL users. For examples showing how
          to set up MySQL accounts to use specific PAM services, see
    <a class="xref" href="pam-pluggable-authentication.html#pam-pluggable-authentication-usage" title="Using PAM Pluggable Authentication">
     Using PAM Pluggable Authentication
    </a>
    .
   </p>
   <div class="orderedlist">
    <ol class="orderedlist" type="1">
     <li class="listitem">
      <p>
       The client program and the server communicate, with the
              client sending to the server the client user name (the
              operating system user name by default) and password:
      </p>
      <div class="itemizedlist">
       <ul class="itemizedlist" style="list-style-type: disc; ">
        <li class="listitem">
         <p>
          The client user name is the external user name.
         </p>
        </li>
        <li class="listitem">
         <p>
          For accounts that use the PAM server-side
                  authentication plugin, the corresponding client-side
                  plugin is
          <code class="literal">
           mysql_clear_password
          </code>
          .
                  This client-side plugin performs no password hashing,
                  with the result that the client sends the password to
                  the server as cleartext.
         </p>
        </li>
       </ul>
      </div>
     </li>
     <li class="listitem">
      <p>
       The server finds a matching MySQL account based on the
              external user name and the host from which the client
              connects. The PAM plugin uses the information passed to it
              by MySQL Server (such as user name, host name, password,
              and authentication string). When you define a MySQL
              account that authenticates using PAM, the authentication
              string contains:
      </p>
      <div class="itemizedlist">
       <ul class="itemizedlist" style="list-style-type: disc; ">
        <li class="listitem">
         <p>
          A PAM service name, which is a name that the system
                  administrator can use to refer to an authentication
                  method for a particular application. There can be
                  multiple applications associated with a single
                  database server instance, so the choice of service
                  name is left to the SQL application developer.
         </p>
        </li>
        <li class="listitem">
         <p>
          Optionally, if proxying is to be used, a mapping from
                  PAM groups to MySQL user names.
         </p>
        </li>
       </ul>
      </div>
     </li>
     <li class="listitem">
      <p>
       The plugin uses the PAM service named in the
              authentication string to check the user credentials and
              returns
       <code class="literal">
        'Authentication succeeded, Username is
        <em class="replaceable">
         <code>
          user_name
         </code>
        </em>
        '
       </code>
       or
       <code class="literal">
        'Authentication failed'
       </code>
       . The password
              must be appropriate for the password store used by the PAM
              service. Examples:
      </p>
      <div class="itemizedlist">
       <ul class="itemizedlist" style="list-style-type: disc; ">
        <li class="listitem">
         <p>
          For traditional Unix passwords, the service looks up
                  passwords stored in the
          <code class="filename">
           /etc/shadow
          </code>
          file.
         </p>
        </li>
        <li class="listitem">
         <p>
          For LDAP, the service looks up passwords stored in an
                  LDAP directory.
         </p>
        </li>
       </ul>
      </div>
      <p>
       If the credentials check fails, the server refuses the
              connection.
      </p>
     </li>
     <li class="listitem">
      <p>
       Otherwise, the authentication string indicates whether
              proxying occurs. If the string contains no PAM group
              mapping, proxying does not occur. In this case, the MySQL
              user name is the same as the external user name.
      </p>
     </li>
     <li class="listitem">
      <p>
       Otherwise, proxying is indicated based on the PAM group
              mapping, with the MySQL user name determined based on the
              first matching group in the mapping list. The meaning of
       <span class="quote">
        “
        <span class="quote">
         PAM group
        </span>
        ”
       </span>
       depends on the PAM service.
              Examples:
      </p>
      <div class="itemizedlist">
       <ul class="itemizedlist" style="list-style-type: disc; ">
        <li class="listitem">
         <p>
          For traditional Unix passwords, groups are Unix groups
                  defined in the
          <code class="filename">
           /etc/group
          </code>
          file,
                  possibly supplemented with additional PAM information
                  in a file such as
          <code class="filename">
           /etc/security/group.conf
          </code>
          .
         </p>
        </li>
        <li class="listitem">
         <p>
          For LDAP, groups are LDAP groups defined in an LDAP
                  directory.
         </p>
        </li>
       </ul>
      </div>
      <p>
       If the proxy user (the external user) has the
       <a class="link" href="privileges-provided.html#priv_proxy">
        <code class="literal">
         PROXY
        </code>
       </a>
       privilege for the
              proxied MySQL user name, proxying occurs, with the proxy
              user assuming the privileges of the proxied user.
      </p>
     </li>
    </ol>
   </div>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="pam-pluggable-authentication-installation">
       </a>
       Installing PAM Pluggable Authentication
      </h5>
     </div>
    </div>
   </div>
   <p>
    This section describes how to install the server-side PAM
          authentication plugin. 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 file 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 plugin library file base name is
    <code class="literal">
     authentication_pam
    </code>
    , and is typically
          compiled with the
    <code class="filename">
     .so
    </code>
    suffix.
   </p>
   <p>
    To load the plugin at server startup, use the
    <a class="link" href="server-options.html#option_mysqld_plugin-load-add">
     <code class="option">
      --plugin-load-add
     </code>
    </a>
    option to
          name the library file that contains it. With this
          plugin-loading method, the option must be given each time the
          server starts. For example, put these lines in the server
    <code class="filename">
     my.cnf
    </code>
    file:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-ini"><div class="docs-select-all right" id="sa21007739"><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_pam.so</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 plugin at runtime, use this
          statement, adjusting the
    <code class="filename">
     .so
    </code>
    suffix as
          necessary:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting one-line language-sql"><div class="docs-select-all right" id="sa17443386"><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_pam <span class="token keyword">SONAME</span> <span class="token string">'authentication_pam.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>
    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="sa65399954"><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">'%pam%'</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>
<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>
<span class="token output"><span class="token punctuation">|</span> authentication_pam <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></code></pre>
   </div>
   <p>
    If the plugin fails to initialize, check the server error log
          for diagnostic messages.
   </p>
   <p>
    To associate MySQL accounts with the PAM plugin, see
    <a class="xref" href="pam-pluggable-authentication.html#pam-pluggable-authentication-usage" title="Using PAM Pluggable Authentication">
     Using PAM Pluggable Authentication
    </a>
    .
   </p>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="pam-pluggable-authentication-uninstallation">
       </a>
       Uninstalling PAM Pluggable Authentication
      </h5>
     </div>
    </div>
   </div>
   <p>
    The method used to uninstall the PAM authentication plugin
          depends on how you installed it:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       If you installed the plugin at server startup using a
       <a class="link" href="server-options.html#option_mysqld_plugin-load-add">
        <code class="option">
         --plugin-load-add
        </code>
       </a>
       option,
              restart the server without the option.
      </p>
     </li>
     <li class="listitem">
      <p>
       If you installed the plugin at runtime 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,
              it remains installed across server restarts. To uninstall
              it, 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 one-line language-sql"><div class="docs-select-all right" id="sa2298923"><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_pam<span class="token punctuation">;</span></code></pre>
      </div>
     </li>
    </ul>
   </div>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="pam-pluggable-authentication-usage">
       </a>
       Using PAM Pluggable Authentication
      </h5>
     </div>
    </div>
   </div>
   <p>
    This section describes in general terms how to use the PAM
          authentication plugin to connect from MySQL client programs to
          the server. The following sections provide instructions for
          using PAM authentication in specific ways. It is assumed that
          the server is running with the server-side PAM plugin enabled,
          as described in
    <a class="xref" href="pam-pluggable-authentication.html#pam-pluggable-authentication-installation" title="Installing PAM Pluggable Authentication">
     Installing PAM Pluggable Authentication
    </a>
    .
   </p>
   <p>
    To refer to the PAM authentication plugin in the
    <code class="literal">
     IDENTIFIED WITH
    </code>
    clause of a
    <a class="link" href="create-user.html" title="15.7.1.3 CREATE USER Statement">
     <code class="literal">
      CREATE USER
     </code>
    </a>
    statement, use the
          name
    <code class="literal">
     authentication_pam
    </code>
    . For example:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa98283200"><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_pam
  <span class="token keyword">AS</span> <span class="token string">'<em class="replaceable">auth_string</em>'</span><span class="token punctuation">;</span></code></pre>
   </div>
   <p>
    The authentication string specifies the following types of
          information:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       The PAM service name (see
       <a class="xref" href="pam-pluggable-authentication.html#pam-pluggable-authentication-process" title="How PAM Authentication of MySQL Users Works">
        How PAM Authentication of MySQL Users Works
       </a>
       ).
              Examples in the following discussion use a service name of
       <code class="literal">
        mysql-unix
       </code>
       for authentication using
              traditional Unix passwords, and
       <code class="literal">
        mysql-ldap
       </code>
       for authentication using
              LDAP.
      </p>
     </li>
     <li class="listitem">
      <p>
       For proxy support, PAM provides a way for a PAM module to
              return to the server a MySQL user name other than the
              external user name passed by the client program when it
              connects to the server. Use the authentication string to
              control the mapping from external user names to MySQL user
              names. If you want to take advantage of proxy user
              capabilities, the authentication string must include this
              kind of mapping.
      </p>
     </li>
    </ul>
   </div>
   <p>
    For example, if an account uses the
    <code class="literal">
     mysql-unix
    </code>
    PAM service name and should map
          operating system users in the
    <code class="literal">
     root
    </code>
    and
    <code class="literal">
     users
    </code>
    PAM groups to the
    <code class="literal">
     developer
    </code>
    and
    <code class="literal">
     data_entry
    </code>
    MySQL users, respectively, use a statement like this:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa8530724"><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_pam
  <span class="token keyword">AS</span> <span class="token string">'mysql-unix, root=developer, users=data_entry'</span><span class="token punctuation">;</span></code></pre>
   </div>
   <p>
    Authentication string syntax for the PAM authentication plugin
          follows these rules:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       The string consists of a PAM service name, optionally
              followed by a PAM group mapping list consisting of one or
              more keyword/value pairs each specifying a PAM group name
              and a MySQL user name:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting one-line language-none"><div class="docs-select-all right" id="sa39685423"><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"><em class="replaceable">pam_service_name</em>[,<em class="replaceable">pam_group_name</em>=<em class="replaceable">mysql_user_name</em>]...</code></pre>
      </div>
      <p>
       The plugin parses the authentication string for each
              connection attempt that uses the account. To minimize
              overhead, keep the string as short as possible.
      </p>
     </li>
     <li class="listitem">
      <p>
       Each
       <code class="literal">
        <em class="replaceable">
         <code>
          pam_group_name
         </code>
        </em>
        =
        <em class="replaceable">
         <code>
          mysql_user_name
         </code>
        </em>
       </code>
       pair must be preceded by a comma.
      </p>
     </li>
     <li class="listitem">
      <p>
       Leading and trailing spaces not inside double quotation
              marks are ignored.
      </p>
     </li>
     <li class="listitem">
      <p>
       Unquoted
       <em class="replaceable">
        <code>
         pam_service_name
        </code>
       </em>
       ,
       <em class="replaceable">
        <code>
         pam_group_name
        </code>
       </em>
       , and
       <em class="replaceable">
        <code>
         mysql_user_name
        </code>
       </em>
       values can
              contain anything except equal sign, comma, or space.
      </p>
     </li>
     <li class="listitem">
      <p>
       If a
       <em class="replaceable">
        <code>
         pam_service_name
        </code>
       </em>
       ,
       <em class="replaceable">
        <code>
         pam_group_name
        </code>
       </em>
       , or
       <em class="replaceable">
        <code>
         mysql_user_name
        </code>
       </em>
       value is quoted
              with double quotation marks, everything between the
              quotation marks is part of the value. This is necessary,
              for example, if the value contains space characters. All
              characters are legal except double quotation mark and
              backslash (
       <code class="literal">
        \
       </code>
       ). To include either
              character, escape it with a backslash.
      </p>
     </li>
    </ul>
   </div>
   <p>
    If the plugin successfully authenticates the external user
          name (the name passed by the client), it looks for a PAM group
          mapping list in the authentication string and, if present,
          uses it to return a different MySQL user name to the MySQL
          server based on which PAM groups the external user is a member
          of:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       If the authentication string contains no PAM group mapping
              list, the plugin returns the external name.
      </p>
     </li>
     <li class="listitem">
      <p>
       If the authentication string does contain a PAM group
              mapping list, the plugin examines each
       <code class="literal">
        <em class="replaceable">
         <code>
          pam_group_name
         </code>
        </em>
        =
        <em class="replaceable">
         <code>
          mysql_user_name
         </code>
        </em>
       </code>
       pair in the list from left to right and tries to find a
              match for the
       <em class="replaceable">
        <code>
         pam_group_name
        </code>
       </em>
       value in a non-MySQL directory of the groups assigned to
              the authenticated user and returns
       <em class="replaceable">
        <code>
         mysql_user_name
        </code>
       </em>
       for the first
              match it finds. If the plugin finds no match for any PAM
              group, it returns the external name. If the plugin is not
              capable of looking up a group in a directory, it ignores
              the PAM group mapping list and returns the external name.
      </p>
     </li>
    </ul>
   </div>
   <p>
    The following sections describe how to set up several
          authentication scenarios that use the PAM authentication
          plugin:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       No proxy users. This uses PAM only to check login names
              and passwords. Every external user permitted to connect to
              MySQL Server should have a matching MySQL account that is
              defined to use PAM authentication. (For a MySQL account of
       <code class="literal">
        '
        <em class="replaceable">
         <code>
          user_name
         </code>
        </em>
        '@'
        <em class="replaceable">
         <code>
          host_name
         </code>
        </em>
        '
       </code>
       to match the external user,
       <em class="replaceable">
        <code>
         user_name
        </code>
       </em>
       must be the external
              user name and
       <em class="replaceable">
        <code>
         host_name
        </code>
       </em>
       must
              match the host from which the client connects.)
              Authentication can be performed by various PAM-supported
              methods. Later discussion shows how to authenticate client
              credentials using traditional Unix passwords, and
              passwords in LDAP.
      </p>
      <p>
       PAM authentication, when not done through proxy users or
              PAM groups, requires the MySQL user name to be same as the
              operating system user name. MySQL user names are limited
              to 32 characters (see
       <a class="xref" href="grant-tables.html" title="8.2.3 Grant Tables">
        Section 8.2.3, “Grant Tables”
       </a>
       ),
              which limits PAM nonproxy authentication to Unix accounts
              with names of at most 32 characters.
      </p>
     </li>
     <li class="listitem">
      <p>
       Proxy users only, with PAM group mapping. For this
              scenario, create one or more MySQL accounts that define
              different sets of privileges. (Ideally, nobody should
              connect using those accounts directly.) Then define a
              default user authenticating through PAM that uses some
              mapping scheme (usually based on the external PAM groups
              the users are members of) to map all the external user
              names to the few MySQL accounts holding the privilege
              sets. Any client who connects and specifies an external
              user name as the client user name is mapped to one of the
              MySQL accounts and uses its privileges. The discussion
              shows how to set this up using traditional Unix passwords,
              but other PAM methods such as LDAP could be used instead.
      </p>
     </li>
    </ul>
   </div>
   <p>
    Variations on these scenarios are possible:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       You can permit some users to log in directly (without
              proxying) but require others to connect through proxy
              accounts.
      </p>
     </li>
     <li class="listitem">
      <p>
       You can use one PAM authentication method for some users,
              and another method for other users, by using differing PAM
              service names among your PAM-authenticated accounts. For
              example, you can use the
       <code class="literal">
        mysql-unix
       </code>
       PAM
              service for some users, and
       <code class="literal">
        mysql-ldap
       </code>
       for others.
      </p>
     </li>
    </ul>
   </div>
   <p>
    The examples make the following assumptions. You might need to
          make some adjustments if your system is set up differently.
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       The login name and password are
       <code class="literal">
        antonio
       </code>
       and
       <em class="replaceable">
        <code>
         antonio_password
        </code>
       </em>
       ,
              respectively. Change these to correspond to the user you
              want to authenticate.
      </p>
     </li>
     <li class="listitem">
      <p>
       The PAM configuration directory is
       <code class="filename">
        /etc/pam.d
       </code>
       .
      </p>
     </li>
     <li class="listitem">
      <p>
       The PAM service name corresponds to the authentication
              method (
       <code class="literal">
        mysql-unix
       </code>
       or
       <code class="literal">
        mysql-ldap
       </code>
       in this discussion). To use
              a given PAM service, you must set up a PAM file with the
              same name in the PAM configuration directory (creating the
              file if it does not exist). In addition, you must name the
              PAM service in the authentication string of the
       <a class="link" href="create-user.html" title="15.7.1.3 CREATE USER Statement">
        <code class="literal">
         CREATE USER
        </code>
       </a>
       statement for
              any account that authenticates using that PAM service.
      </p>
     </li>
    </ul>
   </div>
   <p>
    The PAM authentication plugin checks at initialization time
          whether the
    <code class="literal">
     AUTHENTICATION_PAM_LOG
    </code>
    environment value is set in the server's startup
          environment. If so, the plugin enables logging of diagnostic
          messages to the standard output. Depending on how your server
          is started, the message might appear on the console or in the
          error log. These messages can be helpful for debugging
          PAM-related issues that occur when the plugin performs
          authentication. For more information, see
    <a class="xref" href="pam-pluggable-authentication.html#pam-pluggable-authentication-debugging" title="PAM Authentication Debugging">
     PAM Authentication Debugging
    </a>
    .
   </p>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="pam-authentication-unix-without-proxy">
       </a>
       PAM Unix Password Authentication without Proxy Users
      </h5>
     </div>
    </div>
   </div>
   <p>
    This authentication scenario uses PAM to check external users
          defined in terms of operating system user names and Unix
          passwords, without proxying. Every such external user
          permitted to connect to MySQL Server should have a matching
          MySQL account that is defined to use PAM authentication
          through traditional Unix password store.
   </p>
   <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
    <div class="admon-title">
     Note
    </div>
    <p>
     Traditional Unix passwords are checked using the
     <code class="filename">
      /etc/shadow
     </code>
     file. For information
            regarding possible issues related to this file, see
     <a class="xref" href="pam-pluggable-authentication.html#pam-authentication-unix-password-store" title="PAM Authentication Access to Unix Password Store">
      PAM Authentication Access to Unix Password Store
     </a>
     .
    </p>
   </div>
   <div class="orderedlist">
    <ol class="orderedlist" type="1">
     <li class="listitem">
      <p>
       Verify that Unix authentication permits logins to the
              operating system with the user name
       <code class="literal">
        antonio
       </code>
       and password
       <em class="replaceable">
        <code>
         antonio_password
        </code>
       </em>
       .
      </p>
     </li>
     <li class="listitem">
      <p>
       Set up PAM to authenticate MySQL connections using
              traditional Unix passwords by creating a
       <code class="literal">
        mysql-unix
       </code>
       PAM service file named
       <code class="filename">
        /etc/pam.d/mysql-unix
       </code>
       . The file
              contents are system dependent, so check existing
              login-related files in the
       <code class="filename">
        /etc/pam.d
       </code>
       directory to see what they look like. On Linux, the
       <code class="filename">
        mysql-unix
       </code>
       file might look like this:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-none"><div class="docs-select-all right" id="sa7144015"><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">#%PAM-1.0
auth            include         password-auth
account         include         password-auth</code></pre>
      </div>
      <p>
       For macOS, use
       <code class="literal">
        login
       </code>
       rather than
       <code class="literal">
        password-auth
       </code>
       .
      </p>
      <p>
       The PAM file format might differ on some systems. For
              example, on Ubuntu and other Debian-based systems, use
              these file contents instead:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-none"><div class="docs-select-all right" id="sa28642813"><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">@include common-auth
@include common-account
@include common-session-noninteractive</code></pre>
      </div>
     </li>
     <li class="listitem">
      <p>
       Create a MySQL account with the same user name as the
              operating system user name and define it to authenticate
              using the PAM plugin and the
       <code class="literal">
        mysql-unix
       </code>
       PAM service:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa56714795"><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">'antonio'</span>@<span class="token string">'localhost'</span>
  <span class="token keyword">IDENTIFIED</span> <span class="token keyword">WITH</span> authentication_pam
  <span class="token keyword">AS</span> <span class="token string">'mysql-unix'</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> mydb<span class="token punctuation">.</span><span class="token operator">*</span>
  <span class="token keyword">TO</span> <span class="token string">'antonio'</span>@<span class="token string">'localhost'</span><span class="token punctuation">;</span></code></pre>
      </div>
      <p>
       Here, the authentication string contains only the PAM
              service name,
       <code class="literal">
        mysql-unix
       </code>
       , which
              authenticates Unix passwords.
      </p>
     </li>
     <li class="listitem">
      <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">
        antonio
       </code>
       .
              For example:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-terminal"><div class="docs-select-all right" id="sa49397572"><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>antonio</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">antonio_password</em></code></pre>
      </div>
      <p>
       The server should permit the connection 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="sa91031957"><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>
<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>
<span class="token output"><span class="token punctuation">|</span> antonio@localhost <span class="token punctuation">|</span> antonio@localhost <span class="token punctuation">|</span> NULL         <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></code></pre>
      </div>
      <p>
       This demonstrates that the
       <code class="literal">
        antonio
       </code>
       operating system user is authenticated to have the
              privileges granted to the
       <code class="literal">
        antonio
       </code>
       MySQL
              user, and that no proxying has occurred.
      </p>
     </li>
    </ol>
   </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 PAM. A
            cleartext password is necessary to use the server-side PAM
            library, 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>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="pam-authentication-ldap-without-proxy">
       </a>
       PAM LDAP Authentication without Proxy Users
      </h5>
     </div>
    </div>
   </div>
   <p>
    This authentication scenario uses PAM to check external users
          defined in terms of operating system user names and LDAP
          passwords, without proxying. Every such external user
          permitted to connect to MySQL Server should have a matching
          MySQL account that is defined to use PAM authentication
          through LDAP.
   </p>
   <p>
    To use PAM 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 PAM LDAP service
              to communicate with.
      </p>
     </li>
     <li class="listitem">
      <p>
       Each LDAP user to be authenticated by MySQL must be
              present in the directory managed by the LDAP server.
      </p>
     </li>
    </ul>
   </div>
   <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
    <div class="admon-title">
     Note
    </div>
    <p>
     Another way to use LDAP for MySQL user authentication is to
            use the LDAP-specific authentication plugins. See
     <a class="xref" href="ldap-pluggable-authentication.html" title="8.4.1.7 LDAP Pluggable Authentication">
      Section 8.4.1.7, “LDAP Pluggable Authentication”
     </a>
     .
    </p>
   </div>
   <p>
    Configure MySQL for PAM LDAP authentication as follows:
   </p>
   <div class="orderedlist">
    <ol class="orderedlist" type="1">
     <li class="listitem">
      <p>
       Verify that Unix authentication permits logins to the
              operating system with the user name
       <code class="literal">
        antonio
       </code>
       and password
       <em class="replaceable">
        <code>
         antonio_password
        </code>
       </em>
       .
      </p>
     </li>
     <li class="listitem">
      <p>
       Set up PAM to authenticate MySQL connections using LDAP by
              creating a
       <code class="literal">
        mysql-ldap
       </code>
       PAM service file
              named
       <code class="filename">
        /etc/pam.d/mysql-ldap
       </code>
       . The file
              contents are system dependent, so check existing
              login-related files in the
       <code class="filename">
        /etc/pam.d
       </code>
       directory to see what they look like. On Linux, the
       <code class="filename">
        mysql-ldap
       </code>
       file might look like this:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-none"><div class="docs-select-all right" id="sa98145848"><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">#%PAM-1.0
auth        required    pam_ldap.so
account     required    pam_ldap.so</code></pre>
      </div>
      <p>
       If PAM object files have a suffix different from
       <code class="filename">
        .so
       </code>
       on your system, substitute the
              correct suffix.
      </p>
      <p>
       The PAM file format might differ on some systems.
      </p>
     </li>
     <li class="listitem">
      <p>
       Create a MySQL account with the same user name as the
              operating system user name and define it to authenticate
              using the PAM plugin and the
       <code class="literal">
        mysql-ldap
       </code>
       PAM service:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa38365859"><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">'antonio'</span>@<span class="token string">'localhost'</span>
  <span class="token keyword">IDENTIFIED</span> <span class="token keyword">WITH</span> authentication_pam
  <span class="token keyword">AS</span> <span class="token string">'mysql-ldap'</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> mydb<span class="token punctuation">.</span><span class="token operator">*</span>
  <span class="token keyword">TO</span> <span class="token string">'antonio'</span>@<span class="token string">'localhost'</span><span class="token punctuation">;</span></code></pre>
      </div>
      <p>
       Here, the authentication string contains only the PAM
              service name,
       <code class="literal">
        mysql-ldap
       </code>
       , which
              authenticates using LDAP.
      </p>
     </li>
     <li class="listitem">
      <p>
       Connecting to the server is the same as described in
       <a class="xref" href="pam-pluggable-authentication.html#pam-authentication-unix-without-proxy" title="PAM Unix Password Authentication without Proxy Users">
        PAM Unix Password Authentication without Proxy Users
       </a>
       .
      </p>
     </li>
    </ol>
   </div>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="pam-authentication-unix-with-proxy">
       </a>
       PAM Unix Password Authentication with Proxy Users and Group Mapping
      </h5>
     </div>
    </div>
   </div>
   <a class="indexterm" name="idm46045245691600">
   </a>
   <p>
    The authentication scheme described here uses proxying and PAM
          group mapping to map connecting MySQL users who authenticate
          using PAM 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 using PAM, such
          that all the external users are mapped to the MySQL accounts
          that hold the privileges. Any user who connects using the
          proxy account is mapped to one of those MySQL accounts, the
          privileges for which determine the database operations
          permitted to the external user.
   </p>
   <p>
    The procedure shown here uses Unix password authentication. To
          use LDAP instead, see the early steps of
    <a class="xref" href="pam-pluggable-authentication.html#pam-authentication-ldap-without-proxy" title="PAM LDAP Authentication without Proxy Users">
     PAM LDAP Authentication without Proxy Users
    </a>
    .
   </p>
   <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
    <div class="admon-title">
     Note
    </div>
    <p>
     Traditional Unix passwords are checked using the
     <code class="filename">
      /etc/shadow
     </code>
     file. For information
            regarding possible issues related to this file, see
     <a class="xref" href="pam-pluggable-authentication.html#pam-authentication-unix-password-store" title="PAM Authentication Access to Unix Password Store">
      PAM Authentication Access to Unix Password Store
     </a>
     .
    </p>
   </div>
   <div class="orderedlist">
    <ol class="orderedlist" type="1">
     <li class="listitem">
      <p>
       Verify that Unix authentication permits logins to the
              operating system with the user name
       <code class="literal">
        antonio
       </code>
       and password
       <em class="replaceable">
        <code>
         antonio_password
        </code>
       </em>
       .
      </p>
     </li>
     <li class="listitem">
      <p>
       Verify that
       <code class="literal">
        antonio
       </code>
       is a member of the
       <code class="literal">
        root
       </code>
       or
       <code class="literal">
        users
       </code>
       PAM
              group.
      </p>
     </li>
     <li class="listitem">
      <p>
       Set up PAM to authenticate the
       <code class="literal">
        mysql-unix
       </code>
       PAM service through
              operating system users by creating a file named
       <code class="filename">
        /etc/pam.d/mysql-unix
       </code>
       . The file
              contents are system dependent, so check existing
              login-related files in the
       <code class="filename">
        /etc/pam.d
       </code>
       directory to see what they look like. On Linux, the
       <code class="filename">
        mysql-unix
       </code>
       file might look like this:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-none"><div class="docs-select-all right" id="sa11278410"><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">#%PAM-1.0
auth            include         password-auth
account         include         password-auth</code></pre>
      </div>
      <p>
       For macOS, use
       <code class="literal">
        login
       </code>
       rather than
       <code class="literal">
        password-auth
       </code>
       .
      </p>
      <p>
       The PAM file format might differ on some systems. For
              example, on Ubuntu and other Debian-based systems, use
              these file contents instead:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-none"><div class="docs-select-all right" id="sa79796550"><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">@include common-auth
@include common-account
@include common-session-noninteractive</code></pre>
      </div>
     </li>
     <li class="listitem">
      <p>
       Create a default proxy user (
       <code class="literal">
        ''@''
       </code>
       )
              that maps external PAM users to the proxied accounts:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa73607295"><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_pam
  <span class="token keyword">AS</span> <span class="token string">'mysql-unix, root=developer, users=data_entry'</span><span class="token punctuation">;</span></code></pre>
      </div>
      <p>
       Here, the authentication string contains the PAM service
              name,
       <code class="literal">
        mysql-unix
       </code>
       , which authenticates
              Unix passwords. The authentication string also maps
              external users in the
       <code class="literal">
        root
       </code>
       and
       <code class="literal">
        users
       </code>
       PAM groups to the
       <code class="literal">
        developer
       </code>
       and
       <code class="literal">
        data_entry
       </code>
       MySQL user names,
              respectively.
      </p>
      <p>
       The PAM group mapping list following the PAM service name
              is required when you set up proxy users. Otherwise, the
              plugin cannot tell how to perform mapping from external
              user names to the proper proxied MySQL user names.
      </p>
      <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>
     </li>
     <li class="listitem">
      <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="sa69174406"><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">'developer'</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">'data_entry'</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> mydevdb<span class="token punctuation">.</span><span class="token operator">*</span>
  <span class="token keyword">TO</span> <span class="token string">'developer'</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> mydb<span class="token punctuation">.</span><span class="token operator">*</span>
  <span class="token keyword">TO</span> <span class="token string">'data_entry'</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
              PAM are expected to use the
       <code class="literal">
        developer
       </code>
       or
       <code class="literal">
        data_entry
       </code>
       account by proxy based on
              their PAM group. (This assumes that the 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>
     </li>
     <li class="listitem">
      <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="sa85416876"><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">'developer'</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">'data_entry'</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>
     </li>
     <li class="listitem">
      <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">
        antonio
       </code>
       .
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-terminal"><div class="docs-select-all right" id="sa75309702"><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>antonio</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">antonio_password</em></code></pre>
      </div>
      <p>
       The server authenticates the connection using the default
       <code class="literal">
        ''@''
       </code>
       proxy account. The resulting
              privileges for
       <code class="literal">
        antonio
       </code>
       depend on which
              PAM groups
       <code class="literal">
        antonio
       </code>
       is a member of. If
       <code class="option">
        antonio
       </code>
       is a member of the
       <code class="literal">
        root
       </code>
       PAM group, the PAM plugin maps
       <code class="literal">
        root
       </code>
       to the
       <code class="literal">
        developer
       </code>
       MySQL user name and returns
              that name to the server. The server verifies that
       <code class="literal">
        ''@''
       </code>
       has the
       <a class="link" href="privileges-provided.html#priv_proxy">
        <code class="literal">
         PROXY
        </code>
       </a>
       privilege for
       <code class="literal">
        developer
       </code>
       and permits the connection.
              The following query returns output as shown:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa76733147"><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>
<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>
<span class="token output"><span class="token punctuation">|</span> antonio@localhost <span class="token punctuation">|</span> developer@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></code></pre>
      </div>
      <p>
       This demonstrates that the
       <code class="literal">
        antonio
       </code>
       operating system user is authenticated to have the
              privileges granted to the
       <code class="literal">
        developer
       </code>
       MySQL user, and that proxying occurs through the default
              proxy account.
      </p>
      <p>
       If
       <code class="literal">
        antonio
       </code>
       is not a member of the
       <code class="literal">
        root
       </code>
       PAM group but is a member of the
       <code class="literal">
        users
       </code>
       PAM group, a similar process
              occurs, but the plugin maps
       <code class="literal">
        user
       </code>
       PAM
              group membership to the
       <code class="literal">
        data_entry
       </code>
       MySQL user name and returns that name to the server:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa45060805"><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> antonio@localhost <span class="token punctuation">|</span> data_entry@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>
      <p>
       This demonstrates that the
       <code class="literal">
        antonio
       </code>
       operating system user is authenticated to have the
              privileges of the
       <code class="literal">
        data_entry
       </code>
       MySQL
              user, and that proxying occurs through the default proxy
              account.
      </p>
     </li>
    </ol>
   </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 PAM. A
            cleartext password is necessary to use the server-side PAM
            library, 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>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="pam-authentication-unix-password-store">
       </a>
       PAM Authentication Access to Unix Password Store
      </h5>
     </div>
    </div>
   </div>
   <p>
    On some systems, Unix authentication uses a password store
          such as
    <code class="filename">
     /etc/shadow
    </code>
    , a file that
          typically has restricted access permissions. This can cause
          MySQL PAM-based authentication to fail. Unfortunately, the PAM
          implementation does not permit distinguishing
    <span class="quote">
     “
     <span class="quote">
      password
          could not be checked
     </span>
     ”
    </span>
    (due, for example, to inability
          to read
    <code class="filename">
     /etc/shadow
    </code>
    ) from
    <span class="quote">
     “
     <span class="quote">
      password
          does not match.
     </span>
     ”
    </span>
    If you are using Unix password store
          for PAM authentication, you may be able to enable access to it
          from MySQL using one of the following methods:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       Assuming that the MySQL server is run from the
       <code class="literal">
        mysql
       </code>
       operating system account, put
              that account in the
       <code class="literal">
        shadow
       </code>
       group that
              has
       <code class="filename">
        /etc/shadow
       </code>
       access:
      </p>
      <div class="orderedlist">
       <ol class="orderedlist" type="1">
        <li class="listitem">
         <p>
          Create a
          <code class="literal">
           shadow
          </code>
          group in
          <code class="filename">
           /etc/group
          </code>
          .
         </p>
        </li>
        <li class="listitem">
         <p>
          Add the
          <code class="literal">
           mysql
          </code>
          operating system user
                  to the
          <code class="literal">
           shadow
          </code>
          group in
          <code class="filename">
           /etc/group
          </code>
          .
         </p>
        </li>
        <li class="listitem">
         <p>
          Assign
          <code class="filename">
           /etc/group
          </code>
          to the
          <code class="literal">
           shadow
          </code>
          group and enable the group
                  read permission:
         </p>
         <div class="copytoclipboard-wrapper">
          <pre class="programlisting language-terminal"><div class="docs-select-all right" id="sa59371757"><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">chgrp shadow /etc/shadow
chmod g+r /etc/shadow</code></pre>
         </div>
        </li>
        <li class="listitem">
         <p>
          Restart the MySQL server.
         </p>
        </li>
       </ol>
      </div>
     </li>
     <li class="listitem">
      <p>
       If you are using the
       <code class="literal">
        pam_unix
       </code>
       module
              and the
       <span class="command">
        <strong>
         unix_chkpwd
        </strong>
       </span>
       utility, enable
              password store access as follows:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-terminal"><div class="docs-select-all right" id="sa25131067"><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">chmod u-s /usr/sbin/unix_chkpwd
setcap cap_dac_read_search+ep /usr/sbin/unix_chkpwd</code></pre>
      </div>
      <p>
       Adjust the path to
       <span class="command">
        <strong>
         unix_chkpwd
        </strong>
       </span>
       as
              necessary for your platform.
      </p>
     </li>
    </ul>
   </div>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="pam-pluggable-authentication-debugging">
       </a>
       PAM Authentication Debugging
      </h5>
     </div>
    </div>
   </div>
   <a class="indexterm" name="idm46045245594832">
   </a>
   <a class="indexterm" name="idm46045245593728">
   </a>
   <p>
    The PAM authentication plugin checks at initialization time
          whether the
    <code class="literal">
     AUTHENTICATION_PAM_LOG
    </code>
    environment value is set. If so, the plugin enables logging of
          diagnostic messages to the standard output. These messages may
          be helpful for debugging PAM-related issues that occur when
          the plugin performs authentication.
   </p>
   <p>
    Setting
    <code class="literal">
     AUTHENTICATION_PAM_LOG=1
    </code>
    (or some
          other arbitrary value) does
    <span class="emphasis">
     <em>
      not
     </em>
    </span>
    include
          any passwords. If you wish to include passwords in these
          messages, set
    <code class="literal">
     AUTHENTICATION_PAM_LOG=PAM_LOG_WITH_SECRET_INFO
    </code>
    .
   </p>
   <p>
    Some messages include reference to PAM plugin source files and
          line numbers, which enables plugin actions to be tied more
          closely to the location in the code where they occur.
   </p>
   <p>
    Another technique for debugging connection failures and
          determining what is happening during connection attempts is to
          configure PAM authentication to permit all connections, then
          check the system log files. This technique should be used only
          on a
    <span class="emphasis">
     <em>
      temporary
     </em>
    </span>
    basis, and not on a
          production server.
   </p>
   <p>
    Configure a PAM service file named
    <code class="filename">
     /etc/pam.d/mysql-any-password
    </code>
    with these
          contents (the format may differ on some systems):
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-none"><div class="docs-select-all right" id="sa97504416"><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">#%PAM-1.0
auth        required    pam_permit.so
account     required    pam_permit.so</code></pre>
   </div>
   <p>
    Create an account that uses the PAM plugin and names the
    <code class="literal">
     mysql-any-password
    </code>
    PAM service:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa90682320"><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">'testuser'</span>@<span class="token string">'localhost'</span>
  <span class="token keyword">IDENTIFIED</span> <span class="token keyword">WITH</span> authentication_pam
  <span class="token keyword">AS</span> <span class="token string">'mysql-any-password'</span><span class="token punctuation">;</span></code></pre>
   </div>
   <p>
    The
    <code class="literal">
     mysql-any-password
    </code>
    service file causes
          any authentication attempt to return true, even for incorrect
          passwords. If an authentication attempt fails, that tells you
          the configuration problem is on the MySQL side. Otherwise, the
          problem is on the operating system/PAM side. To see what might
          be happening, check system log files such as
    <code class="filename">
     /var/log/secure
    </code>
    ,
    <code class="filename">
     /var/log/audit.log
    </code>
    ,
    <code class="filename">
     /var/log/syslog
    </code>
    , or
    <code class="filename">
     /var/log/messages
    </code>
    .
   </p>
   <p>
    After determining what the problem is, remove the
    <code class="filename">
     mysql-any-password
    </code>
    PAM service file to
          disable any-password access.
   </p>
  </div>
 </div>
 <br/>
</div>
