MySQL :: MySQL 8.4 Reference Manual :: 8.4.1.7 LDAP Pluggable Authentication (original) (raw)

8.4.1.7 LDAP Pluggable Authentication

Note

LDAP pluggable authentication is an extension included in MySQL Enterprise Edition, a commercial product. To learn more about commercial products, see https://www.mysql.com/products/.

MySQL Enterprise Edition supports an authentication method that enables MySQL Server to use LDAP (Lightweight Directory Access Protocol) to authenticate MySQL users by accessing directory services such as X.500. MySQL uses LDAP to fetch user, credential, and group information.

LDAP pluggable authentication provides these capabilities:

Server and client plugins are available for simple and SASL-based LDAP authentication. On Microsoft Windows, the server plugin for SASL-based LDAP authentication is not supported, but the client plugin is.

The following tables show the plugin and library file names for simple and SASL-based LDAP authentication. The file name suffix might differ on your system. The files must be located in the directory named by theplugin_dir system variable.

Table 8.20 Plugin and Library Names for Simple LDAP Authentication

Plugin or File Plugin or File Name
Server-side plugin name authentication_ldap_simple
Client-side plugin name mysql_clear_password
Library file name authentication_ldap_simple.so

Table 8.21 Plugin and Library Names for SASL-Based LDAP Authentication

Plugin or File Plugin or File Name
Server-side plugin name authentication_ldap_sasl
Client-side plugin name authentication_ldap_sasl_client
Library file names authentication_ldap_sasl.so,authentication_ldap_sasl_client.so

The library files include only theauthentication_ldap_ _`XXX`_ authentication plugins. The client-sidemysql_clear_password plugin is built into thelibmysqlclient client library.

Each server-side LDAP plugin works with a specific client-side plugin:

The server-side LDAP authentication plugins are included only in MySQL Enterprise Edition. They are not included in MySQL community distributions. The client-side SASL LDAP plugin is included in all distributions, including community distributions, and, as mentioned previously, the client-sidemysql_clear_password plugin is built into thelibmysqlclient client library, which also is included in all distributions. This enables clients from any distribution to connect to a server that has the appropriate server-side plugin loaded.

The following sections provide installation and usage information specific to LDAP pluggable authentication:

For general information about pluggable authentication in MySQL, see Section 8.2.17, “Pluggable Authentication”. For information about the mysql_clear_password plugin, seeSection 8.4.1.4, “Client-Side Cleartext Pluggable Authentication”. For proxy user information, see Section 8.2.19, “Proxy Users”.

Note

If your system supports PAM and permits LDAP as a PAM authentication method, another way to use LDAP for MySQL user authentication is to use the server-sideauthentication_pam plugin. SeeSection 8.4.1.5, “PAM Pluggable Authentication”.

Prerequisites for LDAP Pluggable Authentication

To use LDAP pluggable authentication for MySQL, these prerequisites must be satisfied:

How LDAP Authentication of MySQL Users Works

This section provides an overview of how MySQL and LDAP work together to authenticate MySQL users. For examples showing how to set up MySQL accounts to use specific LDAP authentication plugins, seeUsing LDAP Pluggable Authentication. For information about authentication methods available to the LDAP plugins, seeLDAP Authentication Methods.

The client connects to the MySQL server, providing the MySQL client user name and a password:

If the client user name and host name match no MySQL account, the connection is rejected.

If there is a matching MySQL account, authentication against LDAP occurs. The LDAP server looks for an entry matching the user and authenticates the entry against the LDAP password:

If the LDAP server finds no match or multiple matches, authentication fails and the client connection is rejected.

If the LDAP server finds a single match, LDAP authentication succeeds (assuming that the password is correct), the LDAP server returns the LDAP entry, and the authentication plugin determines the name of the authenticated user based on that entry:

The MySQL server compares the client user name with the authenticated user name to determine whether proxying occurs for the client session:

Installing LDAP Pluggable Authentication

This section describes how to install the server-side LDAP authentication plugins. For general information about installing plugins, see Section 7.6.1, “Installing and Uninstalling Plugins”.

To be usable by the server, the plugin library files must be located in the MySQL plugin directory (the directory named by the plugin_dir system variable). If necessary, configure the plugin directory location by setting the value ofplugin_dir at server startup.

The server-side plugin library file base names areauthentication_ldap_simple andauthentication_ldap_sasl. The file name suffix differs per platform (for example,.so for Unix and Unix-like systems,.dll for Windows).

Note

On Microsoft Windows, the server plugin for SASL-based LDAP authentication is not supported, but the client plugin is supported. On other platforms, both the server and client plugins are supported.

