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

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_file is 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.

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.

WebAuthn (FIDO) 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.

Note

Connector/C++ 8.0.29 added authentication_fido support, deprecated it in 8.2.0 in favor of authentication_webauthn, and removed authentication_fido support in 8.4.0. For backward-compatibility, the Fido_Callback callback argument remains but it invokes WebAuthn authentication.