2.5.3 Authentication Support

For connections to the server made using the legacy JDBC API (that is, not made using X DevAPI or X DevAPI for C), Connector/C++ supports different client-side authentication plugins and authentication methods for:

LDAP Authentication

LDAP authentication enables Connector/C++ (8.0.22 and later) application programs to connect to MySQL servers using simple LDAP authentication, or SASL LDAP authentication using the SCRAM-SHA-1 authentication method. LDAP authentication requires use of a server from a MySQL Enterprise Edition distribution. For more information about the LDAP authentication plugins, see LDAP Pluggable Authentication.

Connector/C++ binary distributions include the libraries that provide the client-side LDAP authentication plugins, as well as any dependent libraries required by the plugins.

Note

In Connector/C++ 8.0.23, a dependency on the mysql-client-plugins package was removed. This package now is required only on hosts where Connector/C++ applications make connections using commercial MySQL server accounts with LDAP authentication. In that case, additional libraries must also be installed: cyrus-sasl-scram for installations that use RPM packages and libsasl2-modules-gssapi-mit for installations that use Debian packages. These SASL packages provide the support required to use the SCRAM-SHA-256 and GSSAPI/Kerberos authentication methods for LDAP.

If Connector/C++ was installed from a compressed tar file or Zip archive, the application program will need to set the OPT_PLUGIN_DIR connection option to the appropriate directory so that the bundled plugin library can be found. (Alternatively, copy the required plugin library to the default directory expected by the client library.)

For example:

sql::ConnectOptionsMap connection_properties;
// To use simple LDAP authentication ...
connection_properties["userName"] = "simple_ldap_user_name";
connection_properties["password"] = "simple_ldap_password";
connection_properties[OPT_ENABLE_CLEARTEXT_PLUGIN]=true;
// To use SASL LDAP authentication using SCRAM-SHA-1 ...
connection_properties["userName"] = "sasl_ldap_user_name";
connection_properties["password"] = "sasl_ldap_scram_password";
// Needed if Connector/C++ was installed from tar file or Zip archive ...
connection_properties[OPT_PLUGIN_DIR] = "${INSTALL_DIR}/lib{64}/plugin";
auto *driver = get_driver_instance();
auto *con = driver->connect(connection_properties);
// Execute statements ...
con->close();

Kerberos Authentication

Kerberos authentication enables Connector/C++ application programs to establish 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. This capability is available on client hosts running Linux (starting with 8.0.26) and Windows (starting with 8.0.27).

Note

This implementation of Kerberos authentication does not support MIT Kerberos on any platform.

It is possible to connect to Kerberos-authenticated accounts without giving a user name under these conditions:

  • The user has a Kerberos principal name assigned, a MySQL Kerberos account for that principal name exists, and the user has the required tickets.

  • The default authentication method must be set to the authentication_kerberos_client client-side authentication plugin using the OPT_DEFAULT_AUTH connection option.

It is possible to connect without giving a password, provided that the user has the required tickets in the Kerberos cache (for example, created by kinit or a similar command).

If the required tickets are not present in the Kerberos cache and a password was given, Connector/C++ obtains the tickets from Kerberos using that password. If the required tickets are found in the cache, any password given is ignored and the connection might succeed even if the password is incorrect.

For more information about Kerberos authentication, see Kerberos Pluggable Authentication.

OCI Authentication

OCI authentication enables Connector/C++ application programs to make connections without passwords for accounts that use the authentication_oci server-side authentication plugin, provided that the correct configuration entries are available to map to one unique user in a specific Oracle Cloud Infrastructure tenancy. This supported was added in the Connector/C++ 8.0.27 release.

To ensure correct account mapping, the client-side Oracle Cloud Infrastructure configuration must contain a fingerprint of the API key to use for authentication (fingerprint entry) and the location of a PEM file with the private part of the API key (key_file entry). Both entries should be specified in the [DEFAULT] profile of the configuration file.

Unless an alternative path to the configuration file is specified with the OPT_OCI_CONFIG_FILE connection option, the following default locations are used:

  • ~/.oci/config on Linux or Posix host types

  • %HOMEDRIVE%%HOMEPATH%/.oci/config on Windows host types

If the MySQL user name is not provided as a connection option, then the operating system user name is substituted. Specifically, if the private key and correct Oracle Cloud Infrastructure configuration are present on the client side, then a connection can be made without giving any options.

Multifactor Authentication

Starting with Connector/C++ 8.0.28, applications can establish connections using multifactor authentication, such that up to three passwords can be specified at connect time. The OPT_PASSWORD1, OPT_PASSWORD2, and OPT_PASSWORD3 connection options are available for specifying the first, second, and third multifactor authentication passwords, respectively.

OPT_PASSWORD1 is an alias for the existing OPT_PASSWORD option; if both are provided, OPT_PASSWORD is ignored. For more information about this authentication option, see Multifactor Authentication.

FIDO Authentication

FIDO authentication to MySQL Server using devices such as smart cards, security keys, and biometric readers. This authentication method is based on the Fast Identity Online (FIDO) standard. To ensure client applications using the legacy JBDC API are notified when a user is expected to interact with the FIDO device, Connector/C++ 8.0.29 (and later) implements a new setCallback() method in the MySQL_Driver class that accepts a single callback argument named Fido_Callback.

class Fido_Callback
{
public:
  Fido_Callback(std::function<void(SQLString)>);
  /**
  * Override this message to receive Fido Action Requests
  */
  virtual void FidoActionRequested(sql::SQLString msg);
};

Any connection created by the driver can use the callback, if needed. However, if an application does not set the callback explicitly, libmysqlclient determines the behavior by default, which involves printing a message to standard output.

Note

On Windows, the client application must run as administrator. The is a requirement of the fido2.dll library, which is used by the authentication_fido plugin.

A client application has two options for obtaining a callback from the connector:

  • By passing a function or lambda to Fido_Callback.

    driver->setCallBack(Fido_Callback([](SQLString msg) {...}));
  • By implementing the virtual method FidoActionRequested.

    class MyWindow : public Fido_Callback
    {
      void FidoActionRequested(sql::SQLString msg) override;
    };
    MyWindow window;
    driver->setCallBack(window);

Setting a new callback always removes the previous callback. To disable the active callback and restore the default behavior, pass nullptr as a function callback. Example:

driver->setCallBack(Fido_Callback(nullptr));

For more information about FIDO authentication, see FIDO Pluggable Authentication.