To load the plugins at server startup, use--plugin-load-add options to name the library files that contain them. With this plugin-loading method, the options must be given each time the server starts. Also, specify values for any plugin-provided system variables you wish to configure.

Each server-side LDAP plugin exposes a set of system variables that enable its operation to be configured. Setting most of these is optional, but you must set the variables that specify the LDAP server host (so the plugin knows where to connect) and base distinguished name for LDAP bind operations (to limit the scope of searches and obtain faster searches). For details about all LDAP system variables, seeSection 8.4.1.13, “Pluggable Authentication System Variables”.

To load the plugins and set the LDAP server host and base distinguished name for LDAP bind operations, put lines such as these in your my.cnf file, adjusting the.so suffix for your platform as necessary:

[mysqld]
plugin-load-add=authentication_ldap_simple.so
authentication_ldap_simple_server_host=127.0.0.1
authentication_ldap_simple_bind_base_dn="dc=example,dc=com"
plugin-load-add=authentication_ldap_sasl.so
authentication_ldap_sasl_server_host=127.0.0.1
authentication_ldap_sasl_bind_base_dn="dc=example,dc=com"

After modifying my.cnf, restart the server to cause the new settings to take effect.

Alternatively, to load the plugins at runtime, use these statements, adjusting the .so suffix for your platform as necessary:

INSTALL PLUGIN authentication_ldap_simple
  SONAME 'authentication_ldap_simple.so';
INSTALL PLUGIN authentication_ldap_sasl
  SONAME 'authentication_ldap_sasl.so';

INSTALL PLUGIN loads the plugin immediately, and also registers it in themysql.plugins system table to cause the server to load it for each subsequent normal startup without the need for --plugin-load-add.

After installing the plugins at runtime, the system variables that they expose become available and you can add settings for them to your my.cnf file to configure the plugins for subsequent restarts. For example:

[mysqld]
authentication_ldap_simple_server_host=127.0.0.1
authentication_ldap_simple_bind_base_dn="dc=example,dc=com"
authentication_ldap_sasl_server_host=127.0.0.1
authentication_ldap_sasl_bind_base_dn="dc=example,dc=com"

After modifying my.cnf, restart the server to cause the new settings to take effect.

To set and persist each value at runtime rather than at startup, use these statements:

SET PERSIST authentication_ldap_simple_server_host='127.0.0.1';
SET PERSIST authentication_ldap_simple_bind_base_dn='dc=example,dc=com';
SET PERSIST authentication_ldap_sasl_server_host='127.0.0.1';
SET PERSIST authentication_ldap_sasl_bind_base_dn='dc=example,dc=com';

SET PERSIST sets a value for the running MySQL instance. It also saves the value, causing it to carry over to subsequent server restarts. To change a value for the running MySQL instance without having it carry over to subsequent restarts, use the GLOBAL keyword rather than PERSIST. SeeSection 15.7.6.1, “SET Syntax for Variable Assignment”.

To verify plugin installation, examine the Information SchemaPLUGINS table or use theSHOW PLUGINS statement (seeSection 7.6.2, “Obtaining Server Plugin Information”). For example:

mysql> SELECT PLUGIN_NAME, PLUGIN_STATUS
       FROM INFORMATION_SCHEMA.PLUGINS
       WHERE PLUGIN_NAME LIKE '%ldap%';
+----------------------------+---------------+
| PLUGIN_NAME                | PLUGIN_STATUS |
+----------------------------+---------------+
| authentication_ldap_sasl   | ACTIVE        |
| authentication_ldap_simple | ACTIVE        |
+----------------------------+---------------+

If a plugin fails to initialize, check the server error log for diagnostic messages.

To associate MySQL accounts with an LDAP plugin, seeUsing LDAP Pluggable Authentication.

Additional Notes for SELinux

On systems running EL6 or EL that have SELinux enabled, changes to the SELinux policy are required to enable the MySQL LDAP plugins to communicate with the LDAP service:

  1. Create a file mysqlldap.te with these contents:
module mysqlldap 1.0;  
require {  
        type ldap_port_t;  
        type mysqld_t;  
        class tcp_socket name_connect;  
}  
#============= mysqld_t ==============  
allow mysqld_t ldap_port_t:tcp_socket name_connect;
  1. Compile the security policy module into a binary representation:
checkmodule -M -m mysqlldap.te -o mysqlldap.mod
  1. Create an SELinux policy module package:
semodule_package -m mysqlldap.mod  -o mysqlldap.pp
  1. Install the module package:
semodule -i mysqlldap.pp
  1. When the SELinux policy changes have been made, restart the MySQL server:
service mysqld restart
Uninstalling LDAP Pluggable Authentication

The method used to uninstall the LDAP authentication plugins depends on how you installed them:

