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).

On Windows (starting with 8.0.32), the OPT_AUTHENTICATION_KERBEROS_CLIENT_MODE connection option can be set to either SSPI (default) or GSSAPI. The option permits choosing between SSPI and GSSAPI at runtime for the authentication_kerberos_client authentication plugin on Windows. Connector/C++ implements GSSAPI mode through the MIT kerberos library and this mode is compatible with the Java SE security tools (for example, klist and kinit commands) on Windows. In this mode, the ticket search on Windows hosts is restricted to the MIT Kerberos cache only. If the cache has no ticket, the connection fails even if the Windows ticket is valid

Previously, Connector/C++ supported Kerberos authentication through the Windows SSPI Kerberos library only (starting with 8.0.27). SSPI is not capable of acquiring cached credentials that were generated using the kinit command. In SSPI mode, the Windows single sign-on ticket is used for authentication if the client user provides no password and the authentication method considers the Windows ticket exclusively. If the ticket is missing or invalid, the connection fails even if the Kerberos cache contains a valid ticket. For more information, see Commands for Windows Clients in SSPI Mode.

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 on Linux or the MIT Kerberos cache on Windows (for example, created by kinit or a similar command).

Note

The SSPI Kerberos library is not compatible with Java SE security tools. To use the kinit command, the client application must set the OPT_AUTHENTICATION_KERBEROS_CLIENT_MODE connection option to GSSAPI.

If the required tickets are not present in the Kerberos cache (or the MIT 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.

On client hosts running Windows, you can override the default location of the MIT Kerberos configuration file by setting the KRB5_CONFIG environment variable and the default MIT Kerberos credential cache name with the KRB5CCNAME environment variable (for example, KRB5CCNAME=DIR:/mydir/).

For details about using the MIT Kerberos configuration and cache, see:

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.