MySQL8 authentication plug-in—LDAP Pluggable Authentication

Original 2023-05-05 19:00 Heplit

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 obtain user, credential, and group information.

LDAP Pluggable Authentication provides the following features:

● External authentication: LDAP authentication enables MySQL Server to accept connections from users defined outside of the MySQL authorization tables in the LDAP directory.

● Proxy user support: LDAP authentication can return a user name different from the external user name passed by the client program to MySQL according to the LDAP group to which the external user belongs. This means that an LDAP plugin can return a MySQL user that defines the permissions that an LDAP-authenticated external user should have. For example, if joe's LDAP group is developer, an LDAP user named joe can connect and have the privileges of a MySQL user named developer.

● Security: Using TLS, the connection to the LDAP server can be secure.

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

plugin and library name (plugin and library name for simple LDAP authentication)

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

plugin and library name (plugin and library name for SASL-based LDAP authentication)

plugin or file	plugin or file name
Server-side plugin	authentication_ldap_sasl
Client-side plugin	authentication_ldap_sasl_client
Library file	authentication_ldap_sasl.so, authentication_ldap_sasl_client.so

The library files only include authentication_ldap_XXX authentication plugins. The client mysql_clear_password plugin is built into the libmysqlclient client library.

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

● The server-side
authentication_ldap_simple plugin performs simple ldap authentication. For connections from accounts that use this plugin, client programs use the client-side mysql_clear_password plugin, which sends the password to the server as clear text. No password hashing or encryption is used, so a secure connection between the MySQL client and server is recommended to prevent password disclosure.

● The server-side authentication_ldap_sasl plugin performs sasl-based ldap authentication. For connections from accounts that use this plugin, client programs use the client
authentication_ldap_sasl_client plugin. The client and server-side SASL LDAP plugin uses SASL messages to securely transfer credentials within the LDAP protocol to avoid sending clear text passwords between the MySQL client and server.

The server-side LDAP authentication plugin is only included with MySQL Enterprise Edition. They are not included in the MySQL community distribution. The client-side SASL LDAP plugin is included in all distributions, including community distributions. As mentioned previously, the client-side mysql_clear_password plugin is built into the libmysqlclient client library, which is also included in all distributions. This enables clients from any distribution to connect to servers loaded with the appropriate server-side plugins.

Prerequisites for LDAP Pluggable Authentication

To use LDAP pluggable authentication with MySQL, the following prerequisites must be met:

● An LDAP server must be available for the LDAP Authentication Plugin to communicate with.

● LDAP users to be authenticated by MySQL must exist in a directory managed by the LDAP server.

● The LDAP client library must
be available on the system using the server-side aauthentication_ldap_sasl or authentication_ldap_simple plugins. Currently, the supported libraries are the Windows native LDAP library, or the OpenLDAP library on non-Windows systems.

● To use SASL-based LDAP authentication:

■ The LDAP server must be configured to communicate with the SASL server.

■ The SASL client library must
be available on the system using the client authentication_ldap_sasl_client plugin. Currently, the only supported library is the Cyrus SASL library.

■ To use a particular SASL authentication method, any other services required by that method must be available. For example, to use GSSAPI/Kerberos, the GSSAPI library and the Kerberos service must be available.

How LDAP Authentication for MySQL Users Works

The client connects to the MySQL server, providing the MySQL client username and password:

● For simple LDAP authentication, the client and server plug-ins communicate passwords as clear text. It is recommended to establish a secure connection between the MySQL client and server to prevent password disclosure.

● For SASL-based LDAP authentication, the client and server plug-ins avoid sending clear text passwords between the MySQL client and server. For example, a plugin might use SASL messages to securely transmit credentials in the LDAP protocol. For the GSSAPI authentication method, the client and server-side plugins use Kerberos for secure communication instead of using LDAP messages directly.

If the client username and hostname do not match the MySQL account, the connection will be refused.

Authentication against LDAP occurs if there is a matching MySQL account. The LDAP server looks for an entry that matches the user and verifies that entry against the LDAP password:

● If the MySQL account is named LDAP user DN, LDAP authentication will use that value and the LDAP password provided by the client. (To associate an LDAP user DN with a MySQL account, include a BY clause in the CREATE user statement that creates the account, which specifies the authentication string.)

