MySQL :: MySQL Shell 9.1 :: 4.3.5 Using LDAP and Kerberos Authentication

Simple LDAP Authentication

MySQL and LDAP work together to fetch user, credential, and group information. For an overview of the simple LDAP authentication process, see How LDAP Authentication of MySQL Users Works. To use simple LDAP authentication with MySQL Shell, the following conditions must be satisfied:

A user account must be created on the MySQL server that is set up to communicate with the LDAP server. The MySQL user must be identified with the authentication_ldap_simple server-side plugin and optionally the LDAP user distinguished name (DN). For example:
```
CREATE USER 'admin'@'localhost'
   IDENTIFIED WITH authentication_ldap_simple 
   BY 'uid=admin,ou=People,dc=my-domain,dc=com';
```
The BY clause in this example indicates which LDAP entry the MySQL account authenticates against. Specific attributes of the DN may vary depending on the LDAP server.
MySQL Shell uses the client-side mysql_clear_password plugin, which sends the password to the server as cleartext. No password hashing or encryption is used, so a secure connection (using SSL or sockets) between the MySQL Shell and server is required. For more information, see Section 4.3.4, “Using Encrypted Connections” or Section 4.3.3, “Connecting using Unix Sockets and Windows Named Pipes”.
To minimize the security risk, the mysql_clear_password plugin must be enabled explicitly by setting the value of the --auth-method command-line option to clear_text_password on a secure connection. For example, the following command permits you to establish a global session for the user created in the previous example:
```
$> mysqlsh admin@localhost:3308 --auth-method=clear_text_password
Please provide the password for 'admin@localhost:3308': admin_password (admin LDAP password)
```
Note

You can also set the environment variable, LIBMYSQL_ENABLE_CLEARTEXT_PLUGIN, and enable the mysql_clear_password plugin for all client connections. However, this method is inherently insecure and is not recommended for any scenario other than testing. For more information, see Client-Side Cleartext Pluggable Authentication.

SASL-Based LDAP Authentication

MySQL Server is able to accept connections from users defined outside the MySQL grant tables in LDAP directories. The client-side and server-side SASL LDAP plugins use SASL messages for secure transmission of credentials within the LDAP protocol (see Using LDAP Pluggable Authentication).

For SASL-based authentication, the MySQL user must be identified with the authentication_ldap_sasl server-side plugin and optionally an LDAP entry the MySQL account authenticates against. For example:

CREATE USER 'sammy'@'localhost' 
   IDENTIFIED WITH authentication_ldap_sasl
   BY 'uid=sammy_ldap,ou=People,dc=my-domain,dc=com';

The authentication_ldap_sasl_client client-side plugin ships with the MySQL Server packages rather than being built into the libmysqlclient client library. MySQL Shell provides the persistent connection option shell.options.mysqlPluginDir that enables you to define where the required plugin is located. Alternatively, you can override the persistent setting by specifying a path with the non-persistent command-line option --mysql-plugin-dir. For example, the following command permits you to establish a global session on a Linux host for the user created in the previous example:

$> mysqlsh sammy@localhost:3308 --mysql-plugin-dir="/usr/local/mysql/lib/plugin"
Please provide the password for 'sammy@localhost:3308': sammy_password (sammy_ldap LDAP password)

For additional usage examples, see LDAP Authentication with Proxying and LDAP Authentication Group Preference and Mapping Specification.

GSSAPI/Kerberos Authentication Through LDAP SASL

MySQL Shell also supports Kerberos authentication through LDAP SASL. Using the Generic Security Service Application Program Interface (GSSAPI) security abstraction interface, a connection of this type authenticates to Kerberos to obtain service credentials, then uses those credentials in turn to enable secure access to other services. GSSAPI/Kerberos is supported as an LDAP authentication method for MySQL servers and MySQL Shell on Linux only.

A GSSAPI library and Kerberos services must be available to MySQL Server for the connection to succeed. See The GSSAPI/Kerberos Authentication Method for server-side configuration information.

The following general example creates proxy user named lucy@MYSQL.LOCAL that assumes the privileges of the proxied user named proxied_krb_usr. It presumes the realm domain MYSQL.LOCAL is configured in the /etc/krb5.conf Kerberos configuration file.

Note

The user part of the account name includes the principal domain, so 'lucy@MYSQL.LOCAL' is quoted as a single value for LDAP Kerberos authentication.

CREATE USER 'lucy@MYSQL.LOCAL' 
   IDENTIFIED WITH authentication_ldap_sasl 
   BY '#krb_grp=proxied_krb_user';
CREATE USER 'proxied_krb_user';
GRANT ALL PRIVILEGES ON my_db.* TO 'proxied_krb_user';
GRANT PROXY on 'proxied_krb_user' TO 'lucy@MYSQL.LOCAL';

