6.3.7 Pluggable Authentication

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 mysql.user
system table. The server then authenticates the client,
determining from the account row which authentication plugin
applies to the client:

If the server cannot find the plugin, an error occurs and the
connection attempt is rejected. Otherwise, if the account row
specifies a plugin, the server invokes it to authenticate the
user.

If the account row specifies no plugin name, the server
authenticates the account using either the
mysql_native_password or
mysql_old_password plugin, depending on
whether the password hash value in the
Password column used native hashing or the
older pre-4.1 hashing method. Clients must match the password
in the Password column of the account row.

The plugin returns a status to the server indicating whether the
user provided the correct password and is permitted to connect.

Pluggable authentication enables these important capabilities:

Choice of authentication methods.
Pluggable authentication makes it easy for DBAs to choose
and change the authentication method used for individual
MySQL accounts.

External authentication.
Pluggable authentication makes it possible for clients to
connect to the MySQL server with credentials appropriate for
authentication methods that store credentials elsewhere than
in the mysql.user system table. 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 (the proxied user). While the
connection lasts, the proxy user is treated, for purposes of
access control, as having the privileges of the proxied
user. In effect, one user impersonates another. For more
information, see Section 6.3.8, “Proxy Users”.

Note

If you start the server with the
--skip-grant-tables option,
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-grant-tables in
conjunction with
--skip-networking to prevent
remote clients from connecting.

Available Authentication Plugins

MySQL 5.6 provides these authentication plugins:

Plugins that perform native authentication; that is,
authentication based on the password hashing methods in use
from before the introduction of pluggable authentication in
MySQL. The mysql_native_password plugin
implements authentication based on the native password
hashing method. The mysql_old_password
plugin implements native authentication based on the older
(pre-4.1) password hashing method (and is now deprecated).
See Section 6.5.1.1, “Native Pluggable Authentication”, and
Section 6.5.1.2, “Old Native Pluggable Authentication”.
Native authentication using
mysql_native_password is the default for
new accounts, unless the
--default-authentication-plugin
option is set otherwise at server startup.

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 6.5.1.7, “Windows 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 6.5.1.9, “Test 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.

Authentication Plugin Usage

This section provides general instructions for installing and
using authentication plugins. For instructions specific to a
given plugin, see the section that describes that plugin under
Section 6.5.1, “Authentication Plugins”.

In general, pluggable authentication uses a pair of
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. Authentication plugins that are built in need not
be installed.

For each MySQL account that you create, specify the
appropriate server-side plugin to use for authentication. If
the account is to use the default authentication plugin, the
account-creation statement need not specify the plugin
explicitly. The
--default-authentication-plugin
option configures the default authentication plugin.

When a client connects, the server-side plugin tells the
client program which client-side plugin to use for
authentication.

In the case that an 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.

For standard MySQL clients such as mysql and
mysqladmin, the
--default-auth=plugin_name
option can be specified on the 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
library file, specify a
--plugin-dir=dir_name
option to indicate the plugin library directory location.