UNINSTALL PLUGIN authentication_ldap_simple;  
UNINSTALL PLUGIN authentication_ldap_sasl;

In addition, remove from your my.cnf file any startup options that set LDAP plugin-related system variables. If you usedSET PERSIST to persist LDAP system variables, useRESET PERSIST to remove the settings.

LDAP Pluggable Authentication and ldap.conf

For installations that use OpenLDAP, theldap.conf file provides global defaults for LDAP clients. Options can be set in this file to affect LDAP clients, including the LDAP authentication plugins. OpenLDAP uses configuration options in this order of precedence:

If the library defaults or ldap.conf values do not yield appropriate option values, an LDAP authentication plugin may be able to set related variables to affect the LDAP configuration directly. For example, LDAP plugins can override ldap.conf for parameters such as these:

For more information about ldap.conf consult the ldap.conf(5) man page.

Setting Timeouts for LDAP Pluggable Authentication

For MySQL accounts to connect to a MySQL server using LDAP pluggable authentication, the LDAP server must be available and operational. The interaction between the MySQL and LDAP servers involves two steps. First, the MySQL server establishes a connection to the LDAP server over TCP. Second, the MySQL server sends an LDAP binding request over the connection to the LDAP server and waits for a reply before authenticating the account. If either step fails, the MySQL account cannot connect to the MySQL server.

Short-duration timeouts that supersede a host system's timeout values are applied to both the connection and response steps by default. In all cases, the account user receives notification that their attempt to connect to MySQL is denied if the timeout expires. Client-side and server-side logging can provide additional information. On the client side, set the following environmental variable to elevate the detail level and then restart MySQL client:

AUTHENTICATION_LDAP_CLIENT_LOG=5
export AUTHENTICATION_LDAP_CLIENT_LOG

The following system variables support default timeouts for SASL-based and simple LDAP authentication on Linux platforms only.

Table 8.22 System variables for SASL-based and simple LDAP Authentication

Timeout values for LDAP authentication are adjustable at server startup and at runtime. If you set a timeout to zero using one of these variables, you effectively disengage it and MySQL server reverts to using the host system's default timeout.

Using LDAP Pluggable Authentication

This section describes how to enable MySQL accounts to connect to the MySQL server using LDAP pluggable authentication. It is assumed that the server is running with the appropriate server-side plugins enabled, as described inInstalling LDAP Pluggable Authentication, and that the appropriate client-side plugins are available on the client host.

This section does not describe LDAP configuration or administration. You are assumed to be familiar with those topics.

The two server-side LDAP plugins each work with a specific client-side plugin:

Overall requirements for LDAP authentication of MySQL users:

The instructions here assume the following scenario:

uid=betsy_ldap,ou=People,dc=example,dc=com  
uid=boris_ldap,ou=People,dc=example,dc=com

The instructions for setting up an account that uses LDAP authentication depend on which server-side LDAP plugin is used. The following sections describe several usage scenarios.

Simple LDAP Authentication (Without Proxying)

The procedure outlined in this section requires thatauthentication_ldap_simple_group_search_attr be set to an empty string, like this:

SET GLOBAL.authentication_ldap_simple_group_search_attr='';

Otherwise, proxying is used by default.

To set up a MySQL account for simple LDAP authentication, use a CREATE USER statement to specify the authentication_ldap_simple plugin, optionally including the LDAP user distinguished name (DN), as shown here:

CREATE USER user
  IDENTIFIED WITH authentication_ldap_simple
  [BY 'LDAP user DN'];

Suppose that MySQL user betsy has this entry in the LDAP directory:

uid=betsy_ldap,ou=People,dc=example,dc=com

Then the statement to create the MySQL account forbetsy looks like this:

CREATE USER 'betsy'@'localhost'
  IDENTIFIED WITH authentication_ldap_simple
  AS 'uid=betsy_ldap,ou=People,dc=example,dc=com';

The authentication string specified in theBY clause does not include the LDAP password. That must be provided by the client user at connect time.

Clients connect to the MySQL server by providing the MySQL user name and LDAP password, and by enabling the client-sidemysql_clear_password plugin:

$> mysql --user=betsy --password --enable-cleartext-plugin
Enter password: betsy_ldap_password

Note

The client-side mysql_clear_password authentication plugin leaves the password untouched, so client programs send it to the MySQL server as cleartext. This enables the password to be passed as is to the LDAP server. A cleartext password is necessary to use the server-side LDAP library without SASL, but may be a security problem in some configurations. These measures minimize the risk:

