Documentation Home
MySQL Connector/NET Developer Guide
Related Documentation Download this Manual
PDF (US Ltr) - 1.3Mb
PDF (A4) - 1.3Mb


MySQL Connector/NET Developer Guide  /  Connector/NET Connections  /  Connector/NET Authentication

4.4 Connector/NET Authentication

MySQL Connector/NET implements a variety of authentication plugins that MySQL Server can invoke to authenticate a user. Pluggable authentication enables the server to determine which plugin applies, based on the user name and host name that your application passes to the server when making a connection. For a complete description of the authentication process, see Pluggable Authentication.

Connector/NET provides the following authentication plugins and methods:

  • mysql_native_password

    Supported for all versions of Connector/NET.

  • sha256_password

    Minimum version: Connector/NET 8.0.11

    Supported for both classic MySQL protocol and X Protocol connections. For additional information on using the MYSQL41 mechanism with X Protocol, see the Auth connection option.

  • caching_sha2_password

    Minimum version: Connector/NET 8.0.11 for classic MySQL protocol connections only.

  • authentication_windows_client

    MySQL Connector/NET applications can authenticate to a MySQL server using the Windows Native Authentication Plugin. Users who have logged in to Windows can connect from MySQL client programs to the server based on the information in their environment without specifying an additional password. The interface matches the MySql.Data.MySqlClient object. To enable, pass in Integrated Security to the connection string with a value of yes or sspi.

    Passing in a user ID is optional. When Windows authentication is set up, a MySQL user is created and configured to be used by Windows authentication. By default, this user ID is named auth_windows, but can be defined using a different name. If the default name is used, then passing the user ID to the connection string from Connector/NET is optional, because it will use the auth_windows user. Otherwise, the name must be passed to the connection string using the standard user ID element.

    Supported for all versions of Connector/NET.

  • authentication_oci_client

    Minimum version: Connector/NET 8.0.27 for classic MySQL protocol connections only.

    Connector/NET supports Oracle Cloud Infrastructure pluggable authentication, which enables .NET applications to access MySQL Database Services in a secure way without using passwords. This pluggable authentication is not supported for .NET Framework 4.5.x implementations.

    Prerequisites for this type of connection include access to a tenancy, a Compute instance, a MySQL DB System attached to a private network, and properly configured groups, compartments, and policies. An Oracle Cloud Infrastructure administrator can provide the basic setup for MySQL user accounts.

    In addition, the MySQL DB System must have the server-side authentication plugin installed and loaded before a connection can be attempted. Connector/NET implements the client-side authentication plugin.

    During authentication, the client-side plugin locates the user’s Oracle Cloud Infrastructure configuration file from which it obtains a signing key file. The location of the configuration file can be specified with the ociConfigFile connection option; otherwise, the default location is used. Connector/NET then signs a token it receives from the server, uses the token to create the SHA256 RSA signature that it returns to the server, and waits for the success or failure of the authentication process.

    Potential error conditions include:

    • Private key could not be found at location given by OCI configuration entry 'key_file'.

      Connector/NET could not find the private key at the specified location.

    • OCI configuration entry 'key_file' does not reference a valid key file.

      Connector/NET was unable to load or use the specified private key.

    • OCI configuration file does not contain a 'fingerprint' or 'key_file' entry.

      The configuration file is missing the fingerprint entry, the key_file entry, or both.

    • OCI configuration file could not be read

      Connector/NET could not find or load the configuration file. Be sure the ociConfigFile value matches the location of the file.

    • The OCI SDK cannot be found or is not installed

      Connector/NET could not load the Oracle Cloud Infrastructure SDK library at run time.

    Connector/NET references the OCI.DotNetSDK.Common NuGet package in the Oracle Cloud Infrastructure SDK library to read configuration-file entry values and this package must be available.

    Tip

    To manage the size of your .NET project, include only the required package for authentication rather than the full set of packages in the library.

    For specific details about usage and support, see SDK and CLI Configuration File.

  • authentication_kerberos_client

    Applications and MySQL servers are able use the Kerberos authentication protocol to authenticate MySQL user accounts and services. With the authentication_kerberos_client plugin, both the user and the server are able to verify each other's identity. No passwords are ever sent over the network and Kerberos protocol messages are protected against eavesdropping and replay attacks. The server-side plugin is supported only on Linux.

    Note

    The Defaultauthenticationplugin connection-string option is mandatory for supporting userless and passwordless Kerberos authentications (see Options for Classic MySQL Protocol Only).

    The availability of and the requirements for enabling Kerberos authentication differ by host type. Connector/NET does not provide Kerberos authentication for .NET applications running on macOS. Applications running on Linux and Windows participate in Kerberos authentication based on the following interfaces:

    • Generic Security Service Application Program Interface (GSSAPI) for Linux

      Minimum version: Connector/NET 8.0.26 for classic MySQL protocol connections. Supported on Linux only.

      MIT Kerberos must be installed on each client system to enable authentication of request tickets for Connector/NET by a MySQL server. The libgssapi_krb5.so.2 library for Linux is required. For an overview of the connection process, see Connection Commands for Linux Clients.

    • Security Support Provider Interface (SSPI) for Windows

      Minimum version: Connector/NET 8.0.27 for classic MySQL protocol connections. Supported on Windows only.

      Connector/NET uses SSPI/Kerberos for authentication. On Windows, SSPI implements GSSAPI. The behavioral differences between SSPI and GSSAPI include:

      • Configuration.  Windows clients do not use any external libraries or Kerberos configuration. For example, on Linux you can set the ticket-granting ticket (TGT) expiry time, key distribution center (KDC) port, and so on. On Windows, you cannot set any of these options.

      • TGT tickets caching.  If you provide a user name and password for authentication, the obtained tickets are not stored in the cache. New tickets are obtained every time.

      • Userless and passwordless authentication.  Windows logged-in user name and credentials are used. Windows client must be part of the Active Directory domain of the server for a successful login.

      For an overview of the connection process, see Connection Commands for Windows Clients.

  • authentication_ldap_sasl_client

    SASL-based LDAP authentication for Connector/NET requires the Enterprise Edition of MySQL and the authentication protocol applies to applications running on Linux, Windows (partial support), but not macOS.

    Minimum version:

    • Connector/NET 8.0.22 (SCRAM-SHA-1) on Linux and Windows.

    • Connector/NET 8.0.23 (SCRAM-SHA-256) for classic MySQL protocol only on Linux and Windows.

    • Connector/NET 8.0.24 (GSSAPI) for classic MySQL protocol only on Linux only.

      MIT Kerberos must be installed on each client system to enable authentication of request tickets for Connector/NET by a MySQL server. The authentication_ldap_sasl plugin must be configured to use the GSSAPI mechanism and the application user must be identified as follows:

      IDENTIFIED WITH 'authentication_ldap_sasl'

      The libgssapi_krb5.so.2 library for Linux is required.

  • mysql_clear_password

    Minimum version: Connector/NET 8.0.22 for classic MySQL protocol only.

    Requires a secure connection to the server, which is satisfied by either condition at the client:

    • The SslMode connection option has a value other than None (Preferred by default).

    • The ConnectionProtocol connection option is set to unix for Unix domain sockets.