MySQL Lists are EOL. Please join:

List:Commits« Previous MessageNext Message »
From:paul.dubois Date:November 10 2010 1:19am
Subject:svn commit - mysqldoc@docsrva: r23639 - in trunk: . dynamic-docs/changelog dynamic-docs/command-optvars refman-5.5 refman-5.6
View as plain text  
Author: paul
Date: 2010-11-10 02:19:26 +0100 (Wed, 10 Nov 2010)
New Revision: 23639

Log:
 r65299@frost:  paul | 2010-11-09 19:17:13 -0500
 WL#1054: pluggable authentication
 Add remaining information


Modified:
   trunk/dynamic-docs/changelog/mysqld-2.xml
   trunk/dynamic-docs/changelog/mysqld-versions.xml
   trunk/dynamic-docs/command-optvars/mysql.xml
   trunk/dynamic-docs/command-optvars/mysqld.xml
   trunk/refman-5.5/dba-mysqld-server-core.xml
   trunk/refman-5.5/dba-privilege-system.xml
   trunk/refman-5.5/dba-user-management-core.xml
   trunk/refman-5.5/programs-client-core.xml
   trunk/refman-5.5/sql-syntax-server-administration.xml
   trunk/refman-5.6/dba-mysqld-server-core.xml
   trunk/refman-5.6/dba-privilege-system.xml
   trunk/refman-5.6/dba-user-management-core.xml
   trunk/refman-5.6/programs-client-core.xml
   trunk/refman-5.6/sql-syntax-server-administration.xml

Property changes on: trunk
___________________________________________________________________
Name: svk:merge
   - 07c7e7b4-24e3-4b51-89d0-6dc09fec6bec:/mysqldoc-local/mysqldoc/trunk:35498
07c7e7b4-24e3-4b51-89d0-6dc09fec6bec:/mysqldoc-local/trunk:44052
4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:43968
4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/trunk:44480
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:65296
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:39036
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/trunk:39546
   + 07c7e7b4-24e3-4b51-89d0-6dc09fec6bec:/mysqldoc-local/mysqldoc/trunk:35498
07c7e7b4-24e3-4b51-89d0-6dc09fec6bec:/mysqldoc-local/trunk:44052
4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:43968
4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/trunk:44480
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:65299
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:39036
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/trunk:39546


Modified: trunk/dynamic-docs/changelog/mysqld-2.xml
===================================================================
--- trunk/dynamic-docs/changelog/mysqld-2.xml	2010-11-10 01:19:14 UTC (rev 23638)
+++ trunk/dynamic-docs/changelog/mysqld-2.xml	2010-11-10 01:19:26 UTC (rev 23639)
Changed blocks: 3, Lines Added: 270, Lines Deleted: 6; 10745 bytes

@@ -908,8 +908,8 @@
         timeout for epochs. Suppose the cluster is configured such that
         <literal role="ndbparam:ndbd">TimeBetweenEpochsTimeout</literal>
         is 100 ms but
-        <literal role="ndbparam:ndbd">HeartbeatIntervalDbDb</literal> is 1500
-        ms. A node failure can be signalled after 4 missed
+        <literal role="ndbparam:ndbd">HeartbeatIntervalDbDb</literal> is
+        1500 ms. A node failure can be signalled after 4 missed
         heartbeats&mdash;in this case, 6000 ms. However, this would
         exceed
         <literal role="ndbparam:ndbd">TimeBetweenEpochsTimeout</literal>,

@@ -925,10 +925,10 @@
         The current issue arose when the automatic adjustment routine
         did not correctly take into consideration the fact that, during
         cascading node-failures, several intervals of length <literal>4
-        * (HeartbeatIntervalDBDB + ArbitrationTimeout)</literal> may elapse
-        before all node failures have internally been resolved. This
-        could cause false GCP detection in the event of a cascading node
-        failure.
+        * (HeartbeatIntervalDBDB + ArbitrationTimeout)</literal> may
+        elapse before all node failures have internally been resolved.
+        This could cause false GCP detection in the event of a cascading
+        node failure.
       </para>
 
     </message>

@@ -31043,4 +31043,268 @@
 
   </logentry>
 
+  <logentry entrytype="custom" customname="authentication" customtitle="Authentication Changes:">
+
+    <tags>
+      <manual type="authentication"/>
+      <manual type="proxy users"/>
+      <manual type="CREATE USER"/>
+      <manual type="GRANT"/>
+      <manual type="REVOKE"/>
+      <manual type="proxies_priv"/>
+    </tags>
+
+    <versions>
+      <version ver="5.5.7"/>
+    </versions>
+
+    <message>
+
+      <para>
+        MySQL authentication supports two new capabilities, pluggable
+        authentication and proxy users:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            With pluggable authentication, the server can use plugins to
+            authenticate incoming client connections, and clients can
+            load an authentication plugin that interacts properly with
+            the corresponding server plugin. This capability enables
+            clients to connect to the MySQL server with credentials that
+            are appropriate for authentication methods other than the
+            built-in MySQL authentication based on native MySQL
+            passwords stored in the <literal>mysql.user</literal> table.
+            For example, plugins can be created to use external
+            authentication methods such as LDAP, Kerberos, PAM, or
+            Windows login IDs.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Proxy user capability enables a client who connects and
+            authenticates as one user to be treated, for purposes of
+            access control while connected, as having the privileges of
+            a different user. In effect, one user impersonates another.
+            Proxy capability depends on pluggable authentication because
+            it is based on having an authentication plugin return to the
+            server the user name that the connecting user impersonates.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        Pluggable authentication entails these changes:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            For user specifications in the <literal role="stmt">CREATE
+            USER</literal> and <literal role="stmt">GRANT</literal>
+            statements, a new <literal>IDENTIFIED WITH</literal> clause
+            for specifying the authentication plugin.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            For the <literal>mysql.user</literal> table, new columns
+            that specify plugin information. The
+            <literal>plugin</literal> column, if nonempty, indicates
+            which plugin authenticates connections for an account. The
+            <literal>authentication_string</literal> column is a string
+            that is passed to the plugin.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            For the <literal role="cfunc">mysql_options()</literal> C
+            API function, new <literal>MYSQL_DEFAULT_AUTH</literal> and
+            <literal>MYSQL_PLUGIN_DIR</literal> options that enable
+            client programs to load authentication plugins.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            For the <command>mysql</command> client, new
+            <option role="mysql">--default-auth</option> and
+            <option role="mysql">--plugin-dir</option> options for
+            specifying which authentication plugin and plugin directory
+            to use.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            For the <command>mysqltest</command> client, a new
+            <option role="mysql">--plugin-dir</option> option for
+            specifying which plugin directory to use, and a new
+            <literal>connect()</literal> command argument to specify an
+            authentication plugin.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            For the server plugin API, a new
+            <literal>MYSQL_AUTHENTICATION_PLUGIN</literal> plugin type.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            A client plugin API that enables client programs to manage
+            plugins.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Reimplementation of the built-in authentication methods
+            previously supported in MySQL as plugins. These methods
+            provide native password checking and pre-MySQL 4.1.1
+            authentication that uses shorter password hash values. This
+            change only reimplements the built-in methods as plugins
+            that cannot be unloaded. Existing clients authenticate as
+            before with no changes needed. In particular, starting the
+            server with the <option role="mysqld">--secure-auth</option>
+            option still prevents clients that have pre-4.1.1 password
+            hashes from conecting, and
+            <option role="mysqld">--skip-grant-tables</option> still
+            disables all password checking.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        Proxy user capability entails these changes:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            A new <literal role="priv">PROXY</literal> privilege that
+            can be managed with the <literal role="stmt">GRANT</literal>
+            and <literal role="stmt">REVOKE</literal> statements.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            New <literal role="sysvar">proxy_user</literal> and
+            <literal role="sysvar">external_user</literal> system
+            variables that indicate whether the current session uses
+            proxying.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            A new <literal>mysql.proxies_priv</literal> grant table that
+            records proxy information for MySQL accounts.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        Due to these changes, the server requires that the new grant
+        table, <literal>proxies_priv</literal>, be present in the
+        <literal>mysql</literal> database. If you are upgrading from a
+        previous MySQL release rather than performing a new
+        installation, the server will exit during startup after finding
+        that this table is missing. To create the table, start the
+        server with the
+        <option role="mysqld">--skip-grant-tables</option> option to
+        cause it to skip the normal grant table checks, then run
+        <command>mysql_upgrade</command>. For example:
+      </para>
+
+<programlisting>
+shell&gt; <userinput>mysqld --skip-grant-tables &amp;</userinput>
+shell&gt; <userinput>mysql_upgrade</userinput>
+</programlisting>
+
+      <para>
+        Then stop the server and restart it normally.
+      </para>
+
+      <para>
+        You can specify other options on the <command>mysqld</command>
+        command line if necessary. Alternatively, if your installation
+        is configured so that the server normally reads options from an
+        option file, use the
+        <option role="general">--defaults-file</option> option to
+        specify the file (enter each command on a single line):
+      </para>
+
+<programlisting>
+shell&gt; <userinput>mysqld --defaults-file=/usr/local/mysql/etc/my.cnf</userinput>
+         <userinput>--skip-grant-tables &amp;</userinput>
+shell&gt; <userinput>mysql_upgrade</userinput>
+</programlisting>
+
+      <para>
+        With the <option role="mysqld">--skip-grant-tables</option>
+        option, the server does no password or privilege checking, so
+        any client can connect and effectively have all privilges. For
+        additional security, use the
+        <option role="mysqld">--skip-networking</option> option as well
+        to prevent remote clients from connecting.
+      </para>
+
+      <para>
+        For additional information, consult these references:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            Information about pluggable authentication, including
+            installation and usage instructions:
+            <xref linkend="pluggable-authentication"/>.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Information about proxy users:
+            <xref linkend="proxy-users"/>.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Information about the server and client plugin API:
+            <xref linkend="plugin-general-data-structures"/>.
+          </para>
+          <remark role="todo">
+            Also need XREF to client API section.
+          </remark>
+        </listitem>
+
+        <listitem>
+          <para>
+            Information about the C API functions for managing client
+            plugins: See <xref linkend="c-api-plugin-functions"/>.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+    </message>
+
+  </logentry>
+
 </changelog>