The authentication process occurs as follows:

  1. The client-side plugin sends betsy and_betsypassword_ as the client user name and LDAP password to the MySQL server.
  2. The connection attempt matches the'betsy'@'localhost' account. The server-side LDAP plugin finds that this account has an authentication string of'uid=betsy_ldap,ou=People,dc=example,dc=com' to name the LDAP user DN. The plugin sends this string and the LDAP password to the LDAP server.
  3. The LDAP server finds the LDAP entry forbetsy_ldap and the password matches, so LDAP authentication succeeds.
  4. The LDAP entry has no group attribute, so the server-side plugin returns the client user name (betsy) as the authenticated user. This is the same user name supplied by the client, so no proxying occurs and the client session uses the'betsy'@'localhost' account for privilege checking.

Had the CREATE USER statement contained no BY clause to specify thebetsy_ldap LDAP distinguished name, authentication attempts would use the user name provided by the client (in this case, betsy). In the absence of an LDAP entry for betsy, authentication would fail.

SASL-Based LDAP Authentication (Without Proxying)

The procedure outlined in this section requires thatauthentication_ldap_sasl_group_search_attr be set to an empty string, like this:

SET GLOBAL.authentication_ldap_sasl_group_search_attr='';

Otherwise, proxying is used by default.

To set up a MySQL account for SALS LDAP authentication, use aCREATE USER statement to specify the authentication_ldap_sasl plugin, optionally including the LDAP user distinguished name (DN), as shown here:

CREATE USER user
  IDENTIFIED WITH authentication_ldap_sasl
  [BY 'LDAP user DN'];

Suppose that MySQL user boris has this entry in the LDAP directory:

uid=boris_ldap,ou=People,dc=example,dc=com

Then the statement to create the MySQL account forboris looks like this:

CREATE USER 'boris'@'localhost'
  IDENTIFIED WITH authentication_ldap_sasl
  AS 'uid=boris_ldap,ou=People,dc=example,dc=com';

The authentication string specified in theBY clause does not include the LDAP password. That must be provided by the client user at connect time.

Clients connect to the MySQL server by providing the MySQL user name and LDAP password:

$> mysql --user=boris --password
Enter password: boris_ldap_password

For the server-sideauthentication_ldap_sasl plugin, clients use the client-sideauthentication_ldap_sasl_client plugin. If a client program does not find the client-side plugin, specify a --plugin-dir option that names the directory where the plugin library file is installed.

The authentication process for boris is similar to that previously described forbetsy with simple LDAP authentication, except that the client-side and server-side SASL LDAP plugins use SASL messages for secure transmission of credentials within the LDAP protocol, to avoid sending the cleartext password between the MySQL client and server.

LDAP Authentication with Proxying

LDAP authentication plugins support proxying, enabling a user to connect to the MySQL server as one user but assume the privileges of a different user. This section describes basic LDAP plugin proxy support. The LDAP plugins also support specification of group preference and proxy user mapping; seeLDAP Authentication Group Preference and Mapping Specification.

The proxying implementation described here is based on use of LDAP group attribute values to map connecting MySQL users who authenticate using LDAP onto other MySQL accounts that define different sets of privileges. Users do not connect directly through the accounts that define the privileges. Instead, they connect through a default proxy account authenticated with LDAP, such that all external logins are mapped to the proxied MySQL accounts that hold the privileges. Any user who connects using the proxy account is mapped to one of those proxied MySQL accounts, the privileges for which determine the database operations permitted to the external user.

The instructions here assume the following scenario:

uid=basha,ou=People,dc=example,dc=com,cn=accounting  
uid=basil,ou=People,dc=example,dc=com,cn=front_office

At connect time, the group attribute values become the authenticated user names, so they name theaccounting andfront_office proxied accounts.

Create the default proxy MySQL account:

CREATE USER ''@'%'
  IDENTIFIED WITH authentication_ldap_sasl;

The proxy account definition has no AS '_`authstring`_' clause to name an LDAP user DN. Thus:

Create the proxied accounts and grant to each one the privileges it should have:

CREATE USER 'accounting'@'localhost'
  IDENTIFIED WITH mysql_no_login;
CREATE USER 'front_office'@'localhost'
  IDENTIFIED WITH mysql_no_login;

GRANT ALL PRIVILEGES
  ON accountingdb.*
  TO 'accounting'@'localhost';
GRANT ALL PRIVILEGES
  ON frontdb.*
  TO 'front_office'@'localhost';

The proxied accounts use the mysql_no_login authentication plugin to prevent clients from using the accounts to log in directly to the MySQL server. Instead, users who authenticate using LDAP are expected to use the default ''@'%' proxy account. (This assumes that the mysql_no_login plugin is installed. For instructions, seeSection 8.4.1.9, “No-Login Pluggable Authentication”.) For alternative methods of protecting proxied accounts against direct use, seePreventing Direct Login to Proxied Accounts.

