Skip to content
logo
Percona Server for MySQL
Using LDAP authentication plugins
Initializing search
    percona/psmysql-docs
    percona/psmysql-docs
    • Home
      • Release notes index
      • Percona Server for MySQL 8.0.32-24 (2023-03-20)
      • Percona Server for MySQL 8.0.31-23 (2023-02-09)
        • Percona Server for MySQL 8.0.30-22 Update (2022-11-21)
        • Percona Server for MySQL 8.0.30-22 (2022-11-21)
        • Percona Server for MySQL 8.0.29-21 (2022-08-08)
        • Percona Server for MySQL 8.0.28-20 (2022-06-20)
        • Percona Server for MySQL 8.0.28-19 (2022-05-12)
        • Percona Server for MySQL 8.0.27-18 (2022-03-02)
        • Percona Server for MySQL 8.0.26-17 (2022-01-26)
        • Percona Server for MySQL 8.0.26-16 (2021-10-20)
        • Percona Server for MySQL 8.0.25-15 (2021-07-13)
        • Percona Server for MySQL 8.0.23-14 (2021-05-12)
        • Percona Server for MySQL 8.0.22-13 (2020-12-14)
        • Percona Server for MySQL 8.0.21-12 (2020-10-13)
        • Percona Server for MySQL 8.0.20-11 (2020-07-21)
        • Percona Server for MySQL 8.0.19-10 (2020-03-23)
        • Percona Server for MySQL 8.0.18-9
        • Percona Server for MySQL 8.0.17-8
        • Percona Server for MySQL 8.0.16-7
        • Percona Server for MySQL 8.0.15-6
        • Percona Server for MySQL 8.0.15-5
        • Percona Server for MySQL 8.0.14
        • Percona Server for MySQL 8.0.13-4
        • Percona Server for MySQL 8.0.13-3
        • Percona Server for MySQL 8.0.12-2rc1
      • Limiting the disk space used by binary log files
      • Extended mysqlbinlog
      • Slow query log rotation and expiration
      • Extended SELECT INTO OUTFILE/DUMPFILE
      • Support for PROXY protocol
      • SEQUENCE_TABLE(n) function
      • Trigger updates
      • Expanded fast index creation
      • Kill idle transactions
      • Percona Toolkit UDFs
      • Utility user
      • The ProcFS plugin
      • Adaptive network buffers
      • Thread pool
      • Quickstart overview
      • Install Percona Server for MySQL from repositories
        • Use APT repositories
        • Files in DEB package
        • Build APT packages
        • Downloaded DEB packages
        • Apt pinning
        • Run Percona Server for MySQL
        • Uninstall
        • Use RPM repositories
        • Files in RPM package
        • Downloaded RPM packages
        • Run Percona Server for MySQL
        • Uninstall
        • Install with binary tarballs
        • Binary tarballs available
        • Install Percona Server for MySQL from a source tarball
        • Compile Percona Server for MySQL 8.0 from source
        • Install using Docker
        • Docker environment variables
      • Upgrade guide
      • Upgrade using the Percona repositories
      • Upgrade from systems that use the MyRocks or TokuDB storage engine and partitioned tables
      • Upgrade using Standalone Packages
      • Downgrade
      • Binary logs and replication improvements
      • Post-installation
      • Working with AppArmor
      • Working with SELinux
      • Extended SHOW GRANTS
        • Backup locks
        • Extended mysqldump
        • Start transaction with consistent snapshot
        • Using LDAP authentication plugins
          • Version specific information
          • Plugin names and file names
          • How does the authentication work
          • Prerequisites for authentication
          • Install the plugins
            • Load the plugins at server start
            • Load the plugins at runtime
          • Create a user using simple LDAP authentication
          • Create a user using SASL-based LDAP authentication
          • Examples
            • Uninstall the plugins
        • LDAP authentication plugin system variables
      • Data masking
      • PAM authentication plugin
      • SSL improvements
      • Server variables
      • FIDO authentication plugin
      • Encryption functions
        • Data at Rest Encryption
        • Use the keyring component or keyring plugin
          • Using the Key Management Interoperability Protocol (KMIP)
          • Use the Amazon Key Management Service (AWS KMS)
          • Encrypt File-Per-Table Tablespace
          • Encrypt schema or general tablespace
          • Encrypt system tablespace
          • Encrypt temporary files
          • Encrypt Binary Log Files and Relay Log Files
          • Encrypting the Redo Log data
          • Encrypt the undo tablespace
          • Rotate the master key
          • Advanced encryption key rotation
          • Encrypt doublewrite buffers
          • Verify the encryption for tables, tablespaces, and schemas
      • Manage group replication flow control
      • Group replication system variables
      • Audit log plugin
      • Jemalloc memory allocation profiling
      • User statistics
      • Slow query log
      • Process list
      • Misc. INFORMATION_SCHEMA tables
      • Use Percona Monitoring and Management (PMM) Advisors
      • Too many connections warning
      • Handle corrupted tables
      • Thread based profiling
      • Stacktrace
      • Libcoredumper
        • The Percona XtraDB storage engine
        • Improved MEMORY storage engine
        • Improved InnoDB I/O scalability
        • Enforcing storage engine
        • Extended show engine InnoDB status
        • Show storage engines
        • Compressed columns with dictionaries
        • InnoDB full-text search improvements
        • XtraDB changed page tracking
        • XtraDB performance improvements for I/O-bound highly-concurrent workloads
        • Multiple page asynchronous I/O requests
        • Prefix index queries optimization
        • Limit the estimation of records in a Query
        • InnoDB page fragmentation counters
        • Percona MyRocks introduction
        • Percona MyRocks installation guide
        • Updated supported features
        • MyRocks limitations
        • Differences between Percona MyRocks and Facebook MyRocks
        • MyRocks Information Schema tables
        • MyRocks server variables
        • MyRocks status variables
        • Gap locks detection
        • Data loading
        • Installing and configuring Percona Server for MySQL with ZenFS support
        • TokuDB introduction
        • TokuDB installation
        • Use TokuDB
        • Fast updates with TokuDB
        • TokuDB files and file types
        • TokuDB file management
        • TokuDB background ANALYZE TABLE
        • TokuDB variables
        • TokuDB status variables
        • TokuDB fractal tree indexing
        • TokuDB troubleshooting
        • TokuDB Performance Schema integration
        • Frequently asked questions
        • Migrate and removing the TokuDB storage engine
        • Percona TokuBackup
      • List of variables introduced in Percona Server for MySQL 8.0
      • List of features available in Percona Server for MySQL releases
      • Percona Server for MySQL feature comparison
      • Understand version numbers
      • Development of Percona Server for MySQL
      • Trademark policy
      • Index of INFORMATION_SCHEMA tables
      • Frequently asked questions
      • Copyright and licensing information
      • Glossary

    • Version specific information
    • Plugin names and file names
    • How does the authentication work
    • Prerequisites for authentication
    • Install the plugins
      • Load the plugins at server start
      • Load the plugins at runtime
    • Create a user using simple LDAP authentication
    • Create a user using SASL-based LDAP authentication
    • Examples
      • Uninstall the plugins

    Using LDAP authentication plugins¶

    LDAP (Lightweight Directory Access Protocol) provides an alternative method to access existing directory servers, which maintain information about individuals, groups, and organizations.

    Version specific information¶

    Percona Server for MySQL 8.0.30-22 implements an SASL-based LDAP authentication plugin. This plugin only supports the SCRAM-SHA-1 SASL mechanism.

    Important

    This feature is a tech preview. Before using this feature in production, we recommend that you test restoring production from physical backups in your environment, and also use the alternative backup method for redundancy.

    Percona Server for MySQL 8.0.19-10 implements the simple LDAP authentication. The Percona simple LDAP authentication plugin is a free and Open Source implementation of the MySQL Enterprise Simple LDAP authentication plugin.

    Plugin names and file names¶

    The following tables show the plugin names and the file name for simple LDAP authentication and SASL-based LDAP authentication.

    Plugin or file Plugin name or file name
    Server-side plugin authentication_ldap_simple
    client-side plugin mysql_clear_password
    library file authentication_ldap_simple.so
    Plugin or file Plugin name or file name
    Server-side plugin authentication_ldap_sasl
    client-side plugin authentication_ldap_sasl_client
    library files authentication_ldap_sasl.so
    authentication_ldap_sasl_client.so

    How does the authentication work¶

    The server-side LDAP plugins work only with the specific client-side plugin:

    • The authentication_ldap_simple plugin, on the server, performs the simple LDAP authentication. The client, using mysql_clear_password, connects to the server. The client plugin sends the password to the server as cleartext. For this method, use a secure connection between the client and server.

    • The authentication_ldap_sasl plugin, on the server, performs the SASL-based LDAP authentication. The client must use the authentication_ldap_sasl_client plugin. The method does not send the password to the server in cleartext. The server-side and client-side plugins use Simple Authentication and Security Layer (SASL) to send secure messages within the LDAP protocol.

    For either method, the database server rejects the connection if the client user name and the host name do not match a server account.

    If a database server LDAP authentication is successful, the LDAP server searches for an entry. The LDAP server matches the user and authenticates using the LDAP password. If the database server account names the LDAP user distinguished name (DN), added by the IDENTIFIED WITH <plugin-name> BY '<auth-string>' clause, the LDAP server uses that value and the LDAP password provided by the client. This method fails if the DN and password have incorrect values

    If the LDAP server finds multiple matches or no match, authentication fails.

    If the password is correct, and the LDAP server finds a match, then LDAP authentication succeeds. The LDAP server returns the LDAP entry and the authentication plugin determines the authenticated user’s name based on the entry. If the LDAP entry has no group attribute, the plugin returns the client user name as the authenticated name. If the LDAP entry has a group attribute, the plugin returns the group value as the authenticated name.

    The database server compares the client user name to the authenticated user name. If these names are the same, the database server uses the client user name to check for privileges. If the name differs, then the database server looks for an account that matches the authenticated name.

    Prerequisites for authentication¶

    The LDAP authentication plugins required the following:

    • An available LDAP server

    • The LDAP server must contain the LDAP user accounts to be authenticated

    • The OpenLDAP client library must be available on the same system as the plugin

    The SASL-based LDAP authentication additionally requires the following:

    • Configure the LDAP server to communicate with a SASL server

    • Available SASL client library on the same system as the client plugin.

    • Services are configured to use the supported SCRAM-SHA-1 SASL mechanism

    Install the plugins¶

    You can use either of the following methods to install the plugins.

    The SASL-based LDAP authentication is available on Percona Server for MySQL 8.0.30-22 and later.

    Load the plugins at server start¶

    Use either of the following methods to load the plugin at server start.

    Add the following statements to your my.cnf file to load simple LDAP authentication:

    [mysqld]
    plugin-load-add=authentication_ldap_simple.so
    authentication_ldap_simple_server_host=127.0.0.1
    authentication_ldap_simple_bind_base_dn='dc=percona, dc=com'
    

    Restart the server for the changes to take effect.

    Add the following statements to your my.cnf file to load the SASL-based LDAP authentication:

    [mysqld]
    plugin-load-add=authentication_ldap_sasl.so
    authentication_ldap_sasl_server_host=127.0.0.1
    authentication_ldap_sasl_bind_base_dn='dc=percona, dc=com'
    

    Load the plugins at runtime¶

    Install the plugin with the following statements.

    mysql> INSTALL PLUGIN authentication_ldap_simple SONAME 'authentication_ldap_simple.so';
    

    To set and persist values at runtime, use the following statements:

    mysql> SET PERSIST authentication_ldap_simple_server_host='127.0.0.1';
    mysql> SET PERSIST authentication_ldap_simple_bind_base_dn='dc=percona, dc=com';
    
    mysql> INSTALL PLUGIN authentication_ldap_sasl SONAME 'authentication_ldap_sasl.so`;
    

    To set and persist values at runtime, use the following statements:

    mysql> SET PERSIST authentication_ldap_sasl_server_host='127.0.0.1';
    mysql> SET PERSIST authentication_ldap_sasl_bind_base_dn='dc=percona, dc=com';
    

    Create a user using simple LDAP authentication¶

    There are several methods to add or modify a user.

    In the CREATE USER statement or the ALTER USER statement, for simple LDAP authentication, you can specify the authentication_ldap_simple plugin in the IDENTIFIED WITH clause:

    mysql> CREATE USER ... IDENTIFIED WITH authentication_ldap_simple;
    

    Using the IDENTIFIED WITH clause, the database server assigns the specified plugin.

    If you provide the optional authentication string clause, ‘cn,ou,dc,dc’ in the example, the string is stored along with the password.

    mysql> CREATE USER ... IDENTIFIED WITH authentication_ldap_simple BY 'cn=[user name],ou=[organization unit],dc=[domain component],dc=com'
    

    Unless the authentication_ldap_simple_group_role_mapping variable is used, creating a user with an authentication string does not use the following system variables:

    • authentication_ldap_simple_bind_base_dn

    • authentication_ldap_simple_bind_root_dn

    • authentication_ldap_simple_bind_root_pwd

    • authentication_ldap_simple_user_search_attr

    • authentication_ldap_simple_group_search_attr

    Creating the user with IDENTIFIED BY authentication_ldap_simple uses the variables.

    Creating the user with the authentication_ldap_simple_group_role_mapping variable also adds the authentication_ldap_simple_bind_root_dn and authentication_ldap_simple_bind_root_pwd variables.

    Create a user using SASL-based LDAP authentication¶

    There are several methods to add or modify a user.

    For SASL-based LDAP authentication, in the CREATE USER statement or the ALTER USER statement, you can specify the authentication_ldap_sasl plugin:

    mysql> CREATE USER ... IDENTIFIED WITH authentication_ldap_sasl;
    

    If you provide the optional authentication string clause, ‘cn,ou,dc,dc’ in the example, the string is stored along with the password.

    mysql> CREATE USER ... IDENTIFIED WITH authentication_ldap_sasl BY 'cn=[user name],ou=[organization unit],dc=[domain component],dc=com'
    

    Unless the authentication_ldap_sasl_group_role_mapping variable is used, creating a user with an authentication string does not use the following system variables:

    • authentication_ldap_sasl_bind_base_dn

    • authentication_ldap_sasl_bind_root_dn

    • authentication_ldap_sasl_bind_root_pwd

    • authentication_ldap_sasl_user_search_attr

    • authentication_ldap_sasl_group_search_attr

    Creating the user with IDENTIFIED BY authentication_ldap_sasl uses the variables.

    Creating the user with the authentication_ldap_sasl_group_role_mapping variable also adds theauthentication_ldap_sasl_bind_root_dn and authentication_ldap_sasl_bind_root_pwd variables.

    Examples¶

    The following sections are examples of using simple LDAP authentication and SASL-based LDAP authentication.

    For the purposes of this example, we use the following LDAP user:

    uid=ldapuser,ou=testusers,dc=percona,dc=com
    

    The following example configures an LDAP user and connects to the database server.

    Create a database server account for ldapuser with the following statement:

    mysql> CREATE USER 'ldapuser'@'localhost' IDENTIFIED WITH authentication_ldap_simple BY 'uid=ldapuser,ou=testusers,dc=percona,dc=com';
    

    The authentication string does not include the LDAP password. This password must be provided by the client user when they connect.

    mysql> mysql --user=ldapuser --password --enable-cleartext-plugin
    

    The user enters the ldapuser password. The client sends the password as cleartext, which is necessary when using a server-side LDAP library without SASL. The following actions may minimize the risk:

    • Require that the database server clients explicitly enable the mysql_clear_password plugin with --enable-cleartext-plugin.
    • Require that the database server clients connect to the database server using an encrypted connection

    The following example configures an LDAP user and connect to the database server.

    Create a database server account for ldapuser with the following statement:

    mysql> CREATE USER 'ldapuser'@'localhost' IDENTIFIED WITH authentication_ldap_sasl AS 'uid=ldapuser,ou=testusers,dc=percona,dc=com';
    

    The authentication string does not include the LDAP password. This password must be provided by the client user when they connect.

    Clients connect ot the database server by providing the database server user name and LDAP password:

    mysql> mysql --user=ldapuser --password
    

    The authentication is similar to the authentication method used by simple LDAP authentication, except that the client and the database server SASL LDAP plugins use SASL messages. These messages are secure within the LDAP protocol.

    Uninstall the plugins¶

    If you installed either plugin at server startup, remove those options from the my.cnf file, remove any startup options that set LDAP system variables, and restart the server.

    If you installed the plugins at runtime, run the following statements:

    mysql> UNINSTALL PLUGIN authentication_ldap_simple;
    

    If you used SET_PERSIST, use RESET PERSIST to remove the settings.

    If you installed the plugins at runtime, run the following statements:

    mysql> UNINSTALL PLUGIN authentication_ldap_sasl;
    

    If you used SET_PERSIST, use RESET PERSIST to remove the settings.

    Contact us

    For free technical help, visit the Percona Community Forum.

    To report bugs or submit feature requests, open a JIRA ticket.

    For paid support and managed or consulting services , contact Percona Sales.


    Last update: 2023-01-12
    Percona LLC and/or its affiliates, © 2023
    Made with Material for MkDocs

    Cookie consent

    We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better.