MySQL Connector/C++ Release Notes
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 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 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_clientclient-side authentication plugin using theOPT_DEFAULT_AUTHconnection 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 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. In Connector/C++ 8.0.33, the
OPT_OCI_CLIENT_CONFIG_PROFILE connection
option permits selecting a profile in the configuration file to
use for authentication. By default, the value of
OPT_OCI_CLIENT_CONFIG_PROFILE is the
[DEFAULT] profile.
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/configon Linux or Posix host types%HOMEDRIVE%%HOMEPATH%/.oci/configon 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.
To support Oracle Cloud Infrastructure ephemeral key-based authentication, Connector/C++
8.0.33 (and later) obtains the location of the token file from
the security_token_file entry. For example:
[DEFAULT]
fingerprint=59:8a:0b[...]
key_file=~/.oci/sessions/DEFAULT/oci_api_key.pem
tenancy=ocid1.tenancy.oc1.[...]
region=us-ashburn-1
security_token_file=~/.oci/sessions/DEFAULT/token
Connector/C++ sends to the server a JSON attribute (named
"token") with the value extracted from the
security_token_file field. If the target file
referenced in the profile does not exist, or if the file exceeds
a specified maximum value, then Connector/C++ terminates the action and
returns an exception with the cause.
Connector/C++ sends an empty token value in the JSON payload if:
The security-token file is empty.
The configuration option
security_token_fileis found but the value in the configuration file is empty.
In all other cases, Connector/C++ adds the content of the security-token file intact to the JSON document.
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.
WebAuthn authentication to MySQL Server supports using devices
such as web browsers, smart cards, security keys, and biometric
readers. WebAuthn authentication supports both the FIDO and
FIDO2 standards. To ensure client applications using the legacy
JBDC API are notified when a user is expected to interact with
the FIDO/FIDO2 device, Connector/C++ 8.2.0 (and later) adds a callback
argument named WebAuthn_Callback to the
setCallback() method in the
MySQL_Driver class. The
WebAuthn_Callback class has a callback method
named ActionRequested().
class WebAuthn_Callback
{
public:
WebAuthn_Callback(std::function<void(SQLString)>);
/**
* Override this message to receive WebAuthn Action Requests
*/
virtual void ActionRequested(sql::SQLString msg);
};
Set the WebAuthn_Callback callback explicitly
for authentication to accounts that use WebAuthn authentication.
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_webauthn plugin.
A client application has two options for obtaining a callback from the connector:
-
By passing a function or lambda to
WebAuthn_Callback.driver->setCallBack(WebAuthn_Callback([](SQLString msg) {...})); -
By implementing the virtual method
ActionRequested.class MyWindow : public WebAuthn_Callback { void ActionRequested(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(WebAuthn_Callback(nullptr));For more information about WebAuthn authentication, see WebAuthn Pluggable Authentication.