Modified: trunk/dynamic-docs/changelog/mysqld-versions.xml
===================================================================
--- trunk/dynamic-docs/changelog/mysqld-versions.xml	2010-11-10 01:19:14 UTC (rev 23638)
+++ trunk/dynamic-docs/changelog/mysqld-versions.xml	2010-11-10 01:19:26 UTC (rev 23639)
Changed blocks: 1, Lines Added: 1, Lines Deleted: 48; 2707 bytes

@@ -35,54 +35,7 @@
 -->
   <versionentry ver="5.6.0" reldate="Not yet released"/>
   <versionentry ver="5.5.8" reldate="Not yet released"/>
-  <versionentry ver="5.5.7" reldate="14 October 2010">
-
-    <versionentrypreamble>
-
-      <para>
-        For this release, the server requires that a new grant table,
-        <literal>proxies_priv</literal>, be present in the
-        <literal>mysql</literal> database. If you are upgrading from a
-        previous MySQL release rather than performing a new
-        installation, the server will exit during startup after finding
-        that this table is missing. To create the table, start the
-        server with the
-        <option role="mysqld">--skip-grant-tables</option> option to
-        cause it to skip the normal grant table checks, then run
-        <command>mysql_upgrade</command>. For example:
-      </para>
-<programlisting>
-shell&gt; <userinput>mysqld --skip-grant-tables &amp;</userinput>
-shell&gt; <userinput>mysql_upgrade</userinput>
-</programlisting>
-      <para>
-        Then stop the server and restart it normally.
-      </para>
-      <para>
-        You can specify other options on the <command>mysqld</command>
-        command line if necessary. Alternatively, if your installation
-        is configured so that the server normally reads options from an
-        option file, use the
-        <option role="general">--defaults-file</option> option to
-        specify the file (enter each command on a single line):
-      </para>
-<programlisting>
-shell&gt; <userinput>mysqld --defaults-file=/usr/local/mysql/etc/my.cnf</userinput>
-         <userinput>--skip-grant-tables &amp;</userinput>
-shell&gt; <userinput>mysql_upgrade</userinput>
-</programlisting>
-      <para>
-        With the <option role="mysqld">--skip-grant-tables</option>
-        option, the server does no password or privilege checking, so
-        any client can connect and effectively have all privilges. For
-        additional security, use the
-        <option role="mysqld">--skip-networking</option> option as well
-        to prevent remote clients from connecting.
-      </para>
-
-    </versionentrypreamble>
-
-  </versionentry>
+  <versionentry ver="5.5.7" reldate="14 October 2010"/>
   <versionentry ver="5.5.6" reldate="13 September 2010" rellevel="Release Candidate"/>
   <versionentry ver="5.5.5" reldate="06 July 2010"/>
   <versionentry ver="5.5.4" reldate="09 April 2010"/>


Modified: trunk/dynamic-docs/command-optvars/mysql.xml
===================================================================
--- trunk/dynamic-docs/command-optvars/mysql.xml	2010-11-10 01:19:14 UTC (rev 23638)
+++ trunk/dynamic-docs/command-optvars/mysql.xml	2010-11-10 01:19:26 UTC (rev 23639)
Changed blocks: 2, Lines Added: 50, Lines Deleted: 0; 1605 bytes

@@ -501,6 +501,31 @@
 
   </mysqloption>
 
+  <mysqloption id="default-auth">
+
+    <xrefto id="option_mysql_default-auth"/>
+
+    <name>default-auth</name>
+
+    <shortdescription>
+      The authentication plugin to use
+    </shortdescription>
+
+    <types>
+      <optype class="cmdline" format="--default-auth=plugin"/>
+      <optype class="mycnf" format="default-auth=plugin"/>
+    </types>
+
+    <values vartype="string" platform="all"/>
+
+    <versions>
+      <manual version="5.5"/>
+      <introduced version="5.5.7"/>
+      <manual version="5.6"/>
+    </versions>
+
+  </mysqloption>
+
   <mysqloption id="default-character-set">
 
     <xrefto id="option_mysql_default-character-set"/>

@@ -1129,6 +1154,31 @@
 
   </mysqloption>
 
+  <mysqloption id="plugin-dir">
+
+    <xrefto id="option_mysql_plugin-dir"/>
+
+    <name>plugin-dir</name>
+
+    <shortdescription>
+      The directory where plugins are located
+    </shortdescription>
+
+    <types>
+      <optype class="cmdline" format="--plugin-dir=path"/>
+      <optype class="mycnf" format="plugin-dir=path"/>
+    </types>
+
+    <values vartype="dirname" platform="all"/>
+
+    <versions>
+      <manual version="5.5"/>
+      <introduced version="5.5.7"/>
+      <manual version="5.6"/>
+    </versions>
+
+  </mysqloption>
+
   <mysqloption id="port">
 
     <xrefto id="option_mysql_port"/>


Modified: trunk/dynamic-docs/command-optvars/mysqld.xml
===================================================================
--- trunk/dynamic-docs/command-optvars/mysqld.xml	2010-11-10 01:19:14 UTC (rev 23638)
+++ trunk/dynamic-docs/command-optvars/mysqld.xml	2010-11-10 01:19:26 UTC (rev 23639)
Changed blocks: 2, Lines Added: 48, Lines Deleted: 0; 1566 bytes

@@ -10657,6 +10657,30 @@
 
   </mysqloption>
 
+  <mysqloption section="server" id="external_user">
+
+    <xrefto id="sysvar_external_user"/>
+
+    <name>external_user</name>
+
+    <shortdescription>
+      The external proxy user
+    </shortdescription>
+
+    <types>
+      <vartype class="system" isdynamic="no" scope="session"/>
+    </types>
+
+    <values vartype="string" platform="all"/>
+
+    <versions>
+      <manual version="5.5"/>
+      <introduced version="5.5.7"/>
+      <manual version="5.6"/>
+    </versions>
+
+  </mysqloption>
+
   <mysqloption section="server" id="external-locking">
 
     <xrefto id="option_mysqld_external-locking"/>

@@ -19792,6 +19816,30 @@
 
   </mysqloption>
 
+  <mysqloption section="server" id="proxy_user">
+
+    <xrefto id="sysvar_proxy_user"/>
+
+    <name>proxy_user</name>
+
+    <shortdescription>
+      The user proxied by the external proxy user
+    </shortdescription>
+
+    <types>
+      <vartype class="system" isdynamic="no" scope="session"/>
+    </types>
+
+    <values vartype="string" platform="all"/>
+
+    <versions>
+      <manual version="5.5"/>
+      <introduced version="5.5.7"/>
+      <manual version="5.6"/>
+    </versions>
+
+  </mysqloption>
+
   <mysqloption section="server" id="pseudo_thread_id">
 
     <xrefto id="sysvar_pseudo_thread_id"/>


Modified: trunk/refman-5.5/dba-mysqld-server-core.xml
===================================================================
--- trunk/refman-5.5/dba-mysqld-server-core.xml	2010-11-10 01:19:14 UTC (rev 23638)
+++ trunk/refman-5.5/dba-mysqld-server-core.xml	2010-11-10 01:19:26 UTC (rev 23639)
Changed blocks: 3, Lines Added: 63, Lines Deleted: 0; 2787 bytes

@@ -5117,6 +5117,33 @@
       </listitem>
 
       <listitem>
+        <para id="sysvar_external_user">
+          <indexterm>
+            <primary>external_user session variable</primary>
+          </indexterm>
+
+          <indexterm>
+            <primary>session variable</primary>
+            <secondary>external_user</secondary>
+          </indexterm>
+
+          <literal role="sysvar">external_user</literal>
+        </para>
+
+        <para condition="dynamic:optvar:item" role="5.5:mysqld:external_user"/>
+
+        <para>
+          The extern user name used during the authentication process.
+          With native (built-in) MySQL authentication, this variable is
+          empty. See <xref linkend="proxy-users"/>.
+        </para>
+
+        <para>
+          This variable was added in MySQL 5.5.7.
+        </para>
+      </listitem>
+
+      <listitem>
         <para id="sysvar_flush">
           <indexterm>
             <primary>flush system variable</primary>

@@ -8365,6 +8392,33 @@
       </listitem>
 
       <listitem>
+        <para id="sysvar_proxy_user">
+          <indexterm>
+            <primary>proxy_user session variable</primary>
+          </indexterm>
+
+          <indexterm>
+            <primary>session variable</primary>
+            <secondary>proxy_user</secondary>
+          </indexterm>
+
+          <literal role="sysvar">proxy_user</literal>
+        </para>
+
+        <para condition="dynamic:optvar:item" role="5.5:mysqld:proxy_user"/>
+
+        <para>
+          If the current client is a proxy for another user, this
+          variable is the proxy user account name. Otherwise, this
+          variable is empty. See <xref linkend="proxy-users"/>.
+        </para>
+
+        <para>
+          This variable was added in MySQL 5.5.7.
+        </para>
+      </listitem>
+
+      <listitem>
         <para id="sysvar_pseudo_thread_id">
           <indexterm>
             <primary>pseudo_thread_id system variable</primary>

@@ -14510,6 +14564,15 @@
           from automatically creating new users if it would otherwise do
           so, unless a nonempty password also is specified.
         </para>
+
+        <para>
+          This mode has no effect for
+          <literal role="stmt">GRANT</literal> statements that include
+          an <literal>IDENTIFIED WITH</literal> clause. That is,
+          <literal role="stmt" condition="grant">GRANT ... IDENTIFIED
+          WITH</literal> creates nonexistent users regardless of the
+          mode setting.
+        </para>
       </listitem>
 
       <listitem>


Modified: trunk/refman-5.5/dba-privilege-system.xml
===================================================================
--- trunk/refman-5.5/dba-privilege-system.xml	2010-11-10 01:19:14 UTC (rev 23638)
+++ trunk/refman-5.5/dba-privilege-system.xml	2010-11-10 01:19:26 UTC (rev 23639)
Changed blocks: 6, Lines Added: 103, Lines Deleted: 0; 4431 bytes

@@ -624,6 +624,15 @@
       </listitem>
 
       <listitem>
+        <para id="priv_proxy">
+          The <literal role="priv">PROXY</literal> privilege enables a
+          user to impersonate or become known as another user. See
+          <xref linkend="proxy-users"/>. This privilege was added in
+          MySQL 5.5.7.
+        </para>
+      </listitem>
+
+      <listitem>
         <para id="priv_references">
           The <literal role="priv">REFERENCES</literal> privilege
           currently is unused.

