<div id="docs-body">
 <div class="section">
  <div class="titlepage">
   <div>
    <div>
     <h4 class="title">
      <a name="test-pluggable-authentication">
      </a>
      8.4.1.12 Test Pluggable Authentication
     </h4>
    </div>
   </div>
  </div>
  <a class="indexterm" name="idm46045243849488">
  </a>
  <a class="indexterm" name="idm46045243848384">
  </a>
  <a class="indexterm" name="idm46045243846896">
  </a>
  <a class="indexterm" name="idm46045243845808">
  </a>
  <p>
   MySQL includes a test plugin that checks account credentials and
        logs success or failure to the server error log. This is a
        loadable plugin (not built in) and must be installed prior to
        use.
  </p>
  <p>
   The test plugin source code is separate from the server source,
        unlike the built-in native plugin, so it can be examined as a
        relatively simple example demonstrating how to write a loadable
        authentication plugin.
  </p>
  <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
   <div class="admon-title">
    Note
   </div>
   <p>
    This plugin is intended for testing and development purposes,
          and is not for use in production environments or on servers
          that are exposed to public networks.
   </p>
  </div>
  <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.
  </p>
  <div class="table">
   <a name="idm46045243840224">
   </a>
   <p class="title">
    <b>
     Table 8.27 Plugin and Library Names for Test Authentication
    </b>
   </p>
   <div class="table-contents">
    <table summary="Names for the plugins and library file used for test 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">
         test_plugin_server
        </code>
       </td>
      </tr>
      <tr>
       <td>
        Client-side plugin
       </td>
       <td>
        <code class="literal">
         auth_test_plugin
        </code>
       </td>
      </tr>
      <tr>
       <td>
        Library file
       </td>
       <td>
        <code class="filename">
         auth_test_plugin.so
        </code>
       </td>
      </tr>
     </tbody>
    </table>
   </div>
  </div>
  <br class="table-break"/>
  <p>
   The following sections provide installation and usage
        information specific to test pluggable authentication:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      <a class="xref" href="test-pluggable-authentication.html#test-pluggable-authentication-installation" title="Installing Test Pluggable Authentication">
       Installing Test Pluggable Authentication
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="test-pluggable-authentication.html#test-pluggable-authentication-uninstallation" title="Uninstalling Test Pluggable Authentication">
       Uninstalling Test Pluggable Authentication
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="test-pluggable-authentication.html#test-pluggable-authentication-usage" title="Using Test Pluggable Authentication">
       Using Test Pluggable Authentication
      </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>
   .
  </p>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="test-pluggable-authentication-installation">
       </a>
       Installing Test Pluggable Authentication
      </h5>
     </div>
    </div>
   </div>
   <p>
    This section describes how to install the server-side test
          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>
    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, adjusting the
    <code class="filename">
     .so
    </code>
    suffix for your platform as
          necessary:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-ini"><div class="docs-select-all right" id="sa93798454"><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>auth_test_plugin.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 for
          your platform as necessary:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting one-line language-sql"><div class="docs-select-all right" id="sa11745489"><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> test_plugin_server <span class="token keyword">SONAME</span> <span class="token string">'auth_test_plugin.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="sa44337853"><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">'%test_plugin%'</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> test_plugin_server <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 test plugin, see
    <a class="xref" href="test-pluggable-authentication.html#test-pluggable-authentication-usage" title="Using Test Pluggable Authentication">
     Using Test Pluggable Authentication
    </a>
    .
   </p>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="test-pluggable-authentication-uninstallation">
       </a>
       Uninstalling Test Pluggable Authentication
      </h5>
     </div>
    </div>
   </div>
   <p>
    The method used to uninstall the test 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="sa9991986"><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> test_plugin_server<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="test-pluggable-authentication-usage">
       </a>
       Using Test Pluggable Authentication
      </h5>
     </div>
    </div>
   </div>
   <p>
    To use the test authentication plugin, create an account and
          name that plugin in the
    <code class="literal">
     IDENTIFIED WITH
    </code>
    clause:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa44256260"><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> test_plugin_server
<span class="token keyword">BY</span> <span class="token string">'<em class="replaceable">testpassword</em>'</span><span class="token punctuation">;</span></code></pre>
   </div>
   <p>
    The test authentication plugin also requires creating a proxy
          user as follows:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa91352052"><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> testpassword<span class="token variable">@localhost</span><span class="token punctuation">;</span>
<span class="token keyword">GRANT</span> <span class="token keyword">PROXY</span> <span class="token keyword">ON</span> testpassword<span class="token variable">@localhost</span> <span class="token keyword">TO</span> testuser<span class="token variable">@localhost</span><span class="token punctuation">;</span></code></pre>
   </div>
   <p>
    Then provide the
    <a class="link" href="connection-options.html#option_general_user">
     <code class="option">
      --user
     </code>
    </a>
    and
    <a class="link" href="connection-options.html#option_general_password">
     <code class="option">
      --password
     </code>
    </a>
    options for that
          account when you connect to the server. For example:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-terminal"><div class="docs-select-all right" id="sa55961003"><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>testuser</span> <span class="token property">--password</span>
Enter password<span class="token punctuation">:</span> <em class="replaceable">testpassword</em></code></pre>
   </div>
   <p>
    The plugin fetches the password as received from the client
          and compares it with the value stored in the
    <code class="literal">
     authentication_string
    </code>
    column of the account
          row in the
    <code class="literal">
     mysql.user
    </code>
    system table. If the
          two values match, the plugin returns the
    <code class="literal">
     authentication_string
    </code>
    value as the new
          effective user ID.
   </p>
   <p>
    You can look in the server error log for a message indicating
          whether authentication succeeded (notice that the password is
          reported as the
    <span class="quote">
     “
     <span class="quote">
      user
     </span>
     ”
    </span>
    ):
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-none"><div class="docs-select-all right" id="sa65096543"><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">[Note] Plugin test_plugin_server reported:
'successfully authenticated user <em class="replaceable">testpassword</em>'</code></pre>
   </div>
  </div>
 </div>
 <br/>
</div>