Grant to the proxy account thePROXY privilege for each proxied account:

GRANT PROXY
  ON 'accounting'@'localhost'
  TO ''@'%';
GRANT PROXY
  ON 'front_office'@'localhost'
  TO ''@'%';

Use the mysql command-line client to connect to the MySQL server as basha.

$> mysql --user=basha --password
Enter password: basha_password (basha LDAP password)

Authentication occurs as follows:

  1. The server authenticates the connection using the default''@'%' proxy account, for client userbasha.
  2. The matching LDAP entry is:
uid=basha,ou=People,dc=example,dc=com,cn=accounting
  1. The matching LDAP entry has group attributecn=accounting, soaccounting becomes the authenticated proxied user.
  2. The authenticated user differs from the client user namebasha, with the result thatbasha is treated as a proxy foraccounting, andbasha assumes the privileges of the proxied accounting account. The following query returns output as shown:
mysql> SELECT USER(), CURRENT_USER(), @@proxy_user;  
+-----------------+----------------------+--------------+  
| USER()          | CURRENT_USER()       | @@proxy_user |  
+-----------------+----------------------+--------------+  
| basha@localhost | accounting@localhost | ''@'%'       |  
+-----------------+----------------------+--------------+

This demonstrates that basha uses the privileges granted to the proxiedaccounting MySQL account, and that proxying occurs through the default proxy user account.

Now connect as basil instead:

$> mysql --user=basil --password
Enter password: basil_password (basil LDAP password)

The authentication process for basil is similar to that previously described forbasha:

  1. The server authenticates the connection using the default''@'%' proxy account, for client userbasil.
  2. The matching LDAP entry is:
uid=basil,ou=People,dc=example,dc=com,cn=front_office
  1. The matching LDAP entry has group attributecn=front_office, sofront_office becomes the authenticated proxied user.
  2. The authenticated user differs from the client user namebasil, with the result thatbasil is treated as a proxy forfront_office, andbasil assumes the privileges of the proxied front_office account. The following query returns output as shown:
mysql> SELECT USER(), CURRENT_USER(), @@proxy_user;  
+-----------------+------------------------+--------------+  
| USER()          | CURRENT_USER()         | @@proxy_user |  
+-----------------+------------------------+--------------+  
| basil@localhost | front_office@localhost | ''@'%'       |  
+-----------------+------------------------+--------------+

This demonstrates that basil uses the privileges granted to the proxiedfront_office MySQL account, and that proxying occurs through the default proxy user account.

LDAP Authentication Group Preference and Mapping Specification

As described inLDAP Authentication with Proxying, basic LDAP authentication proxying works by the principle that the plugin uses the first group name returned by the LDAP server as the MySQL proxied user account name. This simple capability does not enable specifying any preference about which group name to use if the LDAP server returns multiple group names, or specifying any name other than the group name as the proxied user name.

For MySQL accounts that use LDAP authentication, the authentication string can specify the following information to enable greater proxying flexibility:

Consider the following MySQL proxy account definition:

CREATE USER ''@'%'
  IDENTIFIED WITH authentication_ldap_sasl
  AS '+ou=People,dc=example,dc=com#grp1=usera,grp2,grp3=userc';

The authentication string has a user DN suffixou=People,dc=example,dc=com prefixed by the+ character. Thus, as described inLDAP Authentication User DN Suffixes, the full user DN is constructed from the user DN suffix as specified, plus the client user name as theuid attribute.

The remaining part of the authentication string begins with#, which signifies the beginning of group preference and mapping information. This part of the authentication string lists group names in the ordergrp1, grp2,grp3. The LDAP plugin compares that list with the set of group names returned by the LDAP server, looking in list order for a match against the returned names. The plugin uses the first match, or if there is no match, authentication fails.

Suppose that the LDAP server returns groupsgrp3, grp2, andgrp7. The LDAP plugin usesgrp2 because it is the first group in the authentication string that matches, even though it is not the first group returned by the LDAP server. If the LDAP server returns grp4, grp2, andgrp1, the plugin usesgrp1 even though grp2 also matches. grp1 has a precedence higher than grp2 because it is listed earlier in the authentication string.

Assuming that the plugin finds a group name match, it performs mapping from that group name to the MySQL proxied user name, if there is one. For the example proxy account, mapping occurs as follows:

If the LDAP server returns a group in DN format, the LDAP plugin parses the group DN to extract the group name from it.

To specify LDAP group preference and mapping information, these principles apply:

"my group name"="my user name"

If an item has group and user names ofmy_group_name andmy_user_name (which contain no special characters), it may but need not be written using quotes. Any of the following are valid: 

