The driver supports Microsoft Entra ID (Entra ID) authentication (formerly known as Azure Active Directory authentication). Entra ID authentication is an alternative to SQL Server Authentication that allows administrators to centrally manage user permissions to Azure SQL Database data stores. The driver supports the following methods of Entra ID authentication:

  • User and password authentication: The driver authenticates using your Entra ID user name and password.
  • Service principal user authentication: The driver authenticates using the object (principal) ID of the logical server and the client secret of your Azure application.
  • Managed identity authentication: The driver authenticates using a system-assigned or user-assigned managed identity. Managed identities are a type of service principal that can be used only with Azure resources for which they are granted permissions. Using managed identities to authenticate provides an alternative to using credentials, and they can be used anywhere Entra ID authentication is supported.
When Entra ID authentication is enabled, all communications with the Azure SQL Database service are encrypted.

User and password authentication

To use user and password authentication with Entra ID:

  • Specify values for minimum required options for establishing a connection:
    • Set the Host Name (HostName) option to specify either the IP address in IPv4 or IPv6 format, or the server name for your Azure server. For example, your_server.database.windows.net.
    • Set the Port Number (PortNumber) option to specify the TCP port of the primary database server that is listening for connections to the database.
    • Set Database (Database) option to specify the name of the database to which you want to connect.
    • If using data sources, set the Data Source Name (DataSourceName) to specify the name of your data source.
  • Set the Authentication Method (AuthenticationMethod) option to 13 (Active Directory Password).
  • Set the Trust Store (Truststore) connection option to specify the absolute path of the digital certificate file for the root CA certificates. The driver requires these certificates to maintain a secure connection.
    Note: For testing purposes, you can disable the truststore requirement by setting the Validate Server Certificate (ValidateServerCertificate) to 0 (disabled). Disabling the Validate Server Certificate option leaves your connection vulnerable to man-in-the-middle attacks; therefore, it is not recommended for extended use.
  • Set the Host Name In Certificate (HostNameInCertificate) option to specify the host name for TLS/SSL certificate validation. For example, *.database.windows.net.
  • Set the User Name (LogonID) option to specify your Entra ID username using the userid@domain.com format.
  • Set the Password (Password) option to specify your Entra ID password.
For example, the following is a DSN-less connection string with only the required options for making a connection using Entra ID authentication with user name and password: 
DRIVER={DataDirect 8.0 SQL Server Wire Protocol};AuthenticationMethod=13;
Database=MyDB;HostName=myserver.database.windows.net;
HostNameInCertificate=*.database.windows;PortNumber=1433;
TrustStore=\<truststore_path>\ca-bundle.crt;ValidateServerCertificate=1;
LogonID=test@domain.com;Password=secret;

The following example demonstrates a data source definition in the odbc.ini file with only the required options for making a connection using Entra ID authentication with user name and password:

[SQLServer Wire Protocol]
Driver=ODBCHOME/lib/ivsqls28.so
Description=DataDirect 8.0 SQL Server Wire Protocol
AuthenticationMethod=13
Database=MyDB
HostName=myserver.database.windows.net
HostNameInCertificate=*.database.windows
LogonID=test@domain.com
Password=secret
PortNumber=1433
TrustStore=/<truststore_path>/ca-bundle.crt
ValidateServerCertificate=1

Service principal user authentication

To use service principal user authentication with Entra ID:

  • Specify values for minimum required options for establishing a connection:
    • Set the Host Name (HostName) option to specify either the IP address in IPv4 or IPv6 format, or the server name for your Azure server. For example, your_server.database.windows.net.
    • Set the Port Number (PortNumber) option to specify the TCP port of the primary database server that is listening for connections to the database.
    • Set the Database (Database) option to specify the name of the database to which you want to connect.
    • If using data sources, set the Data Source Name (DataSourceName) to specify the name of your data source.
  • Set the Authentication Method (AuthenticationMethod) option to specify a value of 36 (Active Directory Service Principal).
  • Set the Trust Store (Truststore) connection option to specify the absolute path of the digital certificate file for the root CA certificates. The driver requires these certificates to maintain a secure connection.
  • Set the Host Name In Certificate (HostNameInCertificate) option to specify the host name for TLS/SSL certificate validation. For example, *.database.windows.net.
  • Set the User Name (LogonID) option to specify the object (principal) ID of the Azure SQL logical server.
  • Set the Password (Password) property to specify the client secret for your Entra ID application.