@@ -947,6 +956,13 @@
         </para>
       </listitem>
 
+      <listitem>
+        <para>
+          <literal>proxies_priv</literal>: Contains proxy-user
+          privileges.
+        </para>
+      </listitem>
+
     </itemizedlist>
 
     <para>

@@ -1153,6 +1169,15 @@
         </para>
       </listitem>
 
+      <listitem>
+        <para>
+          The <literal>proxies_priv</literal> table indicates which
+          users can act as proxies for other users and whether proxy
+          users can grant the <literal role="priv">PROXY</literal>
+          privilege to other users.
+        </para>
+      </listitem>
+
     </itemizedlist>
 
     <para>

@@ -1362,6 +1387,16 @@
             <entry/>
           </row>
           <row>
+            <entry/>
+            <entry><literal>plugin</literal></entry>
+            <entry/>
+          </row>
+          <row>
+            <entry/>
+            <entry><literal>authentication_string</literal></entry>
+            <entry/>
+          </row>
+          <row>
             <entry><emphasis role="bold">Resource control columns</emphasis></entry>
             <entry><literal>max_questions</literal></entry>
             <entry/>

@@ -1386,6 +1421,27 @@
     </table>
 
     <para>
+      As of MySQL 5.5.7, the <literal>mysql.user</literal> table has
+      <literal>plugin</literal> and
+      <literal>authentication_string</literal> columns for storing
+      authentication plugin information.
+    </para>
+
+    <para>
+      If the <literal>plugin</literal> column for an account row is
+      empty, the server uses its built-in authentication for connection
+      attempts for the account. Clients must match the password in the
+      <literal>Password</literal> column of the account row.
+    </para>
+
+    <para>
+      If an account row names a plugin in the <literal>plugin</literal>
+      column, the server uses it to authenticate connection attempts for
+      the account. Whether the plugin uses the value in the
+      <literal>Password</literal> column is up to the plugin.
+    </para>
+
+    <para>
       During the second stage of access control, the server performs
       request verification to make sure that each client has sufficient
       privileges for each request that it issues. In addition to the

@@ -1536,6 +1592,53 @@
     </para>
 
     <para>
+      The <literal>proxies_priv</literal> table was added in MySQL 5.5.7
+      and records information about proxy users. It has these columns:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <literal>Host</literal>, <literal>User</literal>: These
+          columns indicate the user account that has the
+          <literal role="priv">PROXY</literal> privilege for the proxied
+          account.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <literal>Proxied_host</literal>,
+          <literal>Proxied_user</literal>: These columns indicate the
+          account of the proxied user.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <literal>Grantor</literal>: Currently unused.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <literal>Timestamp</literal>: Currently unused.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <literal>With_grant</literal>: This column indicates whether
+          the proxy account can grant the
+          <literal role="priv">PROXY</literal> privilege to other
+          accounts.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
       Scope columns in the grant tables contain strings. They are
       declared as shown here; the default value for each is the empty
       string.


Modified: trunk/refman-5.5/dba-user-management-core.xml
===================================================================
--- trunk/refman-5.5/dba-user-management-core.xml	2010-11-10 01:19:14 UTC (rev 23638)
+++ trunk/refman-5.5/dba-user-management-core.xml	2010-11-10 01:19:26 UTC (rev 23639)
Changed blocks: 1, Lines Added: 605, Lines Deleted: 0; 21049 bytes

@@ -1243,6 +1243,611 @@
 
   </section>
 