my_group_name=my_user_name  
my_group_name="my_user_name"  
"my_group_name"=my_user_name  
"my_group_name"="my_user_name"
LDAP Authentication User DN Suffixes

LDAP authentication plugins permit the authentication string that provides user DN information to begin with a+ prefix character:

This account authentication string does not have+ at the beginning, so it is taken as the full user DN:

CREATE USER 'baldwin'
  IDENTIFIED WITH authentication_ldap_simple
  AS 'uid=admin,ou=People,dc=example,dc=com';

The client connects with the user name specified in the account (baldwin). In this case, that name is not used because the authentication string has no prefix and thus fully specifies the user DN.

This account authentication string does have+ at the beginning, so it is taken as just part of the user DN:

CREATE USER 'accounting'
  IDENTIFIED WITH authentication_ldap_simple
  AS '+ou=People,dc=example,dc=com';

The client connects with the user name specified in the account (accounting), which in this case is used as the uid attribute together with the authentication string to construct the user DN:uid=accounting,ou=People,dc=example,dc=com

The accounts in the preceding examples have a nonempty user name, so the client always connects to the MySQL server using the same name as specified in the account definition. If an account has an empty user name, such as the default anonymous''@'%' proxy account described inLDAP Authentication with Proxying, clients might connect to the MySQL server with varying user names. But the principle is the same: If the authentication string begins with +, the plugin uses the user name sent by the client together with the authentication string to construct the user DN.

LDAP Authentication Methods

The LDAP authentication plugins use a configurable authentication method. The appropriate system variable and available method choices are plugin-specific:

See the system variable descriptions for information about each permitted method. Also, depending on the method, additional configuration may be needed, as described in the following sections.

The GSSAPI/Kerberos Authentication Method

Generic Security Service Application Program Interface (GSSAPI) is a security abstraction interface. Kerberos is an instance of a specific security protocol that can be used through that abstract interface. Using GSSAPI, applications authenticate to Kerberos to obtain service credentials, then use those credentials in turn to enable secure access to other services.

One such service is LDAP, which is used by the client-side and server-side SASL LDAP authentication plugins. When theauthentication_ldap_sasl_auth_method_name system variable is set to GSSAPI, these plugins use the GSSAPI/Kerberos authentication method. In this case, the plugins communicate securely using Kerberos without using LDAP messages directly. The server-side plugin then communicates with the LDAP server to interpret LDAP authentication messages and retrieve LDAP groups.

GSSAPI/Kerberos is supported as an LDAP authentication method for MySQL servers and clients on Linux. It is useful in Linux environments where applications have access to LDAP through Microsoft Active Directory, which has Kerberos enabled by default.

The following discussion provides information about the configuration requirements for using the GSSAPI method. Familiarity is assumed with Kerberos concepts and operation. The following list briefly defines several common Kerberos terms. You may also find the Glossary section ofRFC 4120 helpful.

LDAP authentication using Kerberos requires both a KDC server and an LDAP server. This requirement can be satisfied in different ways:

Kerberos must also be available on the client host. A client contacts the AS using a password to obtain a TGT. The client then uses the TGT to obtain access from the TGS to other services, such as LDAP.

The following sections discuss the configuration steps to use GSSAPI/Kerberos for SASL LDAP authentication in MySQL:

Verify Kerberos and LDAP Availability

The following example shows how to test availability of Kerberos in Active Directory. The example makes these assumptions:

With those assumptions satisfied, follow this procedure:

  1. Verify that the Kerberos library is installed and configured correctly in the operating system. For example, to configure a MYSQL.LOCAL domain for use during MySQL authentication, the/etc/krb5.conf Kerberos configuration file should contain something like this:
[realms]  
  MYSQL.LOCAL = {  
    kdc = ldap_auth.example.com  
    admin_server = ldap_auth.example.com  
    default_domain = MYSQL.LOCAL  
  }
  1. You may need to add an entry to/etc/hosts for the server host:
198.51.100.10 ldap_auth ldap_auth.example.com
  1. Check whether Kerberos authentication works correctly:
    1. Use kinit to authenticate to Kerberos:
    $> kinit bredon@MYSQL.LOCAL  
Password for bredon@MYSQL.LOCAL: (enter password here)

    The command authenticates for the Kerberos principal named bredon@MYSQL.LOCAL. Enter the principal's password when the command prompts for it. The KDC returns a TGT that is cached on the client side for use by other Kerberos-aware applications.
    2. Use klist to check whether the TGT was obtained correctly. The output should be similar to this: 

    $> klist  
Ticket cache: FILE:/tmp/krb5cc_244306  
Default principal: bredon@MYSQL.LOCAL  
Valid starting       Expires              Service principal  
03/23/2021 08🔞33  03/23/2021 18🔞33  krbtgt/MYSQL.LOCAL@MYSQL.LOCAL
  2. Check whether ldapsearch works with the Kerberos TGT using this command, which searches for users in the MYSQL.LOCAL domain:
