Writing Authentication Plugins
MySQL supports pluggable authentication, in which plugins are invoked to authenticate client connections. Authentication plugins enable the use of authentication methods other than the built-in method of passwords stored in the mysql.user
table. For example, plugins can be written to access external authentication methods. Also, authentication plugins can support the proxy user capability, such that the connecting user is a proxy for another user and is treated, for purposes of access control, as having the privileges of a different user. For more information, see , "Pluggable Authentication", and , "Proxy Users".
An authentication plugin can be written for the server side or the client side. Server-side plugins use the same plugin API that is used for the other server plugin types such as full-text parser or audit plugins (although with a different type-specific descriptor). Client-side plugins use the client plugin API.
Several header files contain information relevant to authentication plugins:
plugin.h
: Defines theMYSQL_AUTHENTICATION_PLUGIN
server plugin type.client_plugin.h
: Defines the API for client plugins. This includes the client plugin descriptor and function prototypes for client plugin C API calls (see , "C API Client Plugin Functions").plugin_auth.h
: Defines the part of the server plugin API specific to authentication plugins. This includes the type-specific descriptor for server-side authentication plugins and theMYSQL_SERVER_AUTH_INFO
structure.plugin_auth_common.h
: Contains common elements of client and server authentication plugins. This includes return value definitions and theMYSQL_PLUGIN_VIO
structure.
To write an authentication plugin, include the following header files in the plugin source file. Other MariaDB or general header files might also be needed.
- For a source file that implements a server authentication plugin, include this file:
#include <mysql/plugin_auth.h>
- For a source file that implements a client authentication plugin, or both client and server plugins, include these files:
#include <mysql/plugin_auth.h> #include <mysql/client_plugin.h> #include <mysql>
plugin_auth.h
includes plugin.h
and plugin_auth_common.h
, so you need not include the latter files explicitly.
This section describes how to write a pair of simple server and client authentication plugins that work together.Warning
These plugins accept any non-empty password and the password is sent in clear text. This is insecure, so the plugins should not be used in production environments.
The server-side and client-side plugins developed here both are named auth_simple
. As described in , "Plugin Data Structures", the plugin library file must have the same basename as the client plugin, so the source file name is auth_simple.c
and produces a library named auth_simple.so
(assuming that your system uses .so
as the extension for library files).
In MariaDB source distributions, authentication plugin source is located in the plugin/auth
directory and can be examined as a guide to writing other authentication plugins. Also, to see how the built-in authentication plugins are implemented, see sql/sql_acl.cc
for plugins that are built in to the MariaDB server and sql-common/client.c
for plugins that are built in to the libmysql
client library. (For the built-in client plugins, note that the auth_plugin_t
structures used there differ from the structures used with the usual client plugin declaration macros. In particular, the first two members are provided explicitly, not by declaration macros.)