The following command permits you to establish a global session on a Linux host for the user created in the previous example. You must specify the location of the server's plugin directory, either as the persistent shell.options.mysqlPluginDir connection option or as a non-persistent command option, for example:

$> mysqlsh lucy%40MYSQL.LOCAL:password@localhost:3308/my_db 
--mysql-plugin-dir="/usr/local/mysql/lib/plugin"

In this example, percent encoding (%40) replaces the reserved @ character in the principal name and password is the value set for the MySQL Server variable authentication_ldap_sasl_bind_root_pwd. For the list of server variables related to Kerberos authentication through LDAP SASL, see Configure the Server-Side SASL LDAP Authentication Plugin for GSSAPI/Kerberos.

Prior to invoking MySQL Shell, you can obtain and cache a ticket-granting ticket from the key distribution center independently of MySQL. In this case, invoke MySQL Shell without specifying a user-name or password option:

$> mysqlsh localhost:3308/my_db --auth-method=authentication_ldap_sasl_client 
--mysql-plugin-dir="/usr/local/mysql/lib/plugin"

Specifying the --auth-method=authentication_ldap_sasl_client option is mandatory when user credentials are omitted.

Kerberos Authentication

MySQL Shell is capable of establishing connections for accounts that use the authentication_kerberos server-side authentication plugin, provided that the correct Kerberos tickets are available or can be obtained from Kerberos. As of MySQL Enterprise Edition 8.0.27, that capability is available on hosts running Linux and Windows (version 8.0.26 supports Linux only). For detailed setup information, see Kerberos Pluggable Authentication.

Kerberos authentication can combine the user name (for example, lucy) and the realm domain specified in the user account (for example, MYSQL.LOCAL) to construct the user principal name (UPN), such as lucy@MYSQL.LOCAL. To create a MySQL account that corresponds to the UPN lucy@MYSQL.LOCAL, use this statement:

CREATE USER 'lucy' 
   IDENTIFIED WITH authentication_kerberos 
   BY 'MYSQL.LOCAL';

The client-side plugin uses the UPN and password to obtain a ticket-granting ticket (TGT), uses the TGT to obtain a MySQL service ticket (ST), and uses the ST to authenticate to the MySQL server.

The following command permits you to establish a global session on a Linux host for the user created in the previous example. You must specify the location of the server's plugin directory, either as the persistent shell.options.mysqlPluginDir connection option or as a non-persistent command option, for example:

$> mysqlsh lucy:3308 --mysql-plugin-dir="/usr/local/mysql/lib/plugin"
Please provide the password for 'lucy@localhost:3308': UPN_password

Prior to invoking MySQL Shell, you can obtain and cache a TGT from the key distribution center independently of MySQL. In this case, invoke MySQL Shell without specifying a user-name or password option:

$> mysqlsh localhost:3308 --auth-method=authentication_kerberos_client
--mysql-plugin-dir="/usr/local/mysql/lib/plugin"

Specifying the --auth-method=authentication_kerberos_client option is mandatory when user credentials are omitted.

On Microsoft Windows platforms, you can define the Kerberos client mode, SSPI or GSSAPI, using the plugin-authentication-kerberos-client-mode connection option. This option is available in the following formats:

Command-line option: --plugin-authentication-kerberos-client-mode=SSPI | GSSAPI
Connection query option: user@host:port?plugin-authentication-kerberos-client-mode=SSPI | GSSAPI

URI dictionary option: plugin-authentication-kerberos-client-mode': 'SSPI' | 'GSSAPI', for example:

 shell.connect({'user': 'mysql', 'auth-method':'authentication_kerberos_client', 'host': '127.0.0.1', 
                'password': 'mysqlpa$$w0rd', 'plugin-authentication-kerberos-client-mode': 'GSSAPI', 
                'scheme': 'mysql'});

You can also specify plugin-authentication-kerberos-client-mode in the config file. If it is present in the config file, it is used as the default.

If plugin-authentication-kerberos-client-mode is not defined, SSPI is used by default.

When connecting to a MySQL server using Kerberos authentication, the authentication modes have the following behavior:

GSSAPI:
- If a password is not provided, the authentication ticket is retrieved from the MIT Kerberos cache. If a valid ticket cannot be found, the connection fails.
- If a password is provided, the authentication ticket is retrieved from the Kerberos server and stored in the MIT Kerberos cache.
- If an account name is not provided, the Windows user name is used as the MySQL account name.
SSPI:
- If a password is not provided, the Windows single-sign-on ticket is used.
- If a password is provided, the authentication ticket is stored in temporary, in-memory storage.