ldapsearch -h 198.51.100.10 -Y GSSAPI -b "dc=MYSQL,dc=LOCAL"
Configure the Server-Side SASL LDAP Authentication Plugin for GSSAPI/Kerberos

Assuming that the LDAP server is accessible through Kerberos as just described, configure the server-side SASL LDAP authentication plugin to use the GSSAPI/Kerberos authentication method. (For general LDAP plugin installation information, seeInstalling LDAP Pluggable Authentication.) Here is an example of plugin-related settings the servermy.cnf file might contain:

[mysqld]
plugin-load-add=authentication_ldap_sasl.so
authentication_ldap_sasl_auth_method_name="GSSAPI"
authentication_ldap_sasl_server_host=198.51.100.10
authentication_ldap_sasl_server_port=389
authentication_ldap_sasl_bind_root_dn="cn=admin,cn=users,dc=MYSQL,dc=LOCAL"
authentication_ldap_sasl_bind_root_pwd="password"
authentication_ldap_sasl_bind_base_dn="cn=users,dc=MYSQL,dc=LOCAL"
authentication_ldap_sasl_user_search_attr="sAMAccountName"

Those option file settings configure the SASL LDAP plugin as follows:

Create a MySQL Account That Uses GSSAPI/Kerberos for LDAP Authentication

MySQL authentication using the SASL LDAP authentication plugin with the GSSAPI/Kerberos method is based on a user that is a Kerberos principal. The following discussion uses a principal named bredon@MYSQL.LOCAL as this user, which must be registered in several places:

uid=bredon,dc=MYSQL,dc=LOCAL

Note
In Active Directory (which uses Kerberos as the default authentication method), creating a user creates both the Kerberos principal and the LDAP entry.

Assume that the Kerberos principal and LDAP entry have been registered by the appropriate service administrators, and that, as previously described inInstalling LDAP Pluggable Authentication, and Configure the Server-Side SASL LDAP Authentication Plugin for GSSAPI/Kerberos, the MySQL server has been started with appropriate configuration settings for the server-side SASL LDAP plugin. The MySQL DBA then creates a MySQL account that corresponds to the Kerberos principal name, including the domain name.

Note

The SASL LDAP plugin uses a constant user DN for Kerberos authentication and ignores any user DN configured from MySQL. This has certain implications:

The following statements create a proxy user namedbredon@MYSQL.LOCAL that assumes the privileges of the proxied user namedproxied_krb_usr. Other GSSAPI/Kerberos users that should have the same privileges can similarly be created as proxy users for the same proxied user.

-- create proxy account
CREATE USER 'bredon@MYSQL.LOCAL'
  IDENTIFIED WITH authentication_ldap_sasl
  BY '#krb_grp=proxied_krb_user';

-- create proxied account and grant its privileges;
-- use mysql_no_login plugin to prevent direct login
CREATE USER 'proxied_krb_user'
  IDENTIFIED WITH mysql_no_login;
GRANT ALL
  ON krb_user_db.*
  TO 'proxied_krb_user';

-- grant to proxy account the
-- PROXY privilege for proxied account
GRANT PROXY
  ON 'proxied_krb_user'
  TO 'bredon@MYSQL.LOCAL';

Observe closely the quoting for the proxy account name in the first CREATE USER statement and the GRANT PROXY statement:

Note

When creating an account that authenticates using theauthentication_ldap_sasl SASL LDAP authentication plugin with the GSSAPI/Kerberos authentication method, the CREATE USER statement includes the realm as part of the user name. This differs from creating accounts that use theauthentication_kerberos Kerberos plugin. For such accounts, the CREATE USER statement does not include the realm as part of the user name. Instead, specify the realm as the authentication string in the BY clause. See Create a MySQL Account That Uses Kerberos Authentication.

The proxied account uses the mysql_no_login authentication plugin to prevent clients from using the account to log in directly to the MySQL server. Instead, it is expected that users who authenticate using LDAP use thebredon@MYSQL.LOCAL proxy account. (This assumes that the mysql_no_login plugin is installed. For instructions, seeSection 8.4.1.9, “No-Login Pluggable Authentication”.) For alternative methods of protecting proxied accounts against direct use, seePreventing Direct Login to Proxied Accounts.

Use the MySQL Account to Connect to the MySQL Server

After a MySQL account that authenticates using GSSAPI/Kerberos has been set up, clients can use it to connect to the MySQL server. Kerberos authentication can take place either prior to or at the time of MySQL client program invocation:

