Pre-General Availability Draft: 2018-03-23
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
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, the server invokes that plugin to authenticate the user, and 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.usersystem 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.11, “Proxy Users”.
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, if the server is started
option, it enables
to prevent remote connections.
MySQL 8.0 provides these authentication plugins:
A plugin that performs native authentication; that is, authentication based on the password hashing method in use from before the introduction of pluggable authentication in MySQL. The
mysql_native_passwordplugin implements authentication based on this native password hashing method. See Section 188.8.131.52, “Native Pluggable Authentication”.
Plugins that perform authentication using SHA-256 password hashing. This is stronger encryption than that available with native authentication. See Section 184.108.40.206, “SHA-256 Pluggable Authentication”, and Section 220.127.116.11, “Caching SHA-2 Pluggable Authentication”.
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 18.104.22.168, “Client-Side Cleartext Pluggable Authentication”.
A plugin that prevents all client connections to any account that uses it. Use cases for this plugin include proxied accounts that should never permit direct login but are accessed only through proxy accounts and accounts that must be able to execute stored programs and views with elevated privileges without exposing those privileges to ordinary users. See Section 22.214.171.124, “No-Login Pluggable Authentication”.
A plugin that authenticates clients that connect from the local host through the Unix socket file. See Section 126.96.36.199, “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 188.8.131.52, “Test Pluggable Authentication”.
For information about current restrictions on the use of pluggable authentication, including which connectors support which plugins, see Section C.9, “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 Section 184.108.40.206, “Writing Authentication Plugins”.
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_pluginsystem variable 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.
For standard MySQL clients such as mysql and
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
If the client program does not find the client-side plugin
library file, specify a
option to indicate the plugin library directory location.
Pluggable authentication enables flexibility in the choice of authentication methods for MySQL accounts, but in some cases client connections cannot be established due to authentication plugin incompatibility between the client and server.
The general compatibility principle for a successful client connection to a given account on a given server is that the client and server both must support the authentication method required by the account. Because authentication methods are implemented by authentication plugins, the client and server both must support the authentication plugin required by the account.
Authentication plugin incompatibilities can arise in various ways. Examples:
Connect using a MySQL 5.7 client to a MySQL 8.0 server account that authenticates with
caching_sha2_password. This fails because the 5.7 client does not recognize the plugin, which was introduced in MySQL 8.0.
Connect using a MySQL 5.5 client to a MySQL 5.6 server account that authenticates with
sha256_password. This fails because the 5.5 client does not recognize the plugin, which was introduced in MySQL 5.6.
Connect using a MySQL 5.7 client to a pre-5.7 server account that authenticates with
mysql_old_password. This fails for multiple reasons. First, such a connection requires
--secure-auth=0, which is no longer a supported option. Even were it supported, the 5.7 client does not recognize the plugin because it was removed in MySQL 5.7.
Connect using a MySQL 5.7 client from a Community distribution to a MySQL 5.7 Enterprise server account that authenticates using one of the Enterprise-only LDAP authentication plugins. This fails because the Community client does not have access to the Enterprise plugin.
In general, these compatibility issues do not arise when connections are made between a client and server from the same MySQL distribution. When connections are made between a client and server from different MySQL series, issues can arise. These issues are inherent in the development process when MySQL introduces new authentication plugins or removes old ones. To minimize the potential for incompatibilities, regularly upgrade the server, clients, and connectors on a timely basis.
Various implementations of the MySQL client/server protocol
libmysqlclient C API client
library is one implementation. Some MySQL connectors (typically
those not written in C) provide their own implementation.
However, not all protocol implementations handle plugin
authentication the same way. This section describes an
authentication issue that protocol implementors should take into
In the client/server protocol, the server tells connecting clients which authentication plugin it considers the default. If the protocol implementation used by the client tries to load the default plugin and that plugin does not exist on the client side, the load operation fails. This is an unnecessary failure if the default plugin is not the plugin actually required by the account to which the client is trying to connect.
If a client/server protocol implementation does not have its own notion of default authentication plugin and always tries to load the default plugin specified by the server, it will fail with an error if that plugin is not available.
To avoid this problem, the protocol implementation used by the client should have its own default plugin and should use it as its first choice (or, alternatively, fall back to this default in case of failure to load the default plugin specified by the server). Example:
In MySQL 5.7,
libmysqlclientuses as its default choice either
mysql_native_passwordor the plugin specified through the
When a 5.7 client tries to connect to an 8.0 server, the server specifies
caching_sha2_passwordas its default authentication plugin, but the client still sends credential details per either
mysql_native_passwordor whatever is specified through
The only time the client loads the plugin specified by the server is for a change-plugin request, but in that case it can be any plugin depending on the user account. In this case, the client must try to load the plugin, and if that plugin is not available, an error is not optional.