Note: For testing purposes, you can disable the Truststore and Host Name In Certificate requirement by setting the Validate Server Certificate (ValidateServerCertificate) to 0 (disabled). Disabling the Validate Server Certificate option leaves your connection vulnerable to man-in-the-middle attacks; therefore, it is not recommended for extended use.
For example, the following is a DSN-less connection string with only the required options for making a connection using principal ID authentication: 
DRIVER={DataDirect 8.0 SQL Server Wire Protocol};AuthenticationMethod=36;
        Database=MyDB;HostName=myserver.database.windows.net;
        HostNameInCertificate=*.database.windows;PortNumber=1433;
        TrustStore=\<truststore_path>\ca-bundle.crt;
        LogonID=1234ABCD-1234-ABCD-1234-abcd1234ABCD1234;
        Password=ABcdEFg/hiJkLmNOPqR01stUvWxyzYx2wvUTsrQpO=;

The following example demonstrates a data source definition in the odbc.ini file with only the required options for making a connection using principal ID authentication:

[SQL Server Wire Protocol]
Driver=ODBCHOME/lib/ivsqls28.so
Description=DataDirect 8.0 SQL Server Wire Protocol
...
AuthenticationMethod=36
...
Database=MyDB
...
HostName=myserver.database.windows.net
...
HostNameInCertificate=*.database.windows
...
LogonID=1234ABCD-1234-ABCD-1234-abcd1234ABCD1234
...
Password=ABcdEFg/hiJkLmNOPqR01stUvWxyzYx2wvUTsrQpO=
...
PortNumber=1433
...
TrustStore=/<truststore_path>/ca-bundle.crt
...

Managed identity authentication

To use managed identity authentication with Entra ID:

  • Specify values for minimum required options for establishing a connection:
    • Set the Host Name (HostName) option to specify either the IP address in IPv4 or IPv6 format, or the server name for your Azure server. For example, your_server.database.windows.net.
    • Set the Port Number (PortNumber) option to specify the TCP port of the primary database server that is listening for connections to the database.
    • Set the Database (Database) option to specify the name of the database to which you want to connect.
    • If using data sources, set the Data Source Name (DataSourceName) to specify the name of your data source.
  • Set the Authentication Method (AuthenticationMethod) option to specify a value of 37 (Active Directory Managed Identity).
  • Set the Trust Store (Truststore) option to specify the absolute path of the digital certificate file for the root CA certificates. The driver requires these certificates to maintain a secure connection.
    Note: For testing purposes, you can disable the truststore requirement by setting the Validate Server Certificate (ValidateServerCertificate) to 0 (disabled). Disabling the Validate Server Certificate option leaves your connection vulnerable to man-in-the-middle attacks; therefore, it is not recommended for extended use.
  • Set the Host Name In Certificate (HostNameInCertificate) option to specify the host name for TLS/SSL certificate validation. For example, *.database.windows.net.
  • (For user-assigned identities only) Set the User Name (LogonID) option to specify the client ID of your user-assigned managed identity used for authentication.
    Note: This value is required only if you have multiple user-assigned identities. If you have only one user-assigned identity, the driver will connect without specifying a value for this option.
For example, the following is a DSN-less connection string with only the required options for authenticating with a user-defined managed identity: 
DRIVER={DataDirect 8.0 SQL Server Wire Protocol};AuthenticationMethod=37;
          Database=MyDB;HostName=myserver.database.windows.net;
          HostNameInCertificate=*.database.windows;PortNumber=1433;
          TrustStore=\<truststore_path>\ca-bundle.crt;
          LogonID=1234ABCD-1234-ABCD-1234-abcd1234ABCD1234;

The following example demonstrates a data source definition in the odbc.ini file with only the required options for authenticating with a user-defined managed identities:

[SQLServer Wire Protocol]
Driver=ODBCHOME/lib/ivsqls28.so
Description=DataDirect 8.0 SQL Server Wire Protocol
...
AuthenticationMethod=37
...
Database=MyDB
...
HostName=myserver.database.windows.net
...
HostNameInCertificate=*.database.windows
...
LogonID=1234ABCD-1234-ABCD-1234-abcd1234ABCD1234
...
PortNumber=1433
...
TrustStore=/<truststore_path>/ca-bundle.crt
...