When a client connects to the MySQL server, the server uses the
user name provided by the client and the client host to select the
appropriate account row from the
table. The server then consults this row to authenticate the
Before MySQL 5.5.7, the server authenticates the password provided
by the client against the
Password column of
the account row.
As of MySQL 5.5.7, the server authenticates clients using a
plugin. Selection of the proper account row from the
mysql.user table is based on the user name and
client host, as before, but the server authenticates the client by
determining from the account row which authentication plugin
applies for the client:
If the account row specifies a plugin, the server invokes it to authenticate the user. If the server cannot find the plugin, an error occurs and the connection attempt is rejected.
If the account row specifies no plugin name, the server authenticates the account using either the
mysql_old_passwordplugin, depending on whether the password hash value in the
Passwordcolumn used native hashing or the older pre-4.1 hashing method. Clients must match the password in the
Passwordcolumn of the account row.
The plugin returns a status to the server indicating whether the user is permitted to connect.
Pluggable authentication enables two important capabilities:
External authentication: Pluggable authentication makes it possible for clients to connect to the MySQL server with credentials that are appropriate for authentication methods other than authentication based on passwords stored in the
mysql.usertable. For example, plugins can be created to use external authentication methods such as PAM, Windows login IDs, LDAP, or Kerberos.
Proxy users: If a user is permitted to connect, an authentication plugin can return to the server a user name different from the name of the connecting user, to indicate that the connecting user is a proxy for another user. While the connection lasts, the proxy user is treated, for purposes of access control, as having the privileges of a different user. In effect, one user impersonates another. For more information, see Section 5.7, “Proxy Users”.
Several authentication plugins are available in MySQL:
Plugins that perform native authentication; that is, authentication based on the password hashing methods in use from before the introduction of pluggable authentication. The
mysql_native_passwordplugin implements authentication based on the native password hashing method. The
mysql_old_passwordplugin implements native authentication based on the older (pre-4.1) password hashing method. See Section 7.1.1, “Native Pluggable Authentication”, and Section 7.1.2, “Old Native Pluggable Authentication”. Native authentication using
mysql_native_passwordis the default for accounts that have no plugin named explicitly in their account row.
A client-side plugin that sends the password to the server without hashing or encryption. This plugin is used in conjunction with server-side plugins that require access to the password exactly as provided by the client user. See Section 7.1.3, “Client-Side Cleartext Pluggable Authentication”.
A plugin that performs external authentication using PAM (Pluggable Authentication Modules), enabling MySQL Server to use PAM to authenticate MySQL users. This plugin supports proxy users as well. See Section 7.1.4, “PAM Pluggable Authentication”.
A plugin that performs external authentication on Windows, enabling MySQL Server to use native Windows services to authenticate client connections. Users who have logged in to Windows can connect from MySQL client programs to the server based on the information in their environment without specifying an additional password. This plugin supports proxy users as well. See Section 7.1.5, “Windows Pluggable Authentication”.
A plugin that authenticates clients that connect from the local host through the Unix socket file. See Section 7.1.6, “Socket Peer-Credential Pluggable Authentication”.
A test plugin that checks account credentials and logs success or failure to the server error log. This plugin is intended for testing and development purposes, and as an example of how to write an authentication plugin. See Section 7.1.7, “Test Pluggable Authentication”.
For information about current restrictions on the use of pluggable authentication, including which connectors support which plugins, see Restrictions on Pluggable Authentication.
Third-party connector developers should read that section to determine the extent to which a connector can take advantage of pluggable authentication capabilities and what steps to take to become more compliant.
If you are interested in writing your own authentication plugins, see Writing Authentication Plugins.
This section provides general instructions for installing and using authentication plugins.
In general, pluggable authentication uses corresponding plugins on the server and client sides, so you use a given authentication method like this:
If necessary, install the plugin library or libraries containing the appropriate plugins. On the server host, install the library containing the server-side plugin, so that the server can use it to authenticate client connections. Similarly, on each client host, install the library containing the client-side plugin for use by client programs.
Create MySQL accounts that specify use of the server-side plugin for authentication.
When a client connects, the server-side plugin tells the client program which client-side plugin to use for authentication.
The instructions here use an example authentication plugin included in MySQL distributions (see Section 7.1.7, “Test Pluggable Authentication”). The procedure is similar for other authentication plugins; substitute the appropriate plugin and file names.
The example authentication plugin has these characteristics:
The server-side plugin name is
The client-side plugin name is
Both plugins are located in the shared library file named
auth_test_plugin.so, which must be located in the plugin directory (the directory named by the
plugin_dirsystem variable). The file name suffix might differ on your system.
Install and use the example authentication plugin as follows:
Make sure that the plugin library is installed on the server and client hosts.
Install the server-side test plugin at server startup or at runtime:
To load the plugin at server startup, use the
--plugin-loadoption. With this plugin-loading method, the option must be given each time the server starts. For example, use these lines in a
Alternatively, to register the plugin at runtime, use the
INSTALL PLUGIN test_plugin_server SONAME 'auth_test_plugin.so';
INSTALL PLUGINloads a plugin, and also registers it in the
mysql.pluginstable to cause the plugin to be loaded for each subsequent normal server startup.
SELECT PLUGIN_NAME, PLUGIN_STATUS
WHERE PLUGIN_NAME LIKE '%test_plugin%';+--------------------+---------------+ | PLUGIN_NAME | PLUGIN_STATUS | +--------------------+---------------+ | test_plugin_server | ACTIVE | +--------------------+---------------+
If the plugin fails to initialize, check the server error log for diagnostic messages.
To specify that a MySQL user must be authenticated using a specific server plugin, name the plugin in the
IDENTIFIED WITHclause of the
CREATE USERstatement that creates the user:
CREATE USER 'testuser'@'localhost' IDENTIFIED WITH test_plugin_server;
Connect to the server using a client program. The test plugin authenticates the same way as other authentication plugins, so provide the usual
--passwordoptions that you normally use to connect to the server. For example:
mysql --user=Enter password:
For connections by
testuser, the server sees that the account must be authenticated using the server-side plugin named
test_plugin_serverand communicates to the client program which client-side plugin it must use—in this case,
In the case that the account uses an authentication method that is the default for both the server and the client program, the server need not communicate to the client which client-side plugin to use, and a round trip in client/server negotiation can be avoided. This is true for accounts that use native MySQL authentication (
--default-auth=option can be specified on the mysql command line as a hint about which client-side plugin the program can expect to use, although the server will override this if the server-side plugin associated with the user account requires a different client-side plugin.
If the client program does not find the client-side plugin, specify a
--plugin-dir=option to indicate where the plugin is located.
If you start the server with the
authentication plugins are not used even if loaded because the
server performs no client authentication and permits any client
to connect. Because this is insecure, you might want to use
--skip-networking to prevent
remote clients from connecting.