+  <section id="pluggable-authentication">
+
+    <title>Pluggable Authentication</title>
+
+    <para>
+      Before MySQL 5.5.7, when a client connects to the server, the
+      server uses the user name provided by the client and the client
+      host to determine which <literal>mysql.user</literal> table
+      account row to use for authentication. The server authenticates
+      the password provided by the client against the
+      <literal>Password</literal> column of the account row.
+    </para>
+
+    <para>
+      As of MySQL 5.5.7, the server authenticates clients using plugins.
+      Selection of the proper row from the <literal>mysql.user</literal>
+      table is based on the user name and client host, as before, but
+      the server authenticates the client credentials as follows:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          The server determines which authentication plugin applies for
+          the user:
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              If the account row specifies no plugin name, the server
+              uses built-in authentication against the password stored
+              in the account row. MySQL includes two built-in
+              authentication plugins that cannot be disabled (except by
+              starting the server with the
+              <option role="mysqld">--skip-grant-tables</option>
+              option). These plugins provide native password checking
+              and pre-MySQL 4.1.1 authentication that uses shorter
+              password hash values. This is the same authentication
+              provided by MySQL servers older than 5.5.7 that matches
+              the password against the <literal>Password</literal>
+              column of the account row.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              If the account row specifies a plugin, the server invokes
+              it to authenticate the user.
+            </para>
+          </listitem>
+
+        </itemizedlist>
+      </listitem>
+
+      <listitem>
+        <para>
+          The plugin returns a status to the server indicating whether
+          the user is permitted to connect.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          If the user is permitted to connect, the plugin may also
+          return a user name to indicate that the user is a proxy for
+          another user. In this case, the connecting user is a proxy for
+          another user: The proxy user impersonates the proxied user.
+          While the connection lasts, the proxy user has the access
+          privileges of the proxied user. For more information, see
+          <xref linkend="proxy-users"/>.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <section id="using-authentication-plugins">
+
+      <title>Installing and Using Authentication Plugins</title>
+
+      <para>
+        Pluggable authentication uses corresponding plugins on the
+        client and server sides:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            Install the server plugin so that the server can use it to
+            authenticate client connections.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Indicate to the client program when you run it to use the
+            corresponding client plugin when it connects to the server.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        The following example shows how to install and use an
+        authentication plugin using the example plugin included in MySQL
+        distributions. The server plugin and client plugins are named
+        <literal>test_plugin_server</literal> and
+        <literal>auth_test_plugin</literal>, respectively. Both plugins
+        are located in the shared object file named
+        <filename>auth_test_plugin.so</filename> in the plugin directory
+        (the directory named by the
+        <literal role="sysvar">plugin_dir</literal> system variable). If
+        object files have a suffix different from
+        <filename>.so</filename> on your system, substitute the correct
+        suffix throughout. The procedure shown is the same for other
+        authentication plugins. Just substitute the appropriate plugin
+        name and file name.
+      </para>
+
+      <para>
+        The server-side test plugin can be installed at server startup
+        or at runtime:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            To install the plugin at startup, use the
+            <option role="mysqld">--plugin-load</option> option. For
+            example, use these lines in a <filename>my.cnf</filename>
+            option file:
+          </para>
+
+<programlisting>
+[mysqld]
+plugin-load=test_plugin_server=auth_test_plugin.so
+</programlisting>
+
+          <para>
+            With this plugin-loading method, if the server is started
+            without the option, the plugin is not installed.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            To install the plugin at runtime, use the
+            <literal role="stmt">INSTALL PLUGIN</literal> statement:
+          </para>
+
+<programlisting>
+mysql&gt; <userinput>INSTALL PLUGIN test_plugin_server SONAME 'auth_test_plugin.so';</userinput>
+</programlisting>
+
+          <para>
+            This installs the plugin permanently and need be done only
+            once.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        Use <literal role="stmt">SHOW PLUGINS</literal> to verify that
+        the plugin is installed:
+      </para>
+
+<programlisting>
+mysql&gt; <userinput>SHOW PLUGINS\G</userinput>
+...
+*************************** 21. row ***************************
+   Name: test_plugin_server
+ Status: ACTIVE
+   Type: AUTHENTICATION
+Library: auth_test_plugin.so
+License: GPL
+</programlisting>
+
+      <para>
+        To tell the <command>mysql</command> client to use the client
+        authentication plugin corresponding to the server-side plugin,
+        use the
+        <option role="mysql">--default-auth=auth_test_plugin</option>
+        option. The test plugin authenticates the same way as MySQL
+        built-in authentication, so provide the usual
+        <option role="mysql">--user</option> and
+        <option role="mysql">--password</option> options that you
+        normally use in addition to
+        <option role="mysql">--default-auth</option> (enter the command
+        on a single line):
+      </para>
+
+<programlisting>
+shell&gt; <userinput>mysql --default-auth=auth_test_plugin</userinput>
+         <userinput>--user=<replaceable>your_name</replaceable> --password=<replaceable>your_pass</replaceable></userinput>
+</programlisting>
+
+      <para>
+        If <command>mysql</command> does not find the plugin, specify a
+        <option role="mysql">--plugin-dir=<replaceable>dir_name</replaceable></option>
+        option to indicate where the plugin is located.
+      </para>
+
+      <para>
+        MySQL includes two built-in plugins that implement the same kind
+        of authentication that older servers provide:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            <literal>mysql_native_password</literal>: Implements the
+            same default authentication against the
+            <literal>mysql.user</literal> table as used previously.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <literal>mysql_old_password</literal>: Implements
+            authentication as used before MySQL 4.1.1 that is based on
+            shorter password hash values. For information about this
+            authentication method, see
+            <xref linkend="password-hashing"/>.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        Each plugin exists in both client and server form. The
+        <command>mysql</command> client uses
+        <literal>mysql_native_password</literal> by default. The
+        <option role="mysql">--default-auth</option> option can be used
+        to select either plugin explicitly:
+      </para>
+
+<programlisting>
+shell&gt; <userinput>mysql --default-auth=mysql_native_password ...</userinput>
+shell&gt; <userinput>mysql --default-auth=mysql_old_password ...</userinput>
+</programlisting>
+
+      <para>
+        The built-in authentication plugins are backward compatible.
+        Clients older than MySQL 5.5.7 do not support authentication
+        plugins but use built-in authentication, so they can connect to
+        servers from 5.5.7 and up.
+      </para>
+
+      <note>
+        <para>
+          Server plugins, including authentication plugins, are disabled
+          if you start the server with the
+          <option role="mysqld">--skip-grant-tables</option> option. In
+          this case, the server performs no client authentication and
+          permits any client to connect. Because this is insecure, you
+          might want to use
+          <option role="mysqld">--skip-grant-tables</option> in
+          conjunction with
+          <option role="mysqld">--skip-networking</option> to prevent
+          remote clients from connecting.
+        </para>
+      </note>
+
+    </section>
+
+    <section id="authentication-plugin-information">
+
+      <title>Obtaining Authentication Plugin Information</title>
+
+      <para>
+        To determine which authentication plugins are installed in the
+        server, use the <literal role="stmt">SHOW PLUGINS</literal>
+        statement or the
+        <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            With <literal role="stmt">SHOW PLUGINS</literal>, look for
+            rows with a <literal>Type</literal> value of
+            <literal>AUTHENTICATION</literal>. Any that have a
+            <literal>Library</literal> value of <literal>NULL</literal>
+            are built in and cannot be unloaded.
+          </para>
+
+<programlisting>
+mysql&gt; <userinput>SHOW PLUGINS;</userinput>
++-----------------------+--------+--------------------+---------+---------+
+| Name                  | Status | Type               | Library | License |
++-----------------------+--------+--------------------+---------+---------+
+| binlog                | ACTIVE | STORAGE ENGINE     | NULL    | GPL     |
+| mysql_native_password | ACTIVE | AUTHENTICATION     | NULL    | GPL     |
+| mysql_old_password    | ACTIVE | AUTHENTICATION     | NULL    | GPL     |
+...
+</programlisting>
+        </listitem>
+
+        <listitem>
+          <para>
+            With the
+            <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal>
+            table, look for rows with a <literal>PLUGIN_TYPE</literal>
+            value of <literal>AUTHENTICATION</literal>. Any that have a
+            <literal>PLUGIN_LIBRARY</literal> value of
+            <literal>NULL</literal> are built in and cannot be unloaded.
+          </para>
+
+<programlisting>
+mysql&gt; <userinput>SELECT * FROM INFORMATION_SCHEMA.PLUGINS</userinput>
+    -&gt; <userinput>WHERE PLUGIN_TYPE='AUTHENTICATION'\G</userinput>
+*************************** 1. row ***************************
+           PLUGIN_NAME: mysql_native_password
+        PLUGIN_VERSION: 1.0
+         PLUGIN_STATUS: ACTIVE
+           PLUGIN_TYPE: AUTHENTICATION
+   PLUGIN_TYPE_VERSION: 1.0
+        PLUGIN_LIBRARY: NULL
+PLUGIN_LIBRARY_VERSION: NULL
+         PLUGIN_AUTHOR: R.J.Silk, Sergei Golubchik
+    PLUGIN_DESCRIPTION: Native MySQL authentication
+        PLUGIN_LICENSE: GPL
+           LOAD_OPTION: FORCE
+*************************** 2. row ***************************
+           PLUGIN_NAME: mysql_old_password
+        PLUGIN_VERSION: 1.0
+         PLUGIN_STATUS: ACTIVE
+           PLUGIN_TYPE: AUTHENTICATION
+   PLUGIN_TYPE_VERSION: 1.0
+        PLUGIN_LIBRARY: NULL
+PLUGIN_LIBRARY_VERSION: NULL
+         PLUGIN_AUTHOR: R.J.Silk, Sergei Golubchik
+    PLUGIN_DESCRIPTION: Old MySQL-4.0 authentication
+        PLUGIN_LICENSE: GPL
+           LOAD_OPTION: FORCE
+</programlisting>
+        </listitem>
+
+      </itemizedlist>
+
+    </section>
+
+  </section>
+
+  <section id="proxy-users">
+
+    <title>Proxy Users</title>
+
+    <para>
+      An authentication plugin may request that an externally defined
+      user should authenticate with the server as a differently named
+      MySQL user. Consider the following definitions:
+    </para>
+
+<programlisting>
+CREATE USER 'external_auth' IDENTIFIED WITH auth_plugin AS ...;
+CREATE USER 'employee' IDENTIFIED BY ...;
+CREATE USER 'manager' IDENTIFIED BY ...;
+GRANT PROXY ON 'employee' TO 'external_auth';
+</programlisting>
+
+    <para>
+      Now when a client connects as <literal>external_auth</literal>,
+      the <literal>auth_plugin</literal> plugin, based on some external
+      criteria, may return the <literal>employee</literal> user name to
+      the server to request that this client should become the
+      <literal>employee</literal> local user.
+    </para>
+
+    <para>
+      In this case, <literal>external_auth</literal> is a <quote>proxy
+      user</quote> (a user who can impersonate or become known as
+      another user) and <literal>employee</literal> is a <quote>proxied
+      user</quote> (a user whose identity can be taken by a proxy user).
+    </para>
+
+    <para>
+      The server verifies that external proxy authentication for
+      <literal>employee</literal> is possible through the
+      <literal>external_auth</literal> user. It does this by checking
+      that the <literal>external_auth</literal> user has the
+      <literal role="priv">PROXY</literal> privilege for
+      <literal>employee</literal> user. An error occurs if
+      <literal>external_auth</literal> does not have the
+      <literal role="priv">PROXY</literal> privilege for
+      <literal>employee</literal>.
+    </para>
+
+    <bridgehead>
+      Default Proxy Users
+    </bridgehead>
+
+    <para>
+      To specify that some or all users should connect using an external
+      plugin, create a <quote>blank</quote> MySQL user, set it up to use
+      plugin authentication, and let the plugin return the real
+      authenticated user name (if different from the blank user). For
+      example:
+    </para>
+
+<programlisting>
+CREATE USER ''@'' IDENTIFIED WITH ldap_plugin AS 'O=Oracle, OU=MySQL';
+CREATE USER 'developer' IDENTIFIED BY 'test';
+CREATE USER 'manager' IDENTIFIED BY 'test2';
+GRANT PROXY ON 'manager' TO ''@'';
+GRANT PROXY ON 'developer' TO ''@'';
+</programlisting>
+
+    <para>
+      Now assume that a client tries to connect as follows:
+    </para>
+
+<programlisting>
+mysql --user=myuser --password='myuser_pass' ...
+</programlisting>
+
+    <para>
+      The server will not find <literal>myuser</literal> defined as a
+      MySQL user. But because there is a blank user
+      (<literal>''@''</literal>) it invokes
+      <literal>ldap_plugin</literal>, passing it
+      <literal>myuser</literal> and <literal>myuser_pass</literal>.
+    </para>
+
+    <para>
+      Suppose that <literal>ldap_plugin</literal> finds in the LDAP
+      directory that <literal>myuser</literal> is a developer. It will
+      return <literal>developer</literal> to the MySQL server. The
+      server then checks whether <literal>''@''</literal> can
+      authenticate as <literal>developer</literal> and, if so, accepts
+      the connection, setting <literal>USER()</literal> and
+      <literal>CURRENT_USER()</literal> as follows:
+    </para>
+
+<programlisting>
+mysql&gt; <userinput>SELECT USER(), CURRENT_USER;</userinput>
++------------------+--------------+
+| USER()           | CURRENT_USER |
++------------------+--------------+
+| myuser@localhost | developer@%  |
++------------------+--------------+
+</programlisting>
+
+    <para>
+      For simplicity, external authentication cannot be multilevel:
+      Neither the credentials for <literal>manager</literal> nor those
+      for <literal>developer</literal> are taken into account in the
+      preceding example. However, they are still used if a client tries
+      to authenticate directly against the <literal>developer</literal>
+      account.
+    </para>
+
+    <bridgehead>
+      Proxy User System Variables
+    </bridgehead>
+
+    <para>
+      Two system variables help trace the proxy login process:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <literal role="sysvar">proxy_user</literal>: The proxy user
+          account name used when connecting. This will be null if
+          proxying is not used. Using the example shown earlier, this
+          variable will be set as follows:
+        </para>
+
+<programlisting>
+mysql&gt; <userinput>SELECT @@proxy_user;</userinput>
++--------------+
+| @@proxy_user |
++--------------+
+| ''@''        |
++--------------+
+</programlisting>
+      </listitem>
+
+      <listitem>
+        <para>
+          <literal role="sysvar">external_user</literal>: Sometimes the
+          authentication plugin may use an external user to connect to
+          the MySQL server. For example, when using Windows native
+          authentication, a plugin that authenticates using the windows
+          API does not need the login ID passed to it. However, it still
+          uses an Windows user ID to authenticate. The plugin may return
+          this external user ID (or the first 512 UTF-8 bytes of it) to
+          the server using the <literal>external_user</literal>
+          read-only session variable. If there is no external user, this
+          variable contains an empty string.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <bridgehead>
+      Granting Proxy Privileges
+    </bridgehead>
+
+    <para>
+      A special <literal role="priv">PROXY</literal> privilege is needed
+      to enable an external authentication account to connect as another
+      user. To grant it, use the <literal role="stmt">GRANT</literal>
+      statement. For example:
+    </para>
+
+<programlisting>
+GRANT PROXY ON '<replaceable>proxied_user</replaceable>' TO '<replaceable>proxy_user</replaceable>';
+</programlisting>
+
+    <para>
+      <replaceable>proxied_user</replaceable> must represent a valid
+      locally authenticated user at connection time or connection
+      attempts fail. <replaceable>proxy_user</replaceable> must
+      represent a valid externally authenticated MySQL user at
+      connection time or connection attempts fail.
+    </para>
+
+    <para>
+      The corresponding <literal role="stmt">REVOKE</literal> syntax is:
+    </para>
+
+<programlisting>
+REVOKE PROXY ON '<replaceable>proxied_user</replaceable>' FROM '<replaceable>proxy_user</replaceable>';
+</programlisting>
+
+    <para>
+      MySQL <literal role="stmt">GRANT</literal> and
+      <literal role="stmt">REVOKE</literal> syntax extensions work as
+      usual. For example:
+    </para>
+
+<programlisting>
+GRANT PROXY ON 'a' TO 'b', 'c', 'd';
+GRANT PROXY ON * TO 'd';
+GRANT PROXY ON 'a' TO 'd' IDENTIFIED BY ...;
+GRANT PROXY ON 'a' TO 'd' WITH GRANT OPTION;
+REVOKE PROXY ON 'a' FROM 'b', 'c', 'd';
+</programlisting>
+
+    <para>
+      In the preceding example, the asterisk (<literal>*</literal>)
+      means <quote>any user.</quote>
+    </para>
+
+    <para>
+      The <literal role="priv">PROXY</literal> privilege can be granted
+      in these cases:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          By <replaceable>proxied_user</replaceable> for itself: The
+          value of <literal>USER()</literal> must exactly match
+          <literal>CURRENT_USER()</literal> and
+          <replaceable>proxied_user</replaceable>, for both the user
+          name and host name parts of the account name.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          By a user that has <literal>GRANT PROXY ... WITH GRANT
+          OPTION</literal> on that name.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      The <literal>root</literal> account created by default during
+      MySQL installation has the
+      <literal role="priv" condition="proxy">PROXY ... WITH GRANT
+      OPTION</literal> privilege for all users. For example,
+      <literal>root</literal> can do this:
+    </para>
+
+<programlisting>
+CREATE USER 'ldap_admin' IDENTIFIED BY 'test';
+GRANT PROXY ON * TO 'ldap_admin' WITH GRANT OPTION;
+</programlisting>
+
+    <para>
+      Now the <literal>ldap_admin</literal> user can manage all the
+      specific <literal>GRANT PROXY</literal> mappings. For example,
+      <literal>ldap_admin</literal> can do this:
+    </para>
+
+<programlisting>
+GRANT PROXY ON sally TO joe;
+</programlisting>
+
+  </section>
+
   <section id="secure-connections">
 
     <title>Using SSL for Secure Connections</title>


