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 the Entra ID user and password.
  • Service principal user authentication: The driver retrieves an access token by authenticating using the principal id of the logical server and the client secret of your Entra ID 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.
Note: When using Entra ID authentication, the driver requires root CA certificates to establish an SSL connection to a database. The driver determines the location of the truststore containing the required certificates by using the default JRE cacerts file unless a different file has been specified by the javax.net.ssl.trustStore Java system property. The truststore location cannot be specified using the driver's Truststore property.

User and password authentication

To use user and password authentication with Entra ID:

  • Set the AuthenticationMethod property to specify a value of ActiveDirectoryPassword.
  • Set the User property to specify your Entra ID username using the userid@domain.com format.
  • Set the Password property to specify your Entra ID password.
  • Specify values for minimum required properties for establishing a connection.
    • Set the ServerName property to specify either the IP address in IPv4 or IPv6 format, or the server name for your Azure server. For example, myserver.database.windows.net.
    • Set the PortNumber property to specify the TCP port of the primary database server that is listening for connections to the database.

For example, the following is a connection string with only the required options for making a connection using Entra ID authentication.

Note: If the HostNameInCertificate is not specified, the driver automatically uses the value of the ServerName from the URL as the value for validating the certificate.
Connection conn = DriverManager.getConnection 
("jdbc:datadirect:sqlserver://your_server.database.windows:1433;
AuthenticationMethod=ActiveDirectoryPassword;
User=test@mydomain.com;Password=secret");

Service principal user authentication

To use service principal user authentication with Entra ID:

  • Set the AuthenticationMethod property to specify a value of ActiveDirectoryServicePrincipal.
  • Set the ActiveDirectoryPrincipalID property to specify the Entra ID Identity (PrincipalID) of the Azure SQL logical server.
  • Set the ActiveDirectoryPrincipalSecret property to specify the client secret for your Entra ID application.
  • Specify values for minimum required properties for establishing a connection.
    • Set the ServerName property to specify either the IP address in IPv4 or IPv6 format, or the server name for your Entra ID server. For example, myserver.database.windows.net.
    • Set the PortNumber property to specify the TCP port of the primary database server that is listening for connections to the database.
Note: If the HostNameInCertificate is not specified, the driver automatically uses the value of the ServerName from the URL as the value for validating the certificate.

For example, the following is a connection string with only the required options for making a connection using Entra ID authentication.

Connection conn = DriverManager.getConnection 
        ("jdbc:datadirect:sqlserver://your_server.database.windows:1433;
        AuthenticationMethod=ActiveDirectoryServicePrincipal;
        ActiveDirectoryPrincipalID=789f8b4c-7a4a-445d-6oe9-7bec14625645;
        ActiveDirectoryPrincipalSecret=ABcdEFg/hiJkLmNOPqR01stUvWxyzYx2wvUTsrQpO=");

Managed identity authentication

The driver supports the following methods of managed identity authentication:
  • User-assigned authentication: The driver authenticates using the client ID of the user assigned managed identity.

    To use user-assigned managed identity authentication with Entra ID:

    • Set the AuthenticationMethod property to the value ActiveDirectoryManagedIdentity.
    • Set the User property to specify your Microsoft Entra ID (Azure) client ID of the user assigned managed identity.
      Note: The User property is optional if only one user-assigned managed identity is configured. This property is required if there are more than one user-assigned managed identities configured.
    • Specify values for minimum required properties for establishing a connection.
      • Set the ServerName property to specify either the IP address in IPv4 or IPv6 format, or the server name for your Entra ID (Azure) server. For example, myserver.database.windows.net.
      • Set the PortNumber property to specify the TCP port of the primary database server that is listening for connections to the database.
    • Optionally, set the DatabaseName property to the database to which you want to connect.

    For example, the following is a connection string with the minimal options for making a connection using managed identity authentication.

    Connection conn = DriverManager.getConnection 
("jdbc:datadirect:sqlserver://your_server.database.windows:1433;DatabaseName=exampleDB;
AuthenticationMethod=ActiveDirectoryManagedIdentity;User=f4f42d67-6789-4d58-a789-83a3dc123456");
  • System-assigned authentication: The driver authenticates using the identity associated with Azure resources like virtual machines.

    To use system-assigned managed identity authentication with Entra ID:

    • Set the AuthenticationMethod property to specify a value of ActiveDirectoryManagedIdentity.
    • Specify values for minimum required properties for establishing a connection.
      • Set the ServerName property to specify either the IP address in IPv4 or IPv6 format, or the server name for your Azure server. For example, myserver.database.windows.net.
      • Set the PortNumber property to specify the TCP port of the primary database server that is listening for connections to the database.
    • Optionally, set the DatabaseName property to the database to which you want to connect.

    For example, the following is a connection string with the minimal options for making a connection using managed identity authentication.

    Connection conn = DriverManager.getConnection 
 ("jdbc:datadirect:sqlserver://your_server.database.windows:1433;DatabaseName=exampleDB;
   AuthenticationMethod=ActiveDirectoryManagedIdentity");