### 6.2.17 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, 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.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.2.19, “Proxy Users”](proxy-users.html).

Note

 If you start the server with the [`--skip-grant-tables`](server-options.html#option_mysqld_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, if the server is started with the [`--skip-grant-tables`](server-options.html#option_mysqld_skip-grant-tables) option, it also disables remote connections by enabling [`skip_networking`](server-system-variables.html#sysvar_skip_networking).

* [Available Authentication Plugins](pluggable-authentication.html#pluggable-authentication-available-plugins)

* [The Default Authentication Plugin](pluggable-authentication.html#pluggable-authentication-default-plugin)

* [Authentication Plugin Usage](pluggable-authentication.html#pluggable-authentication-usage)

* [Authentication Plugin Client/Server Compatibility](pluggable-authentication.html#pluggable-authentication-compatibility)

* [Authentication Plugin Connector-Writing Considerations](pluggable-authentication.html#pluggable-authentication-connector-writing)

* [Restrictions on Pluggable Authentication](pluggable-authentication.html#pluggable-authentication-restrictions)

#### Available Authentication Plugins

 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_password` plugin implements authentication based on this native password hashing method. See [Section 6.4.1.1, “Native Pluggable Authentication”](native-pluggable-authentication.html).

* Plugins that perform authentication using SHA-256 password hashing. This is stronger encryption than that available with native authentication. See [Section 6.4.1.2, “Caching SHA-2 Pluggable Authentication”](caching-sha2-pluggable-authentication.html), and [Section 6.4.1.3, “SHA-256 Pluggable Authentication”](sha256-pluggable-authentication.html).

* 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 6.4.1.4, “Client-Side Cleartext Pluggable Authentication”](cleartext-pluggable-authentication.html).

* 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 6.4.1.5, “PAM Pluggable Authentication”](pam-pluggable-authentication.html).

* 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.4.1.6, “Windows Pluggable Authentication”](windows-pluggable-authentication.html).

* Plugins that perform authentication using LDAP (Lightweight Directory Access Protocol) to authenticate MySQL users by accessing directory services such as X.500. These plugins support proxy users as well. See [Section 6.4.1.7, “LDAP Pluggable Authentication”](ldap-pluggable-authentication.html).

* A plugin that performs authentication using Kerberos to authenticate MySQL users that correspond to Kerberos principals. See [Section 6.4.1.8, “Kerberos Pluggable Authentication”](kerberos-pluggable-authentication.html).

* 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 6.4.1.9, “No-Login Pluggable Authentication”](no-login-pluggable-authentication.html).

* A plugin that authenticates clients that connect from the local host through the Unix socket file. See [Section 6.4.1.10, “Socket Peer-Credential Pluggable Authentication”](socket-pluggable-authentication.html).

* A plugin that authenticates users to MySQL Server using FIDO authentication. See [Section 6.4.1.11, “FIDO Pluggable Authentication”](fido-pluggable-authentication.html).

* 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.4.1.12, “Test Pluggable Authentication”](test-pluggable-authentication.html).

Note

 For information about current restrictions on the use of pluggable authentication, including which connectors support which plugins, see [Restrictions on Pluggable Authentication](pluggable-authentication.html#pluggable-authentication-restrictions).

 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](https://dev.mysql.com/doc/extending-mysql/8.0/en/writing-authentication-plugins.html).

#### The Default Authentication Plugin

[]()[]()[]()[]()[]()[]()

 The [`CREATE USER`](create-user.html) and [`ALTER USER`](alter-user.html) statements have syntax for specifying how an account authenticates. Some forms of this syntax do not explicitly name an authentication plugin (there is no `IDENTIFIED WITH` clause). For example:

```
CREATE USER 'jeffrey'@'localhost' IDENTIFIED BY 'password';
```

 In such cases, the server assigns the default authentication plugin to the account. Prior to MySQL 8.0.27, this default is the value of the [`default_authentication_plugin`](server-system-variables.html#sysvar_default_authentication_plugin) system variable.

 As of MySQL 8.0.27, which introduces multifactor authentication, there can be up to three clauses that specify how an account authenticates. The rules that determine the default authentication plugin for authentication methods that name no plugin are factor-specific:

* Factor 1: If [`authentication_policy`](server-system-variables.html#sysvar_authentication_policy) element 1 names an authentication plugin, that plugin is the default. If [`authentication_policy`](server-system-variables.html#sysvar_authentication_policy) element 1 is `*`, the value of [`default_authentication_plugin`](server-system-variables.html#sysvar_default_authentication_plugin) is the default.

   Given the rules above, the following statement creates a two-factor authentication account, with the first factor authentication method determined by the [`authentication_policy`](server-system-variables.html#sysvar_authentication_policy) or [`default_authentication_plugin`](server-system-variables.html#sysvar_default_authentication_plugin) setting:

  ```
  CREATE USER 'wei'@'localhost' IDENTIFIED BY 'password'
    AND IDENTIFIED WITH authentication_ldap_simple;
  ```

   In the same way, this example creates a three-factor authentication account:

  ```
  CREATE USER 'mateo'@'localhost' IDENTIFIED BY 'password'
    AND IDENTIFIED WITH authentication_ldap_simple
    AND IDENTIFIED WITH authentication_fido;
  ```

   You can use [`SHOW CREATE USER`](show-create-user.html) to view the applied authentication methods.

* Factor 2 or 3: If the corresponding [`authentication_policy`](server-system-variables.html#sysvar_authentication_policy) element names an authentication plugin, that plugin is the default. If the [`authentication_policy`](server-system-variables.html#sysvar_authentication_policy) element is `*` or empty, there is no default; attempting to define an account authentication method for the factor without naming a plugin is an error, as in the following examples:

  ```
  mysql> CREATE USER 'sofia'@'localhost' IDENTIFIED WITH authentication_ldap_simple
         AND IDENTIFIED BY 'abc';
  ERROR 1524 (HY000): Plugin '' is not loaded

  mysql> CREATE USER 'sofia'@'localhost' IDENTIFIED WITH authentication_ldap_simple
         AND IDENTIFIED BY 'abc';
  ERROR 1524 (HY000): Plugin '*' is not loaded
  ```

#### 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.4.1, “Authentication Plugins”](authentication-plugins.html).

 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 server assigns the the default authentication plugin, determined as described in [The Default Authentication Plugin](pluggable-authentication.html#pluggable-authentication-default-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**](mysql.html) and [**mysqladmin**](mysqladmin.html), the [`--default-auth=*`plugin_name`*`](mysql-command-options.html#option_mysql_default-auth) 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 overrides 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`*`](mysql-command-options.html#option_mysql_plugin-dir) option to indicate the plugin library directory location.

#### Authentication Plugin Client/Server Compatibility

[]()

 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 from 5.7.22 or lower 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. (This issue is addressed in MySQL 5.7 as of 5.7.23, when `caching_sha2_password` client-side support was added to the MySQL client library and client programs.)

* 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.

#### Authentication Plugin Connector-Writing Considerations

[]()

 Various implementations of the MySQL client/server protocol exist. The `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 account.

 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 fails 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, `libmysqlclient` uses as its default choice either `mysql_native_password` or the plugin specified through the `MYSQL_DEFAULT_AUTH` option for [`mysql_options()`](https://dev.mysql.com/doc/c-api/8.0/en/mysql-options.html).

* When a 5.7 client tries to connect to an 8.0 server, the server specifies `caching_sha2_password` as its default authentication plugin, but the client still sends credential details per either `mysql_native_password` or whatever is specified through `MYSQL_DEFAULT_AUTH`.

* 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.

#### Restrictions on Pluggable Authentication

[]()[]()

 The first part of this section describes general restrictions on the applicability of the pluggable authentication framework described at [Section 6.2.17, “Pluggable Authentication”](pluggable-authentication.html). The second part describes how third-party connector developers can determine the extent to which a connector can take advantage of pluggable authentication capabilities and what steps to take to become more compliant.

 The term “native authentication” used here refers to authentication against passwords stored in the `mysql.user` system table. This is the same authentication method provided by older MySQL servers, before pluggable authentication was implemented. “Windows native authentication” refers to authentication using the credentials of a user who has already logged in to Windows, as implemented by the Windows Native Authentication plugin (“Windows plugin” for short).

* [General Pluggable Authentication Restrictions](pluggable-authentication.html#pluggable-authentication-restrictions-general)

* [Pluggable Authentication and Third-Party Connectors](pluggable-authentication.html#pluggable-authentication-restrictions-third-party-connectors)

##### General Pluggable Authentication Restrictions

* **Connector/C++:** Clients that use this connector can connect to the server only through accounts that use native authentication.

   Exception: A connector supports pluggable authentication if it was built to link to `libmysqlclient` dynamically (rather than statically) and it loads the current version of `libmysqlclient` if that version is installed, or if the connector is recompiled from source to link against the current `libmysqlclient`.

   For information about writing connectors to handle informatin from the server about the default server-side authentication plugin, see [Authentication Plugin Connector-Writing Considerations](pluggable-authentication.html#pluggable-authentication-connector-writing).

* **Connector/NET:** Clients that use Connector/NET can connect to the server through accounts that use native authentication or Windows native authentication.

* **Connector/PHP:** Clients that use this connector can connect to the server only through accounts that use native authentication, when compiled using the MySQL native driver for PHP (`mysqlnd`).

* **Windows native authentication:** Connecting through an account that uses the Windows plugin requires Windows Domain setup. Without it, NTLM authentication is used and then only local connections are possible; that is, the client and server must run on the same computer.

* **Proxy users:** Proxy user support is available to the extent that clients can connect through accounts authenticated with plugins that implement proxy user capability (that is, plugins that can return a user name different from that of the connecting user). For example, the PAM and Windows plugins support proxy users. The `mysql_native_password` and `sha256_password` authentication plugins do not support proxy users by default, but can be configured to do so; see [Server Support for Proxy User Mapping](proxy-users.html#proxy-users-server-user-mapping).

* **Replication**: Replicas can not only employ replication user accounts using native authentication, but can also connect through replication user accounts that use nonnative authentication if the required client-side plugin is available. If the plugin is built into `libmysqlclient`, it is available by default. Otherwise, the plugin must be installed on the replica side in the directory named by the replica's [`plugin_dir`](server-system-variables.html#sysvar_plugin_dir) system variable.

* **[`FEDERATED`](federated-storage-engine.html) tables:** A [`FEDERATED`](federated-storage-engine.html) table can access the remote table only through accounts on the remote server that use native authentication.

##### Pluggable Authentication and Third-Party Connectors

 Third-party connector developers can use the following guidelines to determine readiness of a connector to take advantage of pluggable authentication capabilities and what steps to take to become more compliant:

* An existing connector to which no changes have been made uses native authentication and clients that use the connector can connect to the server only through accounts that use native authentication. *However, you should test the connector against a recent version of the server to verify that such connections still work without problem.*

   Exception: A connector might work with pluggable authentication without any changes if it links to `libmysqlclient` dynamically (rather than statically) and it loads the current version of `libmysqlclient` if that version is installed.

* To take advantage of pluggable authentication capabilities, a connector that is `libmysqlclient`-based should be relinked against the current version of `libmysqlclient`. This enables the connector to support connections though accounts that require client-side plugins now built into `libmysqlclient` (such as the cleartext plugin needed for PAM authentication and the Windows plugin needed for Windows native authentication). Linking with a current `libmysqlclient` also enables the connector to access client-side plugins installed in the default MySQL plugin directory (typically the directory named by the default value of the local server's [`plugin_dir`](server-system-variables.html#sysvar_plugin_dir) system variable).

   If a connector links to `libmysqlclient` dynamically, it must be ensured that the newer version of `libmysqlclient` is installed on the client host and that the connector loads it at runtime.

* Another way for a connector to support a given authentication method is to implement it directly in the client/server protocol. Connector/NET uses this approach to provide support for Windows native authentication.

* If a connector should be able to load client-side plugins from a directory different from the default plugin directory, it must implement some means for client users to specify the directory. Possibilities for this include a command-line option or environment variable from which the connector can obtain the directory name. Standard MySQL client programs such as [**mysql**](mysql.html) and [**mysqladmin**](mysqladmin.html) implement a `--plugin-dir` option. See also [C API Client Plugin Interface](https://dev.mysql.com/doc/c-api/8.0/en/c-api-plugin-interface.html).

* Proxy user support by a connector depends, as described earlier in this section, on whether the authentication methods that it supports permit proxy users.