Modified: trunk/refman-5.5/programs-client-core.xml
===================================================================
--- trunk/refman-5.5/programs-client-core.xml	2010-11-10 01:19:14 UTC (rev 23638)
+++ trunk/refman-5.5/programs-client-core.xml	2010-11-10 01:19:26 UTC (rev 23639)
Changed blocks: 2, Lines Added: 54, Lines Deleted: 0; 2312 bytes

@@ -508,6 +508,31 @@
         </listitem>
 
         <listitem>
+          <para id="option_mysql_default-auth">
+            <indexterm>
+              <primary>mysql</primary>
+              <secondary>default-auth option</secondary>
+            </indexterm>
+
+            <indexterm>
+              <primary>default-auth option</primary>
+              <secondary>mysql</secondary>
+            </indexterm>
+
+            <option role="mysql">--default-auth=<replaceable>plugin</replaceable></option>
+          </para>
+
+          <para>
+            The client-side authentication plugin to use. See
+            <xref linkend="pluggable-authentication"/>.
+          </para>
+
+          <para>
+            This option was added in MySQL 5.5.7.
+          </para>
+        </listitem>
+
+        <listitem>
           <para id="option_mysql_default-character-set">
             <indexterm>
               <primary>mysql</primary>

@@ -1077,6 +1102,35 @@
         </listitem>
 
         <listitem>
+          <para id="option_mysql_plugin-dir">
+            <indexterm>
+              <primary>mysql</primary>
+              <secondary>plugin-dir option</secondary>
+            </indexterm>
+
+            <indexterm>
+              <primary>plugin-dir option</primary>
+              <secondary>mysql</secondary>
+            </indexterm>
+
+            <option role="mysql">--plugin-dir=<replaceable>path</replaceable></option>
+          </para>
+
+          <para>
+            The directory in which to look for plugins. It may be
+            necessary to specify this option if the
+            <option role="mysql">--default-auth</option> option is used
+            to specify an authentication plugin but
+            <command>mysql</command> does not find it. See
+            <xref linkend="pluggable-authentication"/>.
+          </para>
+
+          <para>
+            This option was added in MySQL 5.5.7.
+          </para>
+        </listitem>
+
+        <listitem>
           <para id="option_mysql_port">
             <indexterm>
               <primary>mysql</primary>


Modified: trunk/refman-5.5/sql-syntax-server-administration.xml
===================================================================
--- trunk/refman-5.5/sql-syntax-server-administration.xml	2010-11-10 01:19:14 UTC (rev 23638)
+++ trunk/refman-5.5/sql-syntax-server-administration.xml	2010-11-10 01:19:26 UTC (rev 23639)
Changed blocks: 8, Lines Added: 76, Lines Deleted: 7; 5470 bytes

@@ -64,7 +64,11 @@
     [, <replaceable>user_specification</replaceable>] ...
 
 <replaceable>user_specification</replaceable>:
-    <replaceable>user</replaceable> [IDENTIFIED BY [PASSWORD] '<replaceable>password</replaceable>']
+    <replaceable>user</replaceable>
+    [
+        IDENTIFIED BY [PASSWORD] '<replaceable>password</replaceable>'
+      | IDENTIFIED WITH <replaceable>auth_plugin</replaceable> [AS '<replaceable>auth_string</replaceable>']
+    ]
 </programlisting>
 
       <remark role="help-description-begin"/>

@@ -112,8 +116,9 @@
 </programlisting>
 
           <para>
-            <emphasis>Creating an account with no password is
-            insecure.</emphasis>
+            In this case, the server uses built-in authentication and
+            clients must provide no password. <emphasis>Creating an
+            account with no password is insecure.</emphasis>
           </para>
         </listitem>
 

@@ -126,6 +131,11 @@
 <programlisting>
 CREATE USER 'jeffrey'@'localhost' IDENTIFIED BY 'mypass';
 </programlisting>
+
+          <para>
+            The server uses built-in authentication and clients must
+            match the given password.
+          </para>
         </listitem>
 
         <listitem>

@@ -141,11 +151,47 @@
 CREATE USER 'jeffrey'@'localhost'
 IDENTIFIED BY PASSWORD '*90E462C37378CED12064BB3388827D2BA3A9B689';
 </programlisting>
+
+          <para>
+            The server uses built-in authentication and clients must
+            match the given password.
+          </para>
         </listitem>
 
+        <listitem>
+          <para>
+            If the account should authenticate using a specific
+            authentication plugin, use <literal>IDENTIFIED
+            WITH</literal>. <replaceable>auth_plugin</replaceable> is an
+            authentication plugin name. It can be an unquoted name or a
+            quoted string literal.
+            <literal>'<replaceable>auth_string</replaceable>'</literal>
+            is an optional quoted string literal to pass to the plugin.
+            The plugin interprets the meaning of the string.
+          </para>
+
+<programlisting>
+CREATE USER 'jeffrey'@'localhost'
+IDENTIFIED WITH my_auth_plugin;
+</programlisting>
+
+          <para>
+            The server uses the named plugin and clients must provide
+            credentials as required for the authentication method that
+            the plugin implements. This clause can be given as of MySQL
+            5.5.7.
+          </para>
+        </listitem>
+
       </itemizedlist>
 
       <para>
+        The <literal>IDENTIFIED BY</literal> and <literal>IDENTIFIED
+        WITH</literal> clauses are mutually exclusive, so at most one of
+        them can be specified for a given user.
+      </para>
+
+      <para>
         For additional information about setting passwords, see
         <xref linkend="assigning-passwords"/>.
       </para>

@@ -331,7 +377,11 @@
   | <replaceable>db_name</replaceable>.<replaceable>routine_name</replaceable>
 
 <replaceable>user_specification</replaceable>:
-    <replaceable>user</replaceable> [IDENTIFIED BY [PASSWORD] '<replaceable>password</replaceable>']
+    <replaceable>user</replaceable>
+    [
+        IDENTIFIED BY [PASSWORD] '<replaceable>password</replaceable>'
+      | IDENTIFIED WITH <replaceable>auth_plugin</replaceable> [AS '<replaceable>auth_string</replaceable>']
+    ]
 
 <replaceable>ssl_option</replaceable>:
     SSL

@@ -504,6 +554,10 @@
                 PROCESSLIST</literal></entry>
             </row>
             <row>
+              <entry><literal role="priv">PROXY</literal></entry>
+              <entry>Enable user proxying</entry>
+            </row>
+            <row>
               <entry><literal role="priv">REFERENCES</literal></entry>
               <entry>Not implemented</entry>
             </row>

@@ -563,6 +617,11 @@
       </table>
 
       <para>
+        The <literal role="priv">PROXY</literal> privilege was added in
+        MySQL 5.5.7.
+      </para>
+
+      <para>
         A trigger is associated with a table, so to create or drop a
         trigger, you must have the
         <literal role="priv">TRIGGER</literal> privilege for the table,

@@ -1011,11 +1070,21 @@
       </para>
 
       <para>
+        The <literal role="sqlmode">NO_AUTO_CREATE_USER</literal> SQL
+        mode has no effect for <literal role="stmt">GRANT</literal>
+        statements that include an <literal>IDENTIFIED WITH</literal>
+        clause. That is, <literal role="stmt" condition="grant">GRANT
+        ... IDENTIFIED WITH</literal> creates nonexistent users
+        regardless of the mode setting.
+      </para>
+
+      <para>
         The user specification may indicate how the user should
         authenticate when connecting to the server, through inclusion of
-        an <literal>IDENTIFIED BY</literal> clause. The syntax is the
-        same as for the <literal role="stmt">CREATE USER</literal>
-        statement. See <xref linkend="create-user"/>.
+        an <literal>IDENTIFIED BY</literal> or <literal>IDENTIFIED
+        WITH</literal> clause. The syntax is the same as for the
+        <literal role="stmt">CREATE USER</literal> statement. See
+        <xref linkend="create-user"/>.
       </para>
 
       <para>


Modified: trunk/refman-5.6/dba-mysqld-server-core.xml
===================================================================
--- trunk/refman-5.6/dba-mysqld-server-core.xml	2010-11-10 01:19:14 UTC (rev 23638)
+++ trunk/refman-5.6/dba-mysqld-server-core.xml	2010-11-10 01:19:26 UTC (rev 23639)
Changed blocks: 3, Lines Added: 55, Lines Deleted: 0; 2623 bytes

@@ -4926,6 +4926,29 @@
       </listitem>
 
       <listitem>
+        <para id="sysvar_external_user">
+          <indexterm>
+            <primary>external_user session variable</primary>
+          </indexterm>
+
+          <indexterm>
+            <primary>session variable</primary>
+            <secondary>external_user</secondary>
+          </indexterm>
+
+          <literal role="sysvar">external_user</literal>
+        </para>
+
+        <para condition="dynamic:optvar:item" role="5.6:mysqld:external_user"/>
+
+        <para>
+          The extern user name used during the authentication process.
+          With native (built-in) MySQL authentication, this variable is
+          empty. See <xref linkend="proxy-users"/>.
+        </para>
+      </listitem>
+
+      <listitem>
         <para id="sysvar_flush">
           <indexterm>
             <primary>flush system variable</primary>

@@ -8136,6 +8159,29 @@
       </listitem>
 
       <listitem>
