PAM Authentication Plugin

MariaDB starting with 5.2.10

Starting in version 5.2.10 (only in the source tarball in 5.2.10, included with all packages in later releases), MariaDB includes a PAM authentication plugin.

PAM is short for Pluggable Authentication Modules and is an authentication framework used by Linux, FreeBSD, Solaris, and other operating systems.

Note: Windows does not use PAM, so the PAM authentication plugin does not work on Windows. However, one can use the Windows client to connect to a MariaDB server on Linux or Solaris, for example which does use the PAM authentication plugin. See this example.

Usage Examples

PAM makes it possible to implement various authentication scenarios of different complexity. For example,

  • authentication using passwords from /etc/shadow (indeed, this is what PAM usually does for a normal shell logins, for pop3, imap, and many other services)
  • authentication using LDAP
  • authentication using ssh passphrases
  • authentication using one-time passwords (even with SMS confirmation!)
  • combining different authentication modules, where either one or all of them are required to succeed
  • password expiration
  • user name mapping
  • limiting access by time, date, day of the week, etc.
  • logging every login attempt
  • and so on, the list is in no way exhaustive.

Installation

This plugin is not loaded by default, you need to install it with

INSTALL SONAME 'auth_pam';

or by adding --plugin-load=auth_pam.so to the server's command line or to the [mysqld] section in your my.cnf file.

Similar to all other authentication plugins, to create a user in MariaDB which uses PAM authentication, you use

CREATE USER username@hostname IDENTIFIED VIA pam

or, for example,

GRANT SELECT ON db.* TO serg IDENTIFIED VIA pam

Optionally, you can specify a PAM service name, for example:

CREATE USER test_pam IDENTIFIED VIA pam USING 'mariadb';

This line creates a user that needs to be authenticated via PAM, using the service name mariadb.

If no service name is specified, the plugin will use mysql as the default PAM service name.

PAM Configuration

The PAM plugin tells MariaDB to delegate the authentication to the PAM subsystem. How exactly the authentication is performed depends on how PAM was configured. Typically, PAM configuration can be found in /etc/pam.d/ or in /etc/pam.conf. The syntax of these configuration files is described in your OS manual, for example, in man pam.d. A minimal example that uses UNIX passwords, is

auth            required        pam_unix.so
account         required        pam_unix.so

This needs to be put in the file with the name matching the name of the PAM service; for example in /etc/pam.d/mariadb if you specified USING mariadb in your CREATE USER statement. This simple configuration file instructs the PAM subsystem that for successful authentication it is required that pam_unix.so module returns a success. And for an account to be valid, it is required that pam_unix.so module returns a success. You can find many other examples in your /etc/pam.d/ directory.

Note: if you configure PAM to use pam_unix.so (as in the above example) and notice that MariaDB needs to run as a root user to be able to access /etc/shadow — try to upgrade your PAM installation. Newer versions of PAM do not require pam_unix.so to be run as root.

Dialog plugin

Usually PAM authentication uses a dialog client plugin to communicate with the user. This allows MariaDB to support arbitrarily complex PAM configurations with regular or one-time passwords, challenge-response, multiple questions, or just about anything else. There is no need to install or enable anything — the dialog plugin is loaded by the client library completely automatically and transparently for the application.

MySQL "cleartext" plugin

Starting from MariaDB 5.5.32, one can instruct the PAM plugin to use the mysql_cleartext_password client plugin instead of the dialog plugin. It may be useful if you only have MySQL (not MariaDB) client libraries and cannot install the dialog plugin. Keep in mind, though, that mysql_cleartext_password has a very limited PAM support, and only allows the use of password based authentication.

To switch the PAM plugin into this mode, specify the --pam-use-cleartext-plugin option on the command-line or in your my.cnf file.

User name mapping

Although PAM modules usually do not do that, PAM may change the user name in the process of authentication. For example, according to the PAM specification, one may start authenticating as John and end up being authenticated as Jim.

The MariaDB PAM authentication plugin fully supports it — the original user name is returned by the SQL function USER(), while the authenticated user name (if changed) is returned by the SQL function CURRENT_USER(), and it is the latter which defines what privileges are available to a connected user.

The PAM module pam_user_map was implemented to facilitate user name mapping. It's represented by a single plugin/auth_pam/mapper/pam_user_map.c file in the MariaDB tree.

Compile as

    gcc pam_user_map.c -shared -lpam -fPIC -o pam_user_map.so

Install the resulting pam_user_map.so as appropriate (for example, in /lib/security/). Add the following line to your /etc/pam.d/mysql (preferably, at the end):

=========================================================
auth            required        pam_user_map.so
=========================================================

And then create /etc/security/user_map.conf with the desired mapping in the format:

orig_user_name: mapped_user_name
@user's_group_name: mapped_user_name##
=========================================================
#comments and empty lines are ignored
john: jack
bob:  admin
top:  accounting
@group_ro: readonly

See Also

Comments

Comments loading...
Loading