Description\n-----------\n\nThe pam authentication plugin allows MariaDB to offload user authentication to the system's Pluggable Authentication Module (PAM) framework. PAM is an authentication framework used by Linux, FreeBSD, Solaris, and other Unix-like operating systems.\n\nNote: Windows does not support PAM, so the pam authentication plugin does not support Windows. However, one can use a MariaDB client on Windows to connect to MariaDB server that is installed on a Unix-like operating system and that is configured to use the pam authentication plugin. For an example of how to do this, see the blog post: MariaDB: Improve Security with Two-Step Verification.\n\nUse Cases\n\nPAM makes it possible to implement various authentication scenarios of different complexity:\n\n Authentication using passwords from /etc/shadow (this is what a default PAM configuration usually does). See the pam_unix PAM module.\n Authentication using LDAP. See the pam_ldap PAM module.\n Authentication using Microsoft's Active Directory. See the pam_lsass, pam_winbind, and pam_centrifydc PAM modules.\n Authentication using one-time passwords (even with SMS confirmation!). See the pam_google_authenticator and pam_securid PAM modules.\n Authentication using SSH keys. See the pam_ssh PAM module.\n User and group mapping. See the pam_user_map PAM module.\n Combining different authentication modules in interesting ways in a PAM service.\n Password expiration.\n Limiting access by time, date, day of the week, etc. See the pam_time PAM module.\n Logging of every login attempt.\n\nInstalling the Plugin\n\nThe pam authentication plugin's library is provided in binary packages in all releases on Linux.\n\nAlthough the plugin's shared library is distributed with MariaDB by default, the plugin is not actually installed by MariaDB by default. There are two methods that can be used to install the plugin with MariaDB.\n\nThe first method can be used to install the plugin without restarting the server. You can install the plugin dynamically by executing INSTALL SONAME or INSTALL PLUGIN:\n\n``sql\nINSTALL SONAME 'auth_pam';\n`\n\nThe second method can be used to tell the server to load the plugin when it starts up. The plugin can be installed this way by providing the --plugin-load or the --plugin-load-add options. This can be specified as a command-line argument to mysqld or it can be specified in a relevant server option group in an option file:\n\n`ini\n[mariadb]\n...\nplugin_load_add = auth_pam\n`\n\nInstalling the v1 Plugin\n\nThe auth_pam shared library actually refers to version 2.0 of the pam authentication plugin. Version 1.0 of the plugin as the auth_pam_v1 shared library is also available.\n\nIf you need to install version 1.0 of the authentication plugin instead of version 2.0, install it with INSTALL SONAME or INSTALL PLUGIN:\n\n`sql\nINSTALL SONAME 'auth_pam_v1';\n`\n\nAlternatively, specify it in a relevant server option group in an option file:\n\n`sql\n[mariadb]\n...\nplugin_load_add = auth_pam_v1\n`\n\nUninstalling the Plugin\n\nYou can uninstall the plugin dynamically by executing UNINSTALL SONAME or UNINSTALL PLUGIN:\n\n`sql\nUNINSTALL SONAME 'auth_pam';\n`\n\nIf you installed the plugin by providing the --plugin-load or the --plugin-load-add options in a relevant server option group in an option file, those options must be removed to prevent the plugin from being loaded the next time the server is restarted.\n\nUninstalling the v1 Plugin\n\nIf you installed version 1.0 of the authentication plugin, you can uninstall it by executing a similar statement for auth_pam_v1:\n\n`sql\nUNINSTALL SONAME 'auth_pam_v1';\n`\n\nConfiguring PAM\n\nThe pam authentication plugin tells MariaDB to delegate the authentication to the PAM authentication framework. How exactly that authentication is performed depends on how PAM is configured.\n\nConfiguring the PAM Service\n\nPAM is divided into services. PAM services are configured by PAM configuration files. Typically, the global PAM configuration file is located at /etc/pam.conf and PAM directory-based configuration files for individual services are located in /etc/pam.d/.\n\nIf you want to use a PAM service called mariadb for your MariaDB PAM authentication, then the PAM configuration file for that service would also be called mariadb, and it would typically be located at /etc/pam.d/mariadb.\n\nFor example, here is a minimal PAM service configuration file that performs simple password authentication with UNIX passwords:\n\n`\nauth required pam_unix.so audit\naccount required pam_unix.so audit\n`\n\nLet's breakdown this relatively simple PAM service configuration file.\n\nEach line of a PAM service configuration file has the following general format:\n\n`\ntype control module-path module-arguments\n`\n\nIt instructs the PAM authentication framework that for successful authentication (i.e. type=auth), it is required that the pam_unix.so PAM module returns a success. It also instructs the PAM authentication framework that for an account (i.e. type=account) to be valid, it is required that the pam_unix.so PAM module returns a success.\n\nPAM also supports session and password types, but MariaDB's pam authentication plugin does not support those.\n\nThe above PAM service configuration file also provides the audit module argument to the pam_unix PAM module. The pam_unix manual says that this module argument enables extreme debug logging to the syslog.\n\nOn most systems, you can find many other examples of PAM service configuration files in your /etc/pam.d/ directory.\n\nConfiguring the pam_unix PAM Module\n\nIf you configure PAM to use the pam_unix PAM module (as in the above example), then you might notice on some systems that this will fail by default with errors like the following:\n\n`\nApr 14 12:56:23 localhost unix_chkpwd[3332]: check pass; user unknown\nApr 14 12:56:23 localhost unix_chkpwd[3332]: password check failed for user (alice)\nApr 14 12:56:23 localhost mysqld: pam_unix(mysql:auth): authentication failure; logname= uid=991 euid=991 tty= ruser= rhost=  user=alice\n`\n\nThe problem is that on some systems, the pam_unix PAM module needs access to /etc/shadow in order to function, and most systems only allow root to access that file by default.\n\nNewer versions of PAM do not have this limitation, so you may want to try upgrading your version of PAM to see if that fixes the issue.\n\nIf that does not work, then you can work around this problem by giving the user that runs mysqld access to /etc/shadow. For example, if the mysql user runs mysqld, then you could do the following:\n\n`bash\nsudo groupadd shadow\nsudo usermod -a -G shadow mysql\nsudo chown root:shadow /etc/shadow\nsudo chmod g+r /etc/shadow\n`\n\nAfter configuring, you have to restart the server. The server should now be able to read /etc/shadow.\n\nThe pam authentication plugin uses a setuid wrapper to perform its PAM checks, so it should not need any special workarounds to perform privileged operations, such as reading /etc/shadow when using the pam_unix PAM module. See MDEV-7032 for more information.\n\nCreating Users\n\nTo create a user in MariaDB which uses the pam authentication plugin, execute CREATE USER while specifying the name of the plugin in the IDENTIFIED VIA clause:\n\n`sql\nCREATE USER username@hostname IDENTIFIED VIA pam;\n`\n\nIf SQL_MODE does not have NO_AUTO_CREATE_USER set, then you can also create the user this way with GRANT:\n\n`sql\nGRANT SELECT ON db. TO username@hostname IDENTIFIED VIA pam;\n`\n\nYou can also specify a PAM service name for MariaDB to use by providing it with the USING clause:\n\n`sql\nCREATE USER username@hostname IDENTIFIED VIA pam USING 'mariadb';\n`\n\nThis line creates a user that needs to be authenticated via the pam authentication plugin using the PAM service name mariadb. As mentioned in a previous section, this service's configuration file will typically be present in /etc/pam.d/mariadb.\n\nIf no service name is specified, then the plugin will use mysql as the default PAM service name.\n\nClient Authentication Plugins\n\nFor clients that use the libmysqlclient or MariaDB Connector/C libraries, MariaDB provides two client authentication plugins that are compatible with the pam authentication plugin:\n\n dialog\n mysql_clear_password\n\nWhen connecting with a client or utility to a server as a user account that authenticates with the pam authentication plugin, you may need to tell the client where to find the relevant client authentication plugin by specifying the --plugin-dir option:\n\n`bash\nmariadb --plugin-dir=/usr/local/mysql/lib64/mysql/plugin --user=alice\n`\n\nBoth the dialog and the mysql_clear_password client authentication plugins transmit the password to the server in clear text. Therefore, when you use the pam authentication plugin, it is very important to encrypt client connections using TLS to prevent the clear-text passwords from being seen by unauthorized users.\n\ndialog\n\nUsually the pam authentication plugin uses the dialog client authentication plugin to communicate with the user. This client authentication plugin allows MariaDB to support arbitrarily complex PAM configurations with regular or one-time passwords, challenge-response, multiple questions, or just about anything else. When using a MariaDB client library, there is no need to install or enable anything — the dialog client authentication plugin is loaded by the client library completely automatically and transparently for the application.\n\nThe dialog client authentication plugin was developed by MariaDB, so MySQL's clients and client libraries as well as third party applications that bundle MySQL's client libraries do not support the dialog client authentication plugin out of the box. If the server tells an unsupported client to use the dialog client authentication plugin, then the client is likely to throw an error like the following:\n\n`\nERROR 2059 (HY000): Authentication plugin 'dialog' cannot be loaded: /usr/lib/mysql/plugin/dialog.so: cannot open shared object file: No such file or directory\n`\n\nFor some libraries or applications, this problem can be fixed by copying dialog.so or dialog.dll from a MariaDB client installation that is compatible with the system into the system's MySQL client authentication plugin directory. However, not all clients are compatible with the dialog client authentication plugin, so this may not work for every client.\n\nIf your client does not support the dialog client authentication plugin, then you may need to use the mysql_clear_password client authentication plugin instead.\n\nThe dialog client authentication plugin transmits the password to the server in clear text. Therefore, when you use the pam authentication plugin, it is incredibly important to encrypt client connections using TLS to prevent the clear-text passwords from being seen by unauthorized users.\n\nmysql_clear_password\n\nUsers can instruct the pam authentication plugin to use the mysql_clear_password client authentication plugin instead of the dialog client authentication plugin by configuring the pam_use_cleartext_plugin system variable on the server. It can be set in a relevant server option group in an option file:\n\n`ini\n[mariadb]\n...\npam_use_cleartext_plugin\n`\n\nIt is important to note that the mysql_clear_password plugin has very limited functionality.\n\n The mysql_clear_password client authentication plugin only supports PAM services that require password-based authentication.\n The mysql_clear_password client authentication plugin also only supports PAM services that ask the user a single question.\n If the PAM service requires challenge-responses, multiple questions, or other similar complicated authentication schemes, then the PAM service is not compatible with mysql_clear_password client authentication plugin. In that case, the dialog client authentication plugin will have to be used instead.\n\nThe mysql_clear_password client authentication plugin transmits the password to the server in clear text. Therefore, when you use the pam authentication plugin, it is incredibly important to encrypt client connections using TLS to prevent the clear-text passwords from being seen by unauthorized users.\n\nCompatiblity with MySQL Clients and Client Libraries\n\nThe mysql_clear_password client authentication plugin is similar to MySQL's mysql_clear_password client authentication plugin.\n\nThe mysql_clear_password client authentication plugin is compatible with MySQL clients and most MySQL client libraries, while the dialog client authentication plugin is not always compatible with them. Therefore, the mysql_clear_password client authentication plugin is most useful if you need some kind of MySQL compatibility in your environment, but you still want to use the pam authentication plugin.\n\nEven though the mysql_clear_password client authentication plugin is compatible with MySQL clients and most MySQL client libraries, the mysql_clear_password client authentication plugin may be disabled by default by these clients and client libraries. For example, MySQL's version of the mysql command-line client has the --enable-cleartext-plugin option that must be set in order to use the mysql_clear_password client authentication plugin:\n\n`bash\nmysql --enable-cleartext-plugin --user=alice -p\n`\n\nOther clients may require other methods to enable the authentication plugin. For example, MySQL Workbench has a checkbox titled Enable Cleartext Authentication Plugin under the Advanced tab on the connection configuration screen.\n\nFor applications that use MySQL's libmysqlclient, the authentication plugin can be enabled by setting the MYSQL_ENABLE_CLEARTEXT_PLUGIN option with the mysql_options() function:\n\n`ini\nmysql_options(mysql, MYSQL_ENABLE_CLEARTEXT_PLUGIN, 1);\n`\n\nFor MySQL compatibility, MariaDB Connector/C also allows applications to set the MYSQL_ENABLE_CLEARTEXT_PLUGIN option with the mysql_optionsv function. However, this option does not actually do anything in MariaDB Connector/C, because the mysql_clear_password client authentication plugin is always enabled for MariaDB clients and client libraries.\n\nSupport in Client Libraries\n\nUsing the Plugin with MariaDB Connector/C\n\nMariaDB Connector/C supports pam authentication using the client authentication plugins, regardless of the value of the pam_use_cleartext_plugin system variable.\n\nUsing the Plugin with MariaDB Connector/ODBC\n\nMariaDB Connector/ODBC supports pam authentication using the client authentication plugins, regardless of the value of the pam_use_cleartext_plugin system variable.\n\nUsing the Plugin with MariaDB Connector/J\n\nMariaDB Connector/J supports pam v1 authentication, regardless of the value of the pam_use_cleartext_plugin system variable.\n\nMariaDB Connector/J supports pam v2 authentication, regardless of the value of the pam_use_cleartext_plugin system variable.\n\nUsing the Plugin with MariaDB Connector/Node.js\n\nMariaDB Connector/Node.js supports pam authentication, regardless of the value of the pam_use_cleartext_plugin system variable.\n\nUsing the Plugin with MySqlConnector for .NET\n\nMySqlConnector for ADO.NET supports pam authentication, but on\n\n[Truncated — full content at mariadb.com/docs]