+        <para id="sysvar_proxy_user">
+          <indexterm>
+            <primary>proxy_user session variable</primary>
+          </indexterm>
+
+          <indexterm>
+            <primary>session variable</primary>
+            <secondary>proxy_user</secondary>
+          </indexterm>
+
+          <literal role="sysvar">proxy_user</literal>
+        </para>
+
+        <para condition="dynamic:optvar:item" role="5.6:mysqld:proxy_user"/>
+
+        <para>
+          If the current client is a proxy for another user, this
+          variable is the proxy user account name. Otherwise, this
+          variable is empty. See <xref linkend="proxy-users"/>.
+        </para>
+      </listitem>
+
+      <listitem>
         <para id="sysvar_pseudo_thread_id">
           <indexterm>
             <primary>pseudo_thread_id system variable</primary>

@@ -14181,6 +14227,15 @@
           from automatically creating new users if it would otherwise do
           so, unless a nonempty password also is specified.
         </para>
+
+        <para>
+          This mode has no effect for
+          <literal role="stmt">GRANT</literal> statements that include
+          an <literal>IDENTIFIED WITH</literal> clause. That is,
+          <literal role="stmt" condition="grant">GRANT ... IDENTIFIED
+          WITH</literal> creates nonexistent users regardless of the
+          mode setting.
+        </para>
       </listitem>
 
       <listitem>


Modified: trunk/refman-5.6/dba-privilege-system.xml
===================================================================
--- trunk/refman-5.6/dba-privilege-system.xml	2010-11-10 01:19:14 UTC (rev 23638)
+++ trunk/refman-5.6/dba-privilege-system.xml	2010-11-10 01:19:26 UTC (rev 23639)
Changed blocks: 6, Lines Added: 101, Lines Deleted: 0; 4316 bytes

@@ -624,6 +624,14 @@
       </listitem>
 
       <listitem>
+        <para id="priv_proxy">
+          The <literal role="priv">PROXY</literal> privilege enables a
+          user to impersonate or become known as another user. See
+          <xref linkend="proxy-users"/>.
+        </para>
+      </listitem>
+
+      <listitem>
         <para id="priv_references">
           The <literal role="priv">REFERENCES</literal> privilege
           currently is unused.

@@ -947,6 +955,13 @@
         </para>
       </listitem>
 
+      <listitem>
+        <para>
+          <literal>proxies_priv</literal>: Contains proxy-user
+          privileges.
+        </para>
+      </listitem>
+
     </itemizedlist>
 
     <para>

@@ -1153,6 +1168,15 @@
         </para>
       </listitem>
 
+      <listitem>
+        <para>
+          The <literal>proxies_priv</literal> table indicates which
+          users can act as proxies for other users and whether proxy
+          users can grant the <literal role="priv">PROXY</literal>
+          privilege to other users.
+        </para>
+      </listitem>
+
     </itemizedlist>
 
     <para>

@@ -1362,6 +1386,16 @@
             <entry/>
           </row>
           <row>
+            <entry/>
+            <entry><literal>plugin</literal></entry>
+            <entry/>
+          </row>
+          <row>
+            <entry/>
+            <entry><literal>authentication_string</literal></entry>
+            <entry/>
+          </row>
+          <row>
             <entry><emphasis role="bold">Resource control columns</emphasis></entry>
             <entry><literal>max_questions</literal></entry>
             <entry/>

@@ -1386,6 +1420,26 @@
     </table>
 
     <para>
+      The <literal>mysql.user</literal> table <literal>plugin</literal>
+      and <literal>authentication_string</literal> columns store
+      authentication plugin information.
+    </para>
+
+    <para>
+      If the <literal>plugin</literal> column for an account row is
+      empty, the server uses its built-in authentication for connection
+      attempts for the account. Clients must match the password in the
+      <literal>Password</literal> column of the account row.
+    </para>
+
+    <para>
+      If an account row names a plugin in the <literal>plugin</literal>
+      column, the server uses it to authenticate connection attempts for
+      the account. Whether the plugin uses the value in the
+      <literal>Password</literal> column is up to the plugin.
+    </para>
+
+    <para>
       During the second stage of access control, the server performs
       request verification to make sure that each client has sufficient
       privileges for each request that it issues. In addition to the

@@ -1536,6 +1590,53 @@
     </para>
 
     <para>
+      The <literal>proxies_priv</literal> table records information
+      about proxy users. It has these columns:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <literal>Host</literal>, <literal>User</literal>: These
+          columns indicate the user account that has the
+          <literal role="priv">PROXY</literal> privilege for the proxied
+          account.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <literal>Proxied_host</literal>,
+          <literal>Proxied_user</literal>: These columns indicate the
+          account of the proxied user.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <literal>Grantor</literal>: Currently unused.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <literal>Timestamp</literal>: Currently unused.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <literal>With_grant</literal>: This column indicates whether
+          the proxy account can grant the
+          <literal role="priv">PROXY</literal> privilege to other
+          accounts.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
       Scope columns in the grant tables contain strings. They are
       declared as shown here; the default value for each is the empty
       string.


Modified: trunk/refman-5.6/dba-user-management-core.xml
===================================================================
--- trunk/refman-5.6/dba-user-management-core.xml	2010-11-10 01:19:14 UTC (rev 23638)
+++ trunk/refman-5.6/dba-user-management-core.xml	2010-11-10 01:19:26 UTC (rev 23639)
Changed blocks: 1, Lines Added: 605, Lines Deleted: 0; 21049 bytes

@@ -1243,6 +1243,611 @@
 
   </section>
 