$> kinit bredon@MYSQL.LOCAL  
Password for bredon@MYSQL.LOCAL: (enter password here)

The resulting TGT is cached and becomes available for use by other Kerberos-aware applications, such as programs that use the client-side SASL LDAP authentication plugin. In this case, the MySQL client program authenticates to the MySQL server using the TGT, so invoke the client without specifying a user name or password: 

mysql --default-auth=authentication_ldap_sasl_client

As just described, when the TGT is cached, user-name and password options are not needed in the client command. If the command includes them anyway, they are handled as follows: 

mysql --default-auth=authentication_ldap_sasl_client  
  --user=bredon@MYSQL.LOCAL  
  --password

If you are uncertain whether a TGT exists, you can useklist to check.

Authentication occurs as follows:

  1. The client uses the TGT to authenticate using Kerberos.
  2. The server finds the LDAP entry for the principal and uses it to authenticate the connection for thebredon@MYSQL.LOCAL MySQL proxy account.
  3. The group mapping information in the proxy account authentication string ('#krb_grp=proxied_krb_user') indicates that the authenticated proxied user should beproxied_krb_user.
  4. bredon@MYSQL.LOCAL is treated as a proxy for proxied_krb_user, and the following query returns output as shown:
mysql> SELECT USER(), CURRENT_USER(), @@proxy_user;  
+------------------------------+--------------------+--------------------------+  
| USER()                       | CURRENT_USER()     | @@proxy_user             |  
+------------------------------+--------------------+--------------------------+  
| bredon@MYSQL.LOCAL@localhost | proxied_krb_user@% | 'bredon@MYSQL.LOCAL'@'%' |  
+------------------------------+--------------------+--------------------------+

The USER() value indicates the user name used for the client command (bredon@MYSQL.LOCAL) and the host from which the client connected (localhost).
The CURRENT_USER() value is the full name of the proxied user account, which consists of the proxied_krb_user user part and the % host part.
The@@proxy_user value indicates the full name of the account used to make the connection to the MySQL server, which consists of thebredon@MYSQL.LOCAL user part and the% host part.
This demonstrates that proxying occurs through thebredon@MYSQL.LOCAL proxy user account, and that bredon@MYSQL.LOCAL assumes the privileges granted to theproxied_krb_user proxied user account.

A TGT once obtained is cached on the client side and can be used until it expires without specifying the password again. However the TGT is obtained, the client-side plugin uses it to acquire service tickets and communicate with the server-side plugin.

Note

When the client-side authentication plugin itself obtains the TGT, the client user may not want the TGT to be reused. As described inClient Configuration Parameters for LDAP Authentication, the local /etc/krb5.conf file can be used to cause the client-side plugin to destroy the TGT when done with it.

The server-side plugin has no access to the TGT itself or the Kerberos password used to obtain it.

The LDAP authentication plugins have no control over the caching mechanism (storage in a local file, in memory, and so forth), but Kerberos utilities such askswitch may be available for this purpose.

Client Configuration Parameters for LDAP Authentication

The authentication_ldap_sasl_client client-side SASL LDAP plugin reads the local/etc/krb5.conf file. If this file is missing or inaccessible, an error occurs. Assuming that the file is accessible, it can include an optional[appdefaults] section to provide information used by the plugin. Place the information within the mysql part of the section. For example:

[appdefaults]
  mysql = {
    ldap_server_host = "ldap_host.example.com"
    ldap_destroy_tgt = true
  }

The client-side plugin recognizes these parameters in themysql section:

LDAP Search Referral

An LDAP server can be configured to delegate LDAP searches to another LDAP server, a functionality known as LDAP referral. Suppose that the server a.example.com holds a "dc=example,dc=com" root DN and wishes to delegate searches to another serverb.example.com. To enable this,a.example.com would be configured with a named referral object having these attributes:

dn: dc=subtree,dc=example,dc=com
objectClass: referral
objectClass: extensibleObject
dc: subtree
ref: ldap://b.example.com/dc=subtree,dc=example,dc=com

An issue with enabling LDAP referral is that searches can fail with LDAP operation errors when the search base DN is the root DN, and referral objects are not set. A MySQL DBA might wish to avoid such referral errors for the LDAP authentication plugins, even though LDAP referral might be set globally in the ldap.conf configuration file. To configure on a plugin-specific basis whether the LDAP server should use LDAP referral when communicating with each plugin, set theauthentication_ldap_simple_referral andauthentication_ldap_sasl_referral system variables. Setting either variable toON or OFF causes the corresponding LDAP authentication plugin to tell the LDAP server whether to use referral during MySQL authentication. Each variable has a plugin-specific effect and does not affect other applications that communicate with the LDAP server. Both variables are OFF by default.