MySQL :: MySQL Connector/NET Developer Guide :: 4.4 Connector/NET Authentication

authentication_kerberos_client

For general information, see Kerberos Pluggable Authentication.

Applications and MySQL servers are able use the Kerberos authentication protocol to authenticate MySQL Enterprise Edition 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. On Windows, the Kerberos mode can be set using the KerberosAuthMode connection option (see Section 4.5, “Connector/NET Connection Options Reference”).

Applications running on Linux and Windows participate in Kerberos authentication based on the following interfaces:

Generic Security Service Application Program Interface (GSSAPI)
Minimum version:
- Connector/NET 8.0.26 for classic MySQL protocol connections. Supported on Linux only.
- Connector/NET 8.0.32 for classic MySQL protocol connections through the MIT Kerberos library. Supported on Windows 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. On Windows, use the KRB5_CONFIG and KRB5CCNAME environment variables to specify configuration and cache locations when using GSSAPI through the MIT Kerberos library.
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, with GSSAPI you can set the ticket-granting ticket (TGT) expiry time, key distribution center (KDC) port, and so on. With SSPI, you cannot set any of these options.
- TGT tickets caching. If you provide a user name and password for authentication in SSPI mode, those credentials can be obtained from the Windows in-memory cache, but the obtained tickets are not stored in the Kerberos cache. New tickets are obtained every time.
- Userless and passwordless authentication. In SSPI mode, 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 in SPPI Mode.

authentication_ldap_sasl_client

For general information, see LDAP Pluggable Authentication.

SASL-based LDAP authentication requires MySQL Enterprise Edition and can be used to establish classic MySQL protocol connections only. This 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) on Linux and Windows.
Connector/NET 8.0.24 (GSSAPI) 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.

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 HeatWave Service 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 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 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 client 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. In Connector/NET 8.0.33, the OciConfigProfile connection option permits selecting a profile in the configuration file to use for authentication. 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.

To support Oracle Cloud Infrastructure ephemeral key-based authentication, Connector/NET 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/NET 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/NET terminates the action and returns an exception with the cause.

Connector/NET 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/NET adds the content of the security-token file intact to the JSON document.

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_openid_connect_client

MySQL Enterprise Edition supports authentication to MySQL Server 9.1.0 (and higher) using OpenID Connect Authentication. This authentication method uses a pair of plugins, authentication_openid_connect on the server side and authentication_openid_connect_client on the client side.

Connector/NET requires an Identity Token that is passed to the OpenidIdentityToken connection option. By default, Connector/NET uses the operating system's login username if one is not specified in the connection string or while creating the MySqlConnection object.

IdentityToken = "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIi........."

var connStringBuilder = new MySqlConnectionStringBuilder()
{
    UserID = "openid-testuser",
    Server = Settings.Server,
    Port = Settings.Port,
    OpenIdIdentityToken = IdentityToken,
    DefaultAuthenticationPlugin = "authentication_openid_connect_client"
};
 
using (MySqlConnection conn = new MySqlConnection(connStringBuilder.ConnectionString))
{
    // 
}

authentication_webauthn_client

For general information, see WebAuthn Pluggable Authentication.

MySQL Enterprise Edition supports authentication to MySQL Server 8.2.0 (and higher) using devices such as smart cards, security keys, and biometric readers. This authentication method is based on the FIDO and FIDO2 standards, and uses a pair of plugins, authentication_webauthn on the server side and authentication_webauthn_client on the client side. Connector/NET 8.2.0 supports the client-side WebAuthn authentication plugin.

The WebAuthn authentication method can be used directly for one-factor authentication (1FA) or combined with existing MySQL authentication methods to support accounts that use 2FA or 3FA. Connector/NET provides a callback mechanism to notify the application that the user is expected to interact with the FIDO/FIDO2 device through its authenticator. For example:

public void OpenConnection()
{
    using(var connection = new MySQLConnection("host=foo; .. "))
      connection.WebAuthnActionRequested += WebAuthnActionRequested;
      connection.Open();
      // ...
}

public void WebAuthnActionRequested() 
{
    Console.WriteLine("Please insert WebAuthn device and perform gesture action for authentication to complete.");
}

If the following requirements are satisfied, Connector/NET notifies the application that it is expecting user interaction with the FIDO/FIDO2 device:

The FIDO/FIDO2 device must be registered for the specific authentication factor associated with each user account.
The application, Connector/NET, and the FIDO/FIDO2 device must be available on the same host or within a trusted network.
On Windows, the application must run as administrator to access the required libfido2 library, which must be present on the client.

The authentication process terminates after a reasonable time interval has elapsed without user-device interaction.

Note

The related authentication_fido_client plugin and FidoActionCallback callback (both added in Connector/NET 8.0.29) were removed in Connector/NET 8.4.0 in favor of using WebAuthn authentication.

authentication_windows_client

Supported for all versions of Connector/NET. For general information, see Windows Pluggable Authentication.

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.

caching_sha2_password

Minimum version: Connector/NET 8.0.11 for classic MySQL protocol connections only. For general information, see Caching SHA-2 Pluggable Authentication.

mysql_clear_password

Minimum version: Connector/NET 8.0.22 for classic MySQL protocol connections only. For general information, see Client-Side Cleartext Pluggable Authentication.

mysql_clear_password 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 Disabled or None (deprecated in Connector/NET 8.0.29). The value is set to Preferred by default.
The ConnectionProtocol connection option is set to unix for Unix domain sockets.

mysql_native_password

Supported for all versions of Connector/NET to establish classic MySQL protocol and X Protocol connections. For general information, see Native Pluggable Authentication.

Note

The mysql_native_password plugin is disabled by default as of MySQL Server 8.4.0 and removed as of MySQL Server 9.0.0.

sha256_password

Minimum version: Connector/NET 8.0.11 for classic MySQL protocol connections or X Protocol connections with the MYSQL41 mechanism (see the Auth connection option). For general information, see SHA-256 Pluggable Authentication.

Note

The sha256_password plugin is deprecated as of MySQL Server 8.0.16 and subject to removal in a future version.