+  <section id="pluggable-authentication">
+
+    <title>Pluggable Authentication</title>
+
+    <para>
+      Before MySQL 5.5.7, when a client connects to the server, the
+      server uses the user name provided by the client and the client
+      host to determine which <literal>mysql.user</literal> table
+      account row to use for authentication. The server authenticates
+      the password provided by the client against the
+      <literal>Password</literal> column of the account row.
+    </para>
+
+    <para>
+      As of MySQL 5.5.7, the server authenticates clients using plugins.
+      Selection of the proper row from the <literal>mysql.user</literal>
+      table is based on the user name and client host, as before, but
+      the server authenticates the client credentials as follows:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          The server determines which authentication plugin applies for
+          the user:
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              If the account row specifies no plugin name, the server
+              uses built-in authentication against the password stored
+              in the account row. MySQL includes two built-in
+              authentication plugins that cannot be disabled (except by
+              starting the server with the
+              <option role="mysqld">--skip-grant-tables</option>
+              option). These plugins provide native password checking
+              and pre-MySQL 4.1.1 authentication that uses shorter
+              password hash values. This is the same authentication
+              provided by MySQL servers older than 5.5.7 that matches
+              the password against the <literal>Password</literal>
+              column of the account row.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              If the account row specifies a plugin, the server invokes
+              it to authenticate the user.
+            </para>
+          </listitem>
+
+        </itemizedlist>
+      </listitem>
+
+      <listitem>
+        <para>
+          The plugin returns a status to the server indicating whether
+          the user is permitted to connect.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          If the user is permitted to connect, the plugin may also
+          return a user name to indicate that the user is a proxy for
+          another user. In this case, the connecting user is a proxy for
+          another user: The proxy user impersonates the proxied user.
+          While the connection lasts, the proxy user has the access
+          privileges of the proxied user. For more information, see
+          <xref linkend="proxy-users"/>.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <section id="using-authentication-plugins">
+
+      <title>Installing and Using Authentication Plugins</title>
+
+      <para>
+        Pluggable authentication uses corresponding plugins on the
+        client and server sides:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            Install the server plugin so that the server can use it to
+            authenticate client connections.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Indicate to the client program when you run it to use the
+            corresponding client plugin when it connects to the server.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        The following example shows how to install and use an
+        authentication plugin using the example plugin included in MySQL
+        distributions. The server plugin and client plugins are named
+        <literal>test_plugin_server</literal> and
+        <literal>auth_test_plugin</literal>, respectively. Both plugins
+        are located in the shared object file named
+        <filename>auth_test_plugin.so</filename> in the plugin directory
+        (the directory named by the
+        <literal role="sysvar">plugin_dir</literal> system variable). If
+        object files have a suffix different from
+        <filename>.so</filename> on your system, substitute the correct
+        suffix throughout. The procedure shown is the same for other
+        authentication plugins. Just substitute the appropriate plugin
+        name and file name.
+      </para>
+
+      <para>
+        The server-side test plugin can be installed at server startup
+        or at runtime:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            To install the plugin at startup, use the
+            <option role="mysqld">--plugin-load</option> option. For
+            example, use these lines in a <filename>my.cnf</filename>
+            option file:
+          </para>
+
+<programlisting>
+[mysqld]
+plugin-load=test_plugin_server=auth_test_plugin.so
+</programlisting>
+
+          <para>
+            With this plugin-loading method, if the server is started
+            without the option, the plugin is not installed.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            To install the plugin at runtime, use the
+            <literal role="stmt">INSTALL PLUGIN</literal> statement:
+          </para>
+
+<programlisting>
+mysql&gt; <userinput>INSTALL PLUGIN test_plugin_server SONAME 'auth_test_plugin.so';</userinput>
+</programlisting>
+
+          <para>
+            This installs the plugin permanently and need be done only
+            once.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        Use <literal role="stmt">SHOW PLUGINS</literal> to verify that
+        the plugin is installed:
+      </para>
+
+<programlisting>
+mysql&gt; <userinput>SHOW PLUGINS\G</userinput>
+...
+*************************** 21. row ***************************
+   Name: test_plugin_server
+ Status: ACTIVE
+   Type: AUTHENTICATION
+Library: auth_test_plugin.so
+License: GPL
+</programlisting>
+
+      <para>
+        To tell the <command>mysql</command> client to use the client
+        authentication plugin corresponding to the server-side plugin,
+        use the
+        <option role="mysql">--default-auth=auth_test_plugin</option>
+        option. The test plugin authenticates the same way as MySQL
+        built-in authentication, so provide the usual
+        <option role="mysql">--user</option> and
+        <option role="mysql">--password</option> options that you
+        normally use in addition to
+        <option role="mysql">--default-auth</option> (enter the command
+        on a single line):
+      </para>
+
+<programlisting>
+shell&gt; <userinput>mysql --default-auth=auth_test_plugin</userinput>
+         <userinput>--user=<replaceable>your_name</replaceable> --password=<replaceable>your_pass</replaceable></userinput>
+</programlisting>
+
+      <para>
+        If <command>mysql</command> does not find the plugin, specify a
+        <option role="mysql">--plugin-dir=<replaceable>dir_name</replaceable></option>
+        option to indicate where the plugin is located.
+      </para>
+
+      <para>
+        MySQL includes two built-in plugins that implement the same kind
+        of authentication that older servers provide:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            <literal>mysql_native_password</literal>: Implements the
+            same default authentication against the
+            <literal>mysql.user</literal> table as used previously.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <literal>mysql_old_password</literal>: Implements
+            authentication as used before MySQL 4.1.1 that is based on
+            shorter password hash values. For information about this
+            authentication method, see
+            <xref linkend="password-hashing"/>.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        Each plugin exists in both client and server form. The
+        <command>mysql</command> client uses
+        <literal>mysql_native_password</literal> by default. The
+        <option role="mysql">--default-auth</option> option can be used
+        to select either plugin explicitly:
+      </para>
+
+<programlisting>
+shell&gt; <userinput>mysql --default-auth=mysql_native_password ...</userinput>
+shell&gt; <userinput>mysql --default-auth=mysql_old_password ...</userinput>
+</programlisting>
+
+      <para>
+        The built-in authentication plugins are backward compatible.
+        Clients older than MySQL 5.5.7 do not support authentication
+        plugins but use built-in authentication, so they can connect to
+        servers from 5.5.7 and up.
+      </para>
+
+      <note>
+        <para>
+          Server plugins, including authentication plugins, are disabled
+          if you start the server with the
+          <option role="mysqld">--skip-grant-tables</option> option. In
+          this case, the server performs no client authentication and
+          permits any client to connect. Because this is insecure, you
+          might want to use
+          <option role="mysqld">--skip-grant-tables</option> in
+          conjunction with
+          <option role="mysqld">--skip-networking</option> to prevent
+          remote clients from connecting.
+        </para>
+      </note>
+
+    </section>
+
+    <section id="authentication-plugin-information">
+
+      <title>Obtaining Authentication Plugin Information</title>
+
+      <para>
+        To determine which authentication plugins are installed in the
+        server, use the <literal role="stmt">SHOW PLUGINS</literal>
+        statement or the
+        <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            With <literal role="stmt">SHOW PLUGINS</literal>, look for
+            rows with a <literal>Type</literal> value of
+            <literal>AUTHENTICATION</literal>. Any that have a
+            <literal>Library</literal> value of <literal>NULL</literal>
+            are built in and cannot be unloaded.
+          </para>
+
+<programlisting>
+mysql&gt; <userinput>SHOW PLUGINS;</userinput>
++-----------------------+--------+--------------------+---------+---------+
+| Name                  | Status | Type               | Library | License |
++-----------------------+--------+--------------------+---------+---------+
+| binlog                | ACTIVE | STORAGE ENGINE     | NULL    | GPL     |
+| mysql_native_password | ACTIVE | AUTHENTICATION     | NULL    | GPL     |
+| mysql_old_password    | ACTIVE | AUTHENTICATION     | NULL    | GPL     |
+...
+</programlisting>
+        </listitem>
+
+        <listitem>
+          <para>
+            With the
+            <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal>
+            table, look for rows with a <literal>PLUGIN_TYPE</literal>
+            value of <literal>AUTHENTICATION</literal>. Any that have a
+            <literal>PLUGIN_LIBRARY</literal> value of
+            <literal>NULL</literal> are built in and cannot be unloaded.
+          </para>
+
+<programlisting>
+mysql&gt; <userinput>SELECT * FROM INFORMATION_SCHEMA.PLUGINS</userinput>
+    -&gt; <userinput>WHERE PLUGIN_TYPE='AUTHENTICATION'\G</userinput>
+*************************** 1. row ***************************
+           PLUGIN_NAME: mysql_native_password
+        PLUGIN_VERSION: 1.0
+         PLUGIN_STATUS: ACTIVE
+           PLUGIN_TYPE: AUTHENTICATION
+   PLUGIN_TYPE_VERSION: 1.0
+        PLUGIN_LIBRARY: NULL
+PLUGIN_LIBRARY_VERSION: NULL
+         PLUGIN_AUTHOR: R.J.Silk, Sergei Golubchik
+    PLUGIN_DESCRIPTION: Native MySQL authentication
+        PLUGIN_LICENSE: GPL
+           LOAD_OPTION: FORCE
+*************************** 2. row ***************************
+           PLUGIN_NAME: mysql_old_password
+        PLUGIN_VERSION: 1.0
+         PLUGIN_STATUS: ACTIVE
+           PLUGIN_TYPE: AUTHENTICATION
+   PLUGIN_TYPE_VERSION: 1.0
+        PLUGIN_LIBRARY: NULL
+PLUGIN_LIBRARY_VERSION: NULL
+         PLUGIN_AUTHOR: R.J.Silk, Sergei Golubchik
+    PLUGIN_DESCRIPTION: Old MySQL-4.0 authentication
+        PLUGIN_LICENSE: GPL
+           LOAD_OPTION: FORCE
+</programlisting>
+        </listitem>
+
+      </itemizedlist>
+
+    </section>
+
+  </section>
+
+  <section id="proxy-users">
+
+    <title>Proxy Users</title>
+
+    <para>
+      An authentication plugin may request that an externally defined
+      user should authenticate with the server as a differently named
+      MySQL user. Consider the following definitions:
+    </para>
+
+<programlisting>
+CREATE USER 'external_auth' IDENTIFIED WITH auth_plugin AS ...;
+CREATE USER 'employee' IDENTIFIED BY ...;
+CREATE USER 'manager' IDENTIFIED BY ...;
+GRANT PROXY ON 'employee' TO 'external_auth';
+</programlisting>
+
+    <para>
+      Now when a client connects as <literal>external_auth</literal>,
+      the <literal>auth_plugin</literal> plugin, based on some external
+      criteria, may return the <literal>employee</literal> user name to
+      the server to request that this client should become the
+      <literal>employee</literal> local user.
+    </para>
+
+    <para>
+      In this case, <literal>external_auth</literal> is a <quote>proxy
+      user</quote> (a user who can impersonate or become known as
+      another user) and <literal>employee</literal> is a <quote>proxied
+      user</quote> (a user whose identity can be taken by a proxy user).
+    </para>
+
+    <para>
+      The server verifies that external proxy authentication for
+      <literal>employee</literal> is possible through the
+      <literal>external_auth</literal> user. It does this by checking
+      that the <literal>external_auth</literal> user has the
+      <literal role="priv">PROXY</literal> privilege for
+      <literal>employee</literal> user. An error occurs if
+      <literal>external_auth</literal> does not have the
+      <literal role="priv">PROXY</literal> privilege for
+      <literal>employee</literal>.
+    </para>
+
+    <bridgehead>
+      Default Proxy Users
+    </bridgehead>
+
+    <para>
+      To specify that some or all users should connect using an external
+      plugin, create a <quote>blank</quote> MySQL user, set it up to use
+      plugin authentication, and let the plugin return the real
+      authenticated user name (if different from the blank user). For
+      example:
+    </para>
+
+<programlisting>
+CREATE USER ''@'' IDENTIFIED WITH ldap_plugin AS 'O=Oracle, OU=MySQL';
+CREATE USER 'developer' IDENTIFIED BY 'test';
+CREATE USER 'manager' IDENTIFIED BY 'test2';
+GRANT PROXY ON 'manager' TO ''@'';
+GRANT PROXY ON 'developer' TO ''@'';
+</programlisting>
+
+    <para>
+      Now assume that a client tries to connect as follows:
+    </para>
+
+<programlisting>
+mysql --user=myuser --password='myuser_pass' ...
+</programlisting>
+
+    <para>
+      The server will not find <literal>myuser</literal> defined as a
+      MySQL user. But because there is a blank user
+      (<literal>''@''</literal>) it invokes
+      <literal>ldap_plugin</literal>, passing it
+      <literal>myuser</literal> and <literal>myuser_pass</literal>.
+    </para>
+
+    <para>
+      Suppose that <literal>ldap_plugin</literal> finds in the LDAP
+      directory that <literal>myuser</literal> is a developer. It will
+      return <literal>developer</literal> to the MySQL server. The
+      server then checks whether <literal>''@''</literal> can
+      authenticate as <literal>developer</literal> and, if so, accepts
+      the connection, setting <literal>USER()</literal> and
+      <literal>CURRENT_USER()</literal> as follows:
+    </para>
+
+<programlisting>
+mysql&gt; <userinput>SELECT USER(), CURRENT_USER;</userinput>
++------------------+--------------+
+| USER()           | CURRENT_USER |
++------------------+--------------+
+| myuser@localhost | developer@%  |
++------------------+--------------+
+</programlisting>
+
+    <para>
+      For simplicity, external authentication cannot be multilevel:
+      Neither the credentials for <literal>manager</literal> nor those
+      for <literal>developer</literal> are taken into account in the
+      preceding example. However, they are still used if a client tries
+      to authenticate directly against the <literal>developer</literal>
+      account.
+    </para>
+
+    <bridgehead>
+      Proxy User System Variables
+    </bridgehead>
+
+    <para>
+      Two system variables help trace the proxy login process:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <literal role="sysvar">proxy_user</literal>: The proxy user
+          account name used when connecting. This will be null if
+          proxying is not used. Using the example shown earlier, this
+          variable will be set as follows:
+        </para>
+
+<programlisting>
+mysql&gt; <userinput>SELECT @@proxy_user;</userinput>
++--------------+
+| @@proxy_user |
++--------------+
+| ''@''        |
++--------------+
+</programlisting>
+      </listitem>
+
+      <listitem>
+        <para>
+          <literal role="sysvar">external_user</literal>: Sometimes the
+          authentication plugin may use an external user to connect to
+          the MySQL server. For example, when using Windows native
+          authentication, a plugin that authenticates using the windows
+          API does not need the login ID passed to it. However, it still
+          uses an Windows user ID to authenticate. The plugin may return
+          this external user ID (or the first 512 UTF-8 bytes of it) to
+          the server using the <literal>external_user</literal>
+          read-only session variable. If there is no external user, this
+          variable contains an empty string.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <bridgehead>
+      Granting Proxy Privileges
+    </bridgehead>
+
+    <para>
+      A special <literal role="priv">PROXY</literal> privilege is needed
+      to enable an external authentication account to connect as another
+      user. To grant it, use the <literal role="stmt">GRANT</literal>
+      statement. For example:
+    </para>
+
+<programlisting>
+GRANT PROXY ON '<replaceable>proxied_user</replaceable>' TO '<replaceable>proxy_user</replaceable>';
+</programlisting>
+
+    <para>
+      <replaceable>proxied_user</replaceable> must represent a valid
+      locally authenticated user at connection time or connection
+      attempts fail. <replaceable>proxy_user</replaceable> must
+      represent a valid externally authenticated MySQL user at
+      connection time or connection attempts fail.
+    </para>
+
+    <para>
+      The corresponding <literal role="stmt">REVOKE</literal> syntax is:
+    </para>
+
+<programlisting>
+REVOKE PROXY ON '<replaceable>proxied_user</replaceable>' FROM '<replaceable>proxy_user</replaceable>';
+</programlisting>
+
+    <para>
+      MySQL <literal role="stmt">GRANT</literal> and
+      <literal role="stmt">REVOKE</literal> syntax extensions work as
+      usual. For example:
+    </para>
+
+<programlisting>
+GRANT PROXY ON 'a' TO 'b', 'c', 'd';
+GRANT PROXY ON * TO 'd';
+GRANT PROXY ON 'a' TO 'd' IDENTIFIED BY ...;
+GRANT PROXY ON 'a' TO 'd' WITH GRANT OPTION;
+REVOKE PROXY ON 'a' FROM 'b', 'c', 'd';
+</programlisting>
+
+    <para>
+      In the preceding example, the asterisk (<literal>*</literal>)
+      means <quote>any user.</quote>
+    </para>
+
+    <para>
+      The <literal role="priv">PROXY</literal> privilege can be granted
+      in these cases:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          By <replaceable>proxied_user</replaceable> for itself: The
+          value of <literal>USER()</literal> must exactly match
+          <literal>CURRENT_USER()</literal> and
+          <replaceable>proxied_user</replaceable>, for both the user
+          name and host name parts of the account name.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          By a user that has <literal>GRANT PROXY ... WITH GRANT
+          OPTION</literal> on that name.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      The <literal>root</literal> account created by default during
+      MySQL installation has the
+      <literal role="priv" condition="proxy">PROXY ... WITH GRANT
+      OPTION</literal> privilege for all users. For example,
+      <literal>root</literal> can do this:
+    </para>
+
+<programlisting>
+CREATE USER 'ldap_admin' IDENTIFIED BY 'test';
+GRANT PROXY ON * TO 'ldap_admin' WITH GRANT OPTION;
+</programlisting>
+
+    <para>
+      Now the <literal>ldap_admin</literal> user can manage all the
+      specific <literal>GRANT PROXY</literal> mappings. For example,
+      <literal>ldap_admin</literal> can do this:
+    </para>
+
+<programlisting>
+GRANT PROXY ON sally TO joe;
+</programlisting>
+
+  </section>
+
   <section id="secure-connections">
 
     <title>Using SSL for Secure Connections</title>


Modified: trunk/refman-5.6/programs-client-core.xml
===================================================================
--- trunk/refman-5.6/programs-client-core.xml	2010-11-10 01:19:14 UTC (rev 23638)
+++ trunk/refman-5.6/programs-client-core.xml	2010-11-10 01:19:26 UTC (rev 23639)
Changed blocks: 2, Lines Added: 46, Lines Deleted: 0; 2140 bytes

@@ -507,6 +507,27 @@
         </listitem>
 
         <listitem>
+          <para id="option_mysql_default-auth">
+            <indexterm>
+              <primary>mysql</primary>
+              <secondary>default-auth option</secondary>
+            </indexterm>
+
+            <indexterm>
+              <primary>default-auth option</primary>
+              <secondary>mysql</secondary>
+            </indexterm>
+
+            <option role="mysql">--default-auth=<replaceable>plugin</replaceable></option>
+          </para>
+
+          <para>
+            The client-side authentication plugin to use. See
+            <xref linkend="pluggable-authentication"/>.
+          </para>
+        </listitem>
+
+        <listitem>
           <para id="option_mysql_default-character-set">
             <indexterm>
               <primary>mysql</primary>

@@ -1004,6 +1025,31 @@
         </listitem>
 
         <listitem>
+          <para id="option_mysql_plugin-dir">
+            <indexterm>
+              <primary>mysql</primary>
+              <secondary>plugin-dir option</secondary>
+            </indexterm>
+
+            <indexterm>
+              <primary>plugin-dir option</primary>
+              <secondary>mysql</secondary>
+            </indexterm>
+
+            <option role="mysql">--plugin-dir=<replaceable>path</replaceable></option>
+          </para>
+
+          <para>
+            The directory in which to look for plugins. It may be
+            necessary to specify this option if the
+            <option role="mysql">--default-auth</option> option is used
+            to specify an authentication plugin but
+            <command>mysql</command> does not find it. See
+            <xref linkend="pluggable-authentication"/>.
+          </para>
+        </listitem>
+
+        <listitem>
           <para id="option_mysql_port">
             <indexterm>
               <primary>mysql</primary>


Modified: trunk/refman-5.6/sql-syntax-server-administration.xml
===================================================================
--- trunk/refman-5.6/sql-syntax-server-administration.xml	2010-11-10 01:19:14 UTC (rev 23638)
+++ trunk/refman-5.6/sql-syntax-server-administration.xml	2010-11-10 01:19:26 UTC (rev 23639)
Changed blocks: 7, Lines Added: 70, Lines Deleted: 7; 5068 bytes

@@ -64,7 +64,11 @@
     [, <replaceable>user_specification</replaceable>] ...
 
 <replaceable>user_specification</replaceable>:
-    <replaceable>user</replaceable> [IDENTIFIED BY [PASSWORD] '<replaceable>password</replaceable>']
+    <replaceable>user</replaceable>
+    [
+        IDENTIFIED BY [PASSWORD] '<replaceable>password</replaceable>'
+      | IDENTIFIED WITH <replaceable>auth_plugin</replaceable> [AS '<replaceable>auth_string</replaceable>']
+    ]
 </programlisting>
 
       <remark role="help-description-begin"/>

@@ -112,8 +116,9 @@
 </programlisting>
 
           <para>
-            <emphasis>Creating an account with no password is
-            insecure.</emphasis>
+            In this case, the server uses built-in authentication and
+            clients must provide no password. <emphasis>Creating an
+            account with no password is insecure.</emphasis>
           </para>
         </listitem>
 

@@ -126,6 +131,11 @@
 <programlisting>
 CREATE USER 'jeffrey'@'localhost' IDENTIFIED BY 'mypass';
 </programlisting>
+
+          <para>
+            The server uses built-in authentication and clients must
+            match the given password.
+          </para>
         </listitem>
 
         <listitem>

@@ -141,11 +151,46 @@
 CREATE USER 'jeffrey'@'localhost'
 IDENTIFIED BY PASSWORD '*90E462C37378CED12064BB3388827D2BA3A9B689';
 </programlisting>
+
+          <para>
+            The server uses built-in authentication and clients must
+            match the given password.
+          </para>
         </listitem>
 
+        <listitem>
+          <para>
+            If the account should authenticate using a specific
+            authentication plugin, use <literal>IDENTIFIED
+            WITH</literal>. <replaceable>auth_plugin</replaceable> is an
+            authentication plugin name. It can be an unquoted name or a
+            quoted string literal.
+            <literal>'<replaceable>auth_string</replaceable>'</literal>
+            is an optional quoted string literal to pass to the plugin.
+            The plugin interprets the meaning of the string.
+          </para>
+
+<programlisting>
+CREATE USER 'jeffrey'@'localhost'
+IDENTIFIED WITH my_auth_plugin;
+</programlisting>
+
+          <para>
+            The server uses the named plugin and clients must provide
+            credentials as required for the authentication method that
+            the plugin implements.
+          </para>
+        </listitem>
+
       </itemizedlist>
 
       <para>
+        The <literal>IDENTIFIED BY</literal> and <literal>IDENTIFIED
+        WITH</literal> clauses are mutually exclusive, so at most one of
+        them can be specified for a given user.
+      </para>
+
+      <para>
         For additional information about setting passwords, see
         <xref linkend="assigning-passwords"/>.
       </para>

@@ -331,7 +376,11 @@
   | <replaceable>db_name</replaceable>.<replaceable>routine_name</replaceable>
 
 <replaceable>user_specification</replaceable>:
-    <replaceable>user</replaceable> [IDENTIFIED BY [PASSWORD] '<replaceable>password</replaceable>']
+    <replaceable>user</replaceable>
+    [
+        IDENTIFIED BY [PASSWORD] '<replaceable>password</replaceable>'
+      | IDENTIFIED WITH <replaceable>auth_plugin</replaceable> [AS '<replaceable>auth_string</replaceable>']
+    ]
 
 <replaceable>ssl_option</replaceable>:
     SSL

@@ -504,6 +553,10 @@
                 PROCESSLIST</literal></entry>
             </row>
             <row>
+              <entry><literal role="priv">PROXY</literal></entry>
+              <entry>Enable user proxying</entry>
+            </row>
+            <row>
               <entry><literal role="priv">REFERENCES</literal></entry>
               <entry>Not implemented</entry>
             </row>

@@ -1011,11 +1064,21 @@
       </para>
 
       <para>
+        The <literal role="sqlmode">NO_AUTO_CREATE_USER</literal> SQL
+        mode has no effect for <literal role="stmt">GRANT</literal>
+        statements that include an <literal>IDENTIFIED WITH</literal>
+        clause. That is, <literal role="stmt" condition="grant">GRANT
+        ... IDENTIFIED WITH</literal> creates nonexistent users
+        regardless of the mode setting.
+      </para>
+
+      <para>
         The user specification may indicate how the user should
         authenticate when connecting to the server, through inclusion of
-        an <literal>IDENTIFIED BY</literal> clause. The syntax is the
-        same as for the <literal role="stmt">CREATE USER</literal>
-        statement. See <xref linkend="create-user"/>.
+        an <literal>IDENTIFIED BY</literal> or <literal>IDENTIFIED
+        WITH</literal> clause. The syntax is the same as for the
+        <literal role="stmt">CREATE USER</literal> statement. See
+        <xref linkend="create-user"/>.
       </para>
 
       <para>


Thread
svn commit - mysqldoc@docsrva: r23639 - in trunk: . dynamic-docs/changelog dynamic-docs/command-optvars refman-5.5 refman-5.6paul.dubois10 Nov