● If the MySQL account is not named LDAP user DN, LDAP authentication will use the username and LDAP password provided by the client. In this case, the authentication plugin first binds to the LDAP server using the root DN and password as credentials to look up the user DN based on the client username, and then authenticates that user DN against the LDAP password. If the root DN and password are set to incorrect values, or are empty (not set), and the LDAP server does not allow anonymous connections, binds using root credentials will fail.

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

If the LDAP server finds a match, LDAP authentication succeeds (assuming the password is correct), and the LDAP server returns an LDAP entry from which the authentication plugin determines the name of the authenticated user:

● If the LDAP entry has a group attribute (the cn attribute by default), the plugin will return its value as the authenticated username.

● If the LDAP entry has no group attribute, the authentication plugin returns the client username as the authenticated username.

The MySQL server compares the client username with the authenticated username to determine whether a client session is being proxied:

● If the names are the same, no proxying will occur: the MySQL account matching the client username is used for privilege checking.

● If the names are different, proxying occurs: MySQL looks for an account that matches the authenticated username. This account becomes the proxy user for authorization checks. MySQL accounts that match the client username will be treated as external proxy users.

Install LDAP Pluggable Authentication

To be used by the server, 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 of plugin_dir on server startup.

The base names of the server-side plugin library files are
authentication_ldap_simple and authentication_rdap_sasl. The filename suffix varies by platform (for example, .so for Unix and Unix-like systems, .dll for Windows).

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

To load plugins at server startup, use the -plugin-load-add option to name the library file that contains the plugins. With this method of plugin loading, options must be given every time the server starts. Also, specify values for system variables provided by any plugins you wish to configure.

Each server-side LDAP plugin exposes a set of system variables that configure its operation. Setting most of these is optional, but variables specifying the LDAP server host (so the plugin knows where to connect) and the base DN for LDAP bind operations (to limit the search scope and get faster searches) must be set.

To load the plugin and set the LDAP server host and base DN for LDAP bind operations, put lines like this in your my.cnf file, adjusting the .so suffix for your platform as needed:

[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 for the new settings to take effect.

Alternatively, to load the plugin at runtime, use the following statement, adjusting the platform's .so suffix as needed:

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 registers it in the mysql.plugins system table so that the server loads it on each subsequent normal startup without --plugin-load-add

After plugins are installed at runtime, the system variables they expose will be available, and you can add their settings to your my.cnf file to configure 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 for the new settings to take effect.

To set and persist each value at runtime instead of startup, use the following statement:

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 a running MySQL instance. It also saves the value, thus carrying it over to subsequent server restarts. To change the value of a running MySQL instance without carrying it over to subsequent restarts, use the GLOBAL keyword instead of PERSIST.

To verify plugin installation, check the Information Schema PLUGINS table or use the SHOW PLUGINS statement. For example:

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 the plugin fails to initialize, check the server error log for diagnostic messages.

Additional Notes on SELinux

On systems running EL6 or EL with SELinux enabled, the SELinux policy needs to be changed in order for the MySQL LDAP plugin to communicate with the LDAP service:

1. Create a file mysqlldap.te with the following content

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;

2. Compile the security policy module into a binary representation:

checkmodule -M -m mysqlldap.te -o mysqlldap.mod

3. Create the SELinux policy module package:

semodule_package -m mysqlldap.mod -o mysqlldap.pp

4. Install the module package:

semodule -i mysqlldap.pp

5. When the SELinux policy is changed, restart the MySQL server:

service mysqld restart

Uninstall LDAP Pluggable Authentication

The method used to uninstall the LDAP authentication plugin depends on how it was installed:

● If you installed the plugin with the --plugin-load-add option at server startup, restart the server without these options.

● If you installed plugins at runtime using INSTALL PLUGIN, they will remain installed across server restarts. To uninstall them, use UNINSTALL PLUGIN:

UNINSTALL PLUGIN authentication_ldap_simple;
UNINSTALL PLUGIN authentication_ldap_sasl;

Also, remove any startup options that set LDAP plugin-related system variables from the my.cnf file. If LDAP system variables are preserved with SET PERSIST, use RESET PERSIST to remove the settings.

LDAP Pluggable Authentication and LDAP.conf

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

● The configuration specified by the LDAP client.

● The configuration specified in the ldap.conf file. To disable the use of this file, set the LDAPNOINIT environment variable.

● OpenLDAP library built-in default value.

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

● TLS Configuration: System variables can be used to enable TLS and control CA configuration, such as authentication_ldap_simple_tls and authentication_ldap_simple_ca_path for simple ldap authentication,
and authentication_ldap_sasl_tls and authentication_ldap_sasl_ca_path for SASL LDAP authentication

● LDAP references.

Using LDAP Pluggable Authentication

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

General requirements for MySQL user LDAP authentication:

● Every user to be authenticated must have an LDAP directory entry.

● There must be a MySQL user account that specifies the server-side LDAP authentication plugin and optionally names the associated LDAP user DN. (To associate an LDAP user DN with a MySQL account, include a BY clause in the CREATE user statement that creates the account.) If the account is not named with an LDAP string, LDAP authentication will use the username specified by the client to look up the LDAP entry .

● The client program connects using the connection method appropriate for the server-side authentication plug-in used by the MySQL account. For LDAP authentication, the connection requires a MySQL username and LDAP password. Also, for
accounts using the server-side authentication_ldap_simple plugin, invoke the client program with the --enable-cleartext-plugin option to enable the client-side mysql_clear_password plugin.

The instructions here assume the following situations:

● MySQL users betsy and boris authenticate against the LDAP entries betsy_LDAP and boris_LDAP respectively. (MySQL and LDAP usernames are not necessarily different. Using different names in this discussion helps clarify whether the operational context is MySQL or LDAP)

● LDAP entries use the uid attribute to specify the username. This may vary by LDAP server. Some LDAP servers use the cn attribute for usernames instead of uids. To change the attribute, modify
the authentication_ldap_simple_user_search_attr or authentication_ldap_sasl_user_search_attr system variable appropriately.

● These LDAP entries are available in the directory managed by the LDAP server to provide a distinguished name value that uniquely identifies each user:

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

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

● The CREATE USER statement that creates a MySQL account names the LDAP user in the BY clause to indicate which LDAP entry the MySQL account is authenticating against.

Instructions for setting up an account using LDAP authentication depend on the server-side LDAP plugin used. The following sections describe several usage scenarios.

Simple LDAP Authentication

To configure a MySQL account for simple LDAP authentication, the CREATE USER statement specifies
the authentication_ldap_simple plugin and optionally names the LDAP user DN:

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

Suppose the MySQL user betsy has the following entry in the LDAP directory:

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

Then, the statement to create a MySQL account for betsy 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 the BY clause does not include the LDAP password. Must be provided by the client user at connection time.

The client connects to the MySQL server by providing the MySQL username and LDAP password and enabling the client-side mysql_clear_password plugin:

mysql --user=betsy --password --enable-cleartext-plugin

To reduce the possibility of accidentally using the mysql_clear_password plugin, mysql clients must explicitly enable it. This can be achieved in several ways:

●
Set the LIBMYSQL_ENABLE_CLEARTEXT_PLUGIN environment variable to a value starting with 1, Y, or Y. This will enable the plugin for all client connections.

● The mysql, mysqladmin, mysqlcheck, mysqldump, mysqlshow, and mysqlslap client programs support the --enable-cleartext-plugin plugin option, which enables the plugin on a per-invocation basis.

● The mysql_options() C API function supports a
MYSQL_ENABLE_CLEARTEXT_PLUGIN option, which enables the plug-in on a per-connection basis. Additionally, any program that uses libmysqlclient and reads an option file can enable the plugin by including the enable-cleartext-plugin plugin option in the options group read by the client library.

The authentication process is as follows:

1. The client plugin sends betsy and betsy_password to the MySQL server as the client username and LDAP password.

2. The connection attempt matches the 'betsy'@'localhost' account. The server-side LDAP plugin found that this account has an authentication string '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 an LDAP entry for betsy_ldap, and the passwords match, so LDAP authentication succeeds.

4. The LDAP entry does not have a group attribute, so the server-side plugin returns the client username (betsy) as the authenticated user. This is the same username provided by the client, so no proxying occurs and the client session uses the 'betsy'@'localhost' account for permission checks.

If the matching LDAP entry contains a group attribute, the attribute value will be the authenticated username, and if the value is different from betsy, proxying will occur.

If the CREATE USER statement does not include a BY clause specifying the betsy_ldap LDAP DN, the authentication attempt will use the username provided by the client (betsy in this example). Without an LDAP entry for betsy, authentication will fail.

LDAP authentication based on SASL

To configure a MySQL account for SASL LDAP authentication, the CREATE USER statement specifies the authentication_ldap_sasl plugin and optionally names the LDAP user DN:

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

Assume the MySQL user boris has the following entry in the LDAP directory:

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

Then, the statement to create a MySQL account for boris 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 the BY clause does not include the LDAP password. Must be provided by the client user at connection time.

The client connects to the MySQL server by providing the MySQL username and LDAP password:

mysql --user=boris --password

For the server-side authentication_ldap_sasl plugin, clients use the client-side
authentication_ldap_sasl_client plugin. If the client program cannot find the client plugin, specify a --plugin-dir option that names the directory where the plugin library files are installed.

The authentication process for boris is similar to the simple LDAP authentication process for betsy described previously, except that the client-side and server-side SASL LDAP plugins use SASL messages to securely transmit credentials within the LDAP protocol to avoid sending clear text between the MySQL client and server password.

LDAP authentication with proxy

The instructions here assume the following situations:

● LDAP entries use the uid and cn attributes to specify user name and group values, respectively. To use different user and group attribute names, set the corresponding plugin-specific system variables:

■ For
the authentication_ldap_simple plugin: set authentication_ldap_simple_user_search_attr and authentication_ldap_simple_group_search_attr

■ For the authentication_ldap_sasl plugin: set
authentication_ldap_sasl_user_search_attr and authentication_ldap_sasl_group_search_attr.

● These LDAP entries are available in the directory managed by the LDAP server to provide a DN value that uniquely identifies each user:

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

On connection, the group attribute value becomes the authenticated username, so they name the accounting and front_office proxy accounts.

● These examples assume SASL LDAP authentication. If it is simple LDAP authentication needs to be adjusted appropriately.

Create a default proxy MySQL account:

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

The proxy account definition has no AS" 'auth_string' clause to name the LDAP user DN. Therefore:

● When a client connects, the client username will be the LDAP username to be searched.

● The matching LDAP entry should include a group attribute that names the proxy's MySQL account and defines the permissions the client should have.

Explanation: If MySQL is installed with anonymous users, they may conflict with the default proxy user.

Create proxy accounts and grant each account the permissions it should:

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

Proxy accounts use the mysql_no_login authentication plugin to prevent clients from directly logging into the mysql server using these accounts. Instead, users authenticating with LDAP should use the default ''@'%' proxy account.

To grant the proxy account proxy permissions for each proxy 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

Authentication looks like this:

1. The server authenticates the connection using the default ''@'%' proxy account for client user basha.

2. The matching LDAP entries are:

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

3. The matching LDAP entry has the group attribute cn=accounting, so accounting becomes the authenticated proxy user.

4. The authenticated user is not the same as the client username basha, so basha is considered a proxy for accounting and basha has authority to proxy the accounting account. The following query returns output as shown:

SELECT USER(), CURRENT_USER(), @@proxy_user;
+-----------------+----------------------+--------------+
| USER() | CURRENT_USER() | @@proxy_user |
+-----------------+----------------------+--------------+
| basha@localhost | accounting@localhost | ''@'%' |
+-----------------+----------------------+--------------+

This indicates that basha is using permissions granted to the proxy accounting MySQL account, and that proxying is through the default proxy user account.

Now connect using basil:

mysql --user=basil --password

The authentication process for basil is similar to basha as described earlier:

1. The server authenticates the connection using the default ''@'%'" proxy account for client user basil.

2. The matching LDAP entries are:

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

3. The matching LDAP entry has the group attribute cn=front_office, so front_office becomes the authenticated proxy user.

4. The authenticated user is different from the client username basil, so basil is considered a proxy for front_office, and basil has permissions for the proxied front_office account. The following query returns output as shown:

SELECT USER(), CURRENT_USER(), @@proxy_user;
+-----------------+------------------------+--------------+
| USER() | CURRENT_USER() | @@proxy_user |
+-----------------+------------------------+--------------+
| basil@localhost | front_office@localhost | ''@'%' |
+-----------------+------------------------+--------------+

This indicates that basil uses the privileges granted to the front_office MySQL account being proxied, and that the proxying is through the default proxy user account.

LDAP Authentication Group Preference and Mapping Specification

As described in "LDAP Authentication with Proxy", basic LDAP authentication proxying works in that the plugin uses the first group name returned by the LDAP server as the user account name for the MySQL proxy. This simple function cannot specify any preference for which group name to use if the LDAP server returns more than one group name, nor can it specify anything other than a group name as the proxy username.

Beginning with MySQL 8.0.14, for MySQL accounts using LDAP authentication, the authentication string can specify the following information for greater proxy flexibility:

● A list of groups in order of preference, so that the plugin uses the first group name in the list that matches a group returned by the LDAP server.

● A mapping from group names to proxy user names, such that matching group names can provide the specified name to be used as a proxy user. This provides an alternative to using group names as proxy users.

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 user DN suffix of the authentication string is ou=People,dc=example,dc=com and the prefix is +. Therefore, as described in LDAP Authentication User DN Suffixes, the full user DN is formed from the specified user DN suffix plus the client username as the uid attribute.

The rest of the authentication string starts with #, which indicates the start of group preference and mapping information. This part of the authentication string lists the group names in the order grp1, grp2, grp3. The LDAP plugin compares this list to the set of group names returned by the LDAP server, looking for matches to the returned names in the order of the list. The plugin uses the first match, or fails authentication if there is no match.

Suppose the LDAP server returns groups grp3, grp2 and grp7. The LDAP plugin uses grp2 because it is the first matching group in the authentication string, even though it is not the first group returned by the LDAP server. If the LDAP server returns grp4, grp2, and grp1, the plugin will use grp1 even if grp2 also matches. grp1 takes precedence over grp2 because it is listed earlier in the authentication string.

Assuming the plugin finds a group name match, it performs a mapping (if any) from that group name to the MySQL proxy username. For the proxy account example, the mapping looks like this:

● If the matched group names are grp1 or grp3, they are associated with the user names usera and userc respectively in the authentication string. The plugin uses the corresponding associated username as the proxy username.

● If the matching group name is grp2, there is no associated username in the authentication string. The plugin uses grp2 as the proxy username.

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, apply the following guidelines:

● Begin the group preference and mapping portions of the authentication string with the # prefix character.

● Group preferences and mapping specifications are lists of one or more items, separated by commas. Each item is of the form group_name=user_name or group_name. Items should be listed in group name preference order. For the group name selected by the plug-in from the set of group names returned by the LDAP server as a match, the effects of the two syntaxes are different as follows:

■ For items specified as group_name=user_name (with user name), the group name is mapped to the user name, which is used as the user name for the MySQL proxy.

■ For items specified as group_name (without a username), the group name will be used as the username for the MySQL agent.

● To quote a group or user name that contains special characters such as spaces, enclose it in double quotation marks. For example, if the project's group and user names are my group name and my user name, they must be written in the group map using quotes:

"my group name"="my user name"

If the project's group and user names are my_group_name and my_user_name (with no special characters), quotation marks are allowed but not required. 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"

● To escape a character, precede it with a backslash (\). This is especially useful for including literal double quotes or backslashes that would otherwise not be included literally.

● The user DN does not need to be present in the authentication string, but if present, it must precede the group preferences and mappings section. The user DN can be a full user DN or a user DN suffix with a + prefix character.

LDAP authentication user DN suffix

The LDAP authentication plugin allows authentication strings that provide user DN information to start with a + prefix character:

● In the absence of the + character, the authentication string value is processed as-is without modification.

● If the authentication string starts with +, the plug-in will construct a complete user DN value based on the username sent by the client and the DN specified in the authentication string (+ is removed). In the constructed DN, the client username becomes the value of the attribute specifying the LDAP username. By default, this is the uid; to change the attribute, modify the corresponding system variable (
authentication_ldap_simple_user_search_attr or authentication_rdap_sasl_user_search_aattr ). Authentication strings are stored in the mysql.user system table, and the full user DN is dynamically constructed prior to authentication.

There is no + at the beginning of this account authentication string, so it is treated 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 using the username (baldwin) specified in the account. In this case, the name is not used, since the authentication string has no prefix and thus fully specifies the user DN.

This account authentication string does have a + at the beginning, so it's only part of the user DN:

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

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

The account in the preceding example has a non-empty username, so clients always connect to the MySQL server using the same name specified in the account definition. If the account has an empty username, such as the default anonymous ''@'%' proxy account described in "LDAP Authentication with Proxy", clients may connect to the MySQL server using a different username. But the principle is the same: if the authentication string starts with +, the plugin uses the username and authentication string sent by the client to construct the user DN.

LDAP authentication method

The LDAP authentication plugin uses configurable authentication methods. Appropriate system variables and available method selections are plugin-specific:

● For
the authentication_ldap_simple plug-in: Set the authentication_ldap_simple_auth_method_name system variable to configure the method. The allowed choices are SIMPLE and AD-FOREST.

● For the authentication_ldap_sasl plug-in: Set
the authentication_rdap_sasl_auth_method_name system variable to configure the method. Allowed choices include SCRAM-SHA-1, SCRAM-SHA-256, and GSSAPI. (To determine which SASL LDAP methods are actually available on the host system, check the value of the Authentication_ldap_sasl_supported_methods status variable.)

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

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 this abstract interface. Using GSSAPI, applications authenticate through Kerberos to obtain service credentials, which in turn use these credentials to enable secure access to other services.

One such service is LDAP, which is used by client-side and server-side SASL LDAP authentication plugins.
These plugins use the GSSAPI/Kerberos authentication method when the authentication_ldap_sasl_auth_method_name system variable is set to GSSAPI . In this case, the plugin uses Kerberos for secure communication instead of using LDAP messages directly. The server-side plugin then communicates with the LDAP server to interpret LDAP authentication messages and retrieve LDAP groups.

Support for GSSAPI/Kerberos as LDAP authentication method for MySQL server and client on Linux. It is useful in Linux environments where applications can access LDAP through Microsoft Active Directory with Kerberos enabled by default.

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

● Principal: a named entity, such as a user or server.

● KDC: key distribution center, including AS and TGS:

■ AS: Authentication server; provides the ticket-granting ticket needed to obtain additional tickets

■ TGS: The ticket-granting server; provides additional tickets for Kerberos clients with valid TGT.

● TGT: The ticket-granting ticket; presented to TGS to obtain service tickets for service access

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

● Active Directory includes both servers, and Kerberos authentication is enabled in the Active Directory LDAP server by default.

● OpenLDAP provides an LDAP server, but may require a separate KDC server and additional Kerberos setup.

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

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

Verify availability of Kerberos and LDAP

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

● Active Directory is running on a host named ldap_auth.example.com with IP address 198.51.100.10

● MySQL-related Kerberos authentication and LDAP lookups use the MySQL.LOCAL domain.

● A user named [email protected] has registered with KDC. (In the discussion that follows, this principal name is also associated with the MySQL account that authenticates to the MySQL server using GSSAPI/Kerberos.)

With these assumptions met, the following procedure is followed:

1. Please verify that the Kerberos library is properly installed and configured in the operating system. For example, to configure the MYSQL.LOCAL realm to be used during MYSQL authentication, the /etc/krb5.conf Kerberos configuration file should contain the following:

[realms]
MYSQL.LOCAL = {
kdc = ldap_auth.example.com
admin_server = ldap_auth.example.com
default_domain = MYSQL.LOCAL
}

2. You may need to add an entry to /etc/hosts for the server host:

198.51.100.10 ldap_auth ldap_auth.example.com

3. Check that Kerberos authentication is working:

a. Authenticate to Kerberos using kinit:

kinit [email protected]

This command authenticates for the Kerberos principal named [email protected]. When the command prompts for a password for the principal, enter it. The KDC returns a TGT that is cached on the client for use by other Kerberos-enabled applications.

b. Use klist to check if the TGT was obtained correctly. The output should be similar to this:

klist
Ticket cache: FILE:/tmp/krb5cc_244306
Default principal: [email protected]
Valid starting Expires Service principal
03/23/2021 08:18:33 03/23/2021 18:18:33 krbtgt/[email protected]

4. Check if ldapsearch is working with Kerberos TGT using this command, which is used to search for users in the MYSQL.LOCAL domain:

ldapsearch -h 198.51.100.10 -Y GSSAPI -b "dc=MYSQL,dc=LOCAL"

Configure server-side SASL LDAP authentication plugin for GSSAPI/Kerberos

Assuming the LDAP server is accessible via Kerberos, configure the server-side SASL LDAP authentication plugin to use the GSSAPI/Kerberos authentication method as described previously. The following is an example of plugin-related settings that a server's my.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"

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

● The --plugin-load-add option loads the plugin (adjust the .so suffix of the platform as needed). This option is unnecessary if you previously loaded the plugin with the INSTALL PLUGIN statement.

●
authentication_ldap_sasl_auth_method_name must be set to GSSAPI to use GSSAPI/Kerberos as sasl ldap authentication method.

●
authentication_ldap_sasl_server_host and authentication_ldap_sasl_server_port indicate the IP address and port number of the Active Directory server host used for authentication.

●
authentication_ldap_sasl_bind_root_dn and authentication_ldap_sasl_bind_root_pwd configure the root dn and password for the group search function. This feature is required, but the user may not have search permissions. In this case, it is necessary to provide root DN information:

■ In the DN option value, admin should be the name of an administrative LDAP account with permission to perform user searches.

■ In the Password option value, the password should be the administrator account password.

●
authentication_ldap_sasl_bind_base_dn indicates the base path of user dn to search users in MYSQL.LOCAL domain.

●
authentication_ldap_sasl_user_search_attr specifies the standard Active Directory search attribute, sAMAccountName This attribute is used for searching to match the login name; the attribute value is different from the user DN value.

Create a MySQL account using GSSAPI/Kerberos for LDAP authentication

MySQL authentication is based on users as Kerberos principals using the SASL LDAP authentication plugin and GSSAPI/Kerberos methods. The following discussion uses a principal named [email protected] as this user, which must be registered in several places:

● Kerberos administrators should register usernames as Kerberos principals. This name should include the domain name. The client authenticates via Kerberos using the principal name and password and obtains a TGT.

● The LDAP administrator should register user names in LDAP entries. For example:

uid=bredon,dc=MYSQL,dc=LOCAL

Explanation: In Active Directory (which uses Kerberos as the default authentication method), creating a user will create both a Kerberos principal and an LDAP entry.

● The MySQL DBA should create an account with the Kerberos principal name as the username and authenticate using the SASL LDAP plugin.

It is assumed that Kerberos principals and LDAP entries have been registered by the appropriate service administrators, and that, the MySQL server has been started with the 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.

The following statement creates a proxy user named [email protected] which assumes the permissions of a proxied user named proxy_krb_usr. Other GSSAPI/Kerberos users that should have the same permissions can similarly be created as proxy users for the same proxy user.

-- create proxy account
CREATE USER '[email protected]' 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 '[email protected]';

Observe carefully the reference to the proxy account name in the first CREATE USER statement and the GRANT proxy statement:

● For most MySQL accounts, user and host are separate parts of the account name and are therefore referenced as "'user_name'@'host_name' respectively

● For LDAP Kerberos authentication, the user part of the account name includes the subject domain, so '[email protected]' is referenced as a single value. Since the host part is not given, the MySQL account full name uses the default '%' as the host part: '[email protected]'@'%'

illustrate:

When creating accounts that authenticate using the authentication_ldap_sasl SASL LDAP authentication plugin and GSSAPI/Kerberos authentication methods, the CREATE USER statement includes the realm as part of the username. This is different from creating accounts using the authentication_kerberos Kerberos plugin. For such accounts, the CREATE USER statement does not include the realm as part of the username. Instead, specify the realm as the authentication string in the BY clause.

The proxy account uses the mysql_no_login authentication plugin to prevent clients from using the account to log in directly to the mysql server. Instead, users authenticating using LDAP should use the [email protected] proxy account.

Connect to MySQL server using MySQL account

After setting up a MySQL account using GSSAPI/Kerberos for authentication, clients can use it to connect to the MySQL server. Kerberos authentication can be done before or when the MySQL client program calls:

● Before invoking the MySQL client program, the client user can obtain the TGT from the KDC independently of MySQL. For example, a client user can authenticate to Kerberos using kinit by providing a Kerberos principal name and principal password:

kinit [email protected]
Password for [email protected]: (enter password here)

The resulting TGT is cached and made available to other Kerberos-enabled applications, such as those using client-side SASL LDAP authentication plugins. In this case, the MySQL client program uses the TGT to authenticate to the MySQL server, so calling the client without specifying a username or password:

mysql --default-auth=authentication_ldap_sasl_client

As mentioned before, the username and password options are not required in the client command when caching the TGT. If the command still contains them, they are handled as follows:

■ If the command contains a username, authentication will fail if that name does not match the principal name in the TGT.

■ If the command contains a password, the Client Plug-in ignores it. Because authentication is based on TGT, it can succeed even if the password provided by the user is incorrect. Therefore, the plugin produces a warning if a valid TGT is found that causes the password to be ignored.

● If the Kerberos cache does not contain a TGT, the client-side SASL LDAP authentication plugin itself can obtain a TGT from the KDC. Invoke the client with the name and password options of the Kerberos principal associated with the MySQL account (enter the command on a single line, followed by the principal password when prompted):

mysql --default-auth=authentication_ldap_sasl_client [email protected] --password

• Authentication fails if the Kerberos cache does not contain a TGT and the client command does not specify a principal name as the username.

If you're not sure if a TGT exists, you can use klist to check.

Authentication looks like this:

1. Client authenticates using Kerberos using TGT.

2. The server finds the principal's LDAP entry and uses it to authenticate the [email protected] MySQL proxy account.

3. The group mapping information ('#krb_grp=proxied_krb_user') in the proxy account authentication string indicates that the authenticated proxy user should be proxyed_krb_user.

4. [email protected] is regarded as the proxy of proxyed_krb_user, and the following query returns the output, as shown in the figure:

SELECT USER(), CURRENT_USER(), @@proxy_user;
+------------------------------+--------------------+--------------------------+
| USER() | CURRENT_USER() | @@proxy_user |
+------------------------------+--------------------+--------------------------+
| [email protected]@localhost | proxied_krb_user@% | '[email protected]'@'%' |
+------------------------------+--------------------+--------------------------+

The USER() value indicates the username used for client commands ([email protected]) and the host computer (localhost) from which the client connects.

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 represents the full name of the account used to connect to the MySQL server, which consists of the [email protected] user part and the % host part.

This indicates that the proxy passes [email protected] to the proxy user account, and [email protected] gets the permissions granted to the proxyed_krb_user proxied user account.

Once a TGT is obtained, it is cached on the client side and can be used until it expires without specifying the password again. Once a TGT is obtained, client plugins use it to obtain service tickets and communicate with server-side plugins.

illustrate

Client users may not wish to reuse a TGT when the client authentication plugin itself obtains the TGT. A local /etc/krb5.conf file can be used to make client plugins destroy TGTs when they are in use.

Server-side plugins do not have access to the TGT itself or the Kerberos password used to obtain the TGT.

LDAP authentication plugins have no control over the caching mechanism (stored in local files, memory, etc.), but Kerberos utilities such as kswitch may be available for this purpose.

Client Configuration Parameters for LDAP Authentication

authentication_ldap_sasl_client Client SASL LDAP plugin to read local /etc/krb5.conf file. An error occurs if this file is missing or inaccessible. Assuming the file is accessible, it can include an optional [appdefaults] section to provide information used by the plugin. Put the info in the mysql section of that section. For example:

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

The client plugin recognizes these parameters in the mysql section:

● The ldap_server_host value specifies the LDAP server host, which may be useful when the host is different from the KDC server host specified in the [realms] section. By default, the plugin uses the KDC server host as the LDAP server host.

● The ldap_destroy_tgt value indicates whether the client plug-in destroys the TGT after obtaining and using it. By default, ldap_destroy_tgt is false, but can be set to true to avoid TGT reuse. (This setting only applies to TGTs created by client plugins, not TGTs created by other plugins or external to MySQL)

LDAP search reference

An LDAP server can be configured to delegate LDAP searches to another LDAP server, a feature known as an LDAP referral. Suppose server a.example.com has a root DN of "dc=example,dc=com" and wishes to delegate searches to another server b.example.com. To enable this feature, a.example.com would be configured with a named reference object with the following properties:

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

One problem with enabling LDAP referrals is that when the search base DN is the root DN and the referral object is not set, the search may fail with an LDAP operation error. MySQL DBAs may wish to avoid such referral errors with LDAP authentication plugins, even though LDAP referrals may be set globally in the LDAP.conf configuration file. To configure on a plugin-specific basis whether the LDAP server should use LDAP referrals when communicating with each plugin, set the
authentication_ldap_simple_referral and authentication_ldap_sasl_referral system variables. Setting a variable to ON or OFF causes the corresponding LDAP authentication plugin to tell the LDAP server whether to use referrals during MySQL authentication. Each variable has plugin-specific effects and does not affect other applications communicating with the LDAP server. Both variables are turned off by default