6.3.6 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 table. The server then consults this row to authenticate the client.

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:

The plugin returns a status to the server indicating whether the user is permitted to connect.

Pluggable authentication enables two important capabilities:

Several authentication plugins are available in MySQL:

Note

For information about current restrictions on the use of pluggable authentication, including which connectors support which plugins, see Section D.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 24.2.4.9, “Writing Authentication Plugins”.

Authentication Plugin Usage Instructions

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:

The instructions here use an example authentication plugin included in MySQL distributions (see Section 6.3.7.7, “The Test Authentication Plugin”). The procedure is similar for other authentication plugins; substitute the appropriate plugin and file names.

The example authentication plugin has these characteristics:

Install and use the example authentication plugin as follows:

  1. Make sure that the plugin library is installed on the server and client hosts.

  2. Install the server-side test plugin at server startup or at runtime:

    • To install the plugin at startup, use the --plugin-load option. With this plugin-loading method, the option must be given each time you start the server. For example, use these lines in a my.cnf option file:

      [mysqld]
      plugin-load=test_plugin_server=auth_test_plugin.so
      
    • To install the plugin at runtime, use the INSTALL PLUGIN statement:

      mysql> INSTALL PLUGIN test_plugin_server SONAME 'auth_test_plugin.so';
      

      This installs the plugin permanently and need be done only once.

  3. Verify that the plugin is installed. For example, use SHOW PLUGINS:

    mysql> SHOW PLUGINS\G
    ...
    *************************** 21. row ***************************
       Name: test_plugin_server
     Status: ACTIVE
       Type: AUTHENTICATION
    Library: auth_test_plugin.so
    License: GPL
    

    For other ways to check the plugin, see Section 5.1.8.2, “Obtaining Server Plugin Information”.

  4. To specify that a MySQL user must be authenticated using a specific server plugin, name the plugin in the IDENTIFIED WITH clause of the CREATE USER statement that creates the user:

    CREATE USER 'testuser'@'localhost' IDENTIFIED WITH test_plugin_server;
    
  5. Connect to the server using a client program. The test plugin authenticates the same way as native MySQL authentication, so provide the usual --user and --password options that you normally use to connect to the server. For example:

    shell> mysql --user=your_name --password=your_pass
    

    For connections by testuser, the server sees that the account must be authenticated using the server-side plugin named test_plugin_server and communicates to the client program which client-side plugin it must use—in this case, auth_test_plugin.

    In the case that the account uses the authentication method that is the default for both the server and the client program, the server need not communicate to the client which plugin to use, and a round trip in client/server negotiation can be avoided. Currently this is true for accounts that use native MySQL authentication (mysql_native_password).

    The --default-auth=plugin_name option can be specified on the mysql command line to make explicit which client-side plugin the program can expect to use, although the server will override this if the user account requires a different plugin.

    If the client program does not find the plugin, specify a --plugin-dir=dir_name option to indicate where the plugin is located.

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.