Поделиться через

Подключение с помощью проверки подлинности Microsoft Entra

  • Статья

Скачать драйвер JDBC

В этой статье содержатся сведения о разработке приложений Java, использующих функцию проверки подлинности Microsoft Entra с драйвером Microsoft JDBC для SQL Server.

Проверку подлинности Microsoft Entra можно использовать для подключения к База данных SQL Azure, экземпляру SQL Azure и Azure Synapse Analytics с помощью удостоверений в идентификаторе Microsoft Entra. Используйте проверку подлинности Microsoft Entra для централизованного управления удостоверениями пользователей базы данных и в качестве альтернативы проверке подлинности SQL Server. Драйвер JDBC позволяет указать учетные данные Microsoft Entra в строка подключения JDBC для подключения к SQL Azure. Сведения о настройке проверки подлинности Microsoft Entra см. в статье "Подключение к SQL Azure с помощью проверки подлинности Microsoft Entra".

Свойства подключения для поддержки проверки подлинности Microsoft Entra в драйвере Microsoft JDBC для SQL Server:

  • authentication: с помощью этого свойства можно указать способ проверки подлинности SQL, используемый для подключения. Возможные значения:

    • ActiveDirectoryManagedIdentity

      • Так как драйвер версии 8.3.1 authentication=ActiveDirectoryMSI можно использовать для подключения к База данных SQL Azure/Synapse Analytics из ресурса Azure с поддержкой удостоверений. При необходимости вместе с этим режимом проверки подлинности в свойствах подключения или источника данных можно указать msiClientId. msiClientId должен содержать идентификатор клиента управляемого удостоверения, который будет использоваться для получения маркера доступа для установления соединения. Так как драйвер версии 12.2 authentication=ActiveDirectoryManagedIdentity также можно использовать для подключения к База данных SQL Azure/Synapse Analytics из ресурса Azure с поддержкой удостоверений. При необходимости идентификатор клиента управляемого удостоверения теперь можно задать в свойстве user . Дополнительные сведения см. в разделе "Подключение с помощью режима проверки подлинности ActiveDirectoryManagedIdentity".

    • ActiveDirectoryDefault

      • Так как драйвер версии 12.2 authentication=ActiveDirectoryDefault можно использовать для подключения к AZURE SQL/Synapse Analytics через DefaultAzureCredential из клиентской библиотеки удостоверений Azure. Дополнительные сведения см. в разделе "Подключение с помощью режима проверки подлинности ActiveDirectoryDefault".

    • ActiveDirectoryIntegrated

      • Так как драйвер версии 6.0 authentication=ActiveDirectoryIntegrated можно использовать для подключения к AZURE SQL/Synapse Analytics с помощью интегрированной проверки подлинности. Чтобы использовать этот режим проверки подлинности, необходимо федеративные службы федерации локальная служба Active Directory (ADFS) с идентификатором Microsoft Entra в облаке. После настройки вы можете подключиться, добавив собственную библиотеку mssql-jdbc_auth-<version>-<arch>.dll в путь класса приложения в Windows или настроив билет Kerberos для поддержки кроссплатформенной проверки подлинности. Вы можете получить доступ к Azure SQL/Azure Synapse Analytics, не запрашивая учетные данные при входе на компьютер, присоединенный к домену. Дополнительные сведения см. в разделе "Подключение с помощью режима проверки подлинности ActiveDirectoryIntegrated".

    • ActiveDirectoryPassword

      • Так как драйвер версии 6.0 authentication=ActiveDirectoryPassword можно использовать для подключения к AZURE SQL/Synapse Analytics с помощью имени пользователя и пароля Microsoft Entra. Дополнительные сведения см. в разделе "Подключение с помощью режима проверки подлинности ActiveDirectoryPassword".

    • ActiveDirectoryInteractive

      • Так как драйвер версии 9.2 authentication=ActiveDirectoryInteractive можно использовать для подключения к AZURE SQL/Synapse Analytics с помощью интерактивного потока проверки подлинности (многофакторная проверка подлинности). Дополнительные сведения см. в разделе "Подключение с помощью режима проверки подлинности ActiveDirectoryInteractive".

    • ActiveDirectoryServicePrincipal

      • Так как драйвер версии 9.2 можно использовать для подключения к Azure SQL/Synapse Analytics, authentication=ActiveDirectoryServicePrincipal указав идентификатор приложения или клиента в свойстве userName и секрет удостоверения субъекта-службы в свойстве пароля. Дополнительные сведения см. в разделе "Подключение с помощью режима проверки подлинности ActiveDirectoryServicePrincipal".

    • ActiveDirectoryServicePrincipalCertificate

      • Так как драйвер версии 12.4 можно использовать для подключения к База данных SQL Azure/Synapse Analytics, authentication=ActiveDirectoryServicePrincipalCertificate указав идентификатор приложения или клиента в свойстве userName и расположение сертификата субъекта-службы в свойствеclientCertificate. Дополнительные сведения см. в разделе "Подключение с помощью режима проверки подлинности ActiveDirectoryServicePrincipalCertificate".

    • SqlPassword

      • Используйте authentication=SqlPassword для подключения к SQL Server с помощью свойств userName, user и password.

    • NotSpecified

      • Используйте authentication=NotSpecified или оставьте значение по умолчанию, если ни один из этих методов проверки подлинности не требуется.

    • accessToken: используйте это свойство подключения для установки подключения к Базе данных SQL с помощью токена доступа. accessToken можно задать только с помощью параметра getConnection() Properties метода в классе DriverManager. Его нельзя использовать в URL-адресе подключения.

Дополнительные сведения об установке свойства authentication см. в статье Setting the connection properties (Установка свойств подключения).

Требования к настройке клиента

Помимо основных требований к системе драйверов, следующие режимы проверки подлинности имеют больше требований.

В следующей таблице перечислены необходимые зависимости библиотеки для каждого режима проверки подлинности и версии драйвера. Также требуются зависимости зависимостей.

Примечание.

В случаях, когда исправление для основного выпуска имеет другую версию зависимости, чем ее основной выпуск, также перечислены исправления.

Параметр проверки подлинности Версии драйвера Зависимости библиотеки
ActiveDirectoryPassword
ActiveDirectoryIntegrated		 6,0 Adal4j 1.3.0
ActiveDirectoryPassword
ActiveDirectoryIntegrated		 6.2.2 - 6.4 Adal4j 1.4.0
ActiveDirectoryPassword
ActiveDirectoryIntegrated		 7.0 Adal4j 1.6.0
ActiveDirectoryPassword
ActiveDirectoryIntegrated		 7.2 Adal4j 1.6.3
Client-Runtime-for-AutoRest 1.6.5
ActiveDirectoryPassword
ActiveDirectoryIntegrated		 7.4 - 8.2 Adal4jl4j 1.6.4
Client-Runtime-for-AutoRest 1.7.0
ActiveDirectoryPassword
ActiveDirectoryIntegrated		 8.4 Adal4j 1.6.5
Client-Runtime-for-AutoRest 1.7.4
ActiveDirectoryPassword
ActiveDirectoryIntegrated
ActiveDirectoryInteractive
ActiveDirectoryServicePrincipal		 9,2 msal4j 1.7.1
ActiveDirectoryPassword
ActiveDirectoryIntegrated
ActiveDirectoryInteractive
ActiveDirectoryServicePrincipal		 9,4 msal4j 1.10.1
ActiveDirectoryPassword
ActiveDirectoryIntegrated
ActiveDirectoryInteractive
ActiveDirectoryServicePrincipal		 10.2 msal4j 1.11.0
ActiveDirectoryPassword
ActiveDirectoryIntegrated
ActiveDirectoryInteractive
ActiveDirectoryServicePrincipal		 11.2 msal4j 1.11.3
ActiveDirectoryPassword
ActiveDirectoryIntegrated
ActiveDirectoryInteractive
ActiveDirectoryServicePrincipal		 11.2.3 msal4j 1.13.0
ActiveDirectoryPassword
ActiveDirectoryIntegrated
ActiveDirectoryInteractive
ActiveDirectoryServicePrincipal		 12,2 msal4j 1.13.3
ActiveDirectoryManagedIdentity
ActiveDirectoryMSI
ActiveDirectoryDefault		 12,2 azure-identity 1.7.0
ActiveDirectoryPassword
ActiveDirectoryIntegrated
ActiveDirectoryInteractive
ActiveDirectoryServicePrincipal
ActiveDirectoryServicePrincipalCertificate		 12,4 msal4j 1.13.8
ActiveDirectoryManagedIdentity
ActiveDirectoryMSI
ActiveDirectoryDefault		 12,4 azure-identity 1.9.0
ActiveDirectoryPassword
ActiveDirectoryIntegrated
ActiveDirectoryInteractive
ActiveDirectoryServicePrincipal
ActiveDirectoryServicePrincipalCertificate		 12,6 msal4j 1.14.1
ActiveDirectoryManagedIdentity
ActiveDirectoryMSI
ActiveDirectoryDefault		 12,6 azure-identity 1.11.1
ActiveDirectoryPassword
ActiveDirectoryIntegrated
ActiveDirectoryInteractive
ActiveDirectoryServicePrincipal
ActiveDirectoryServicePrincipalCertificate		 12.6.3 msal4j 1.15.1
ActiveDirectoryManagedIdentity
ActiveDirectoryMSI
ActiveDirectoryDefault		 12.6.3 azure-identity 1.12.2
ActiveDirectoryPassword
ActiveDirectoryIntegrated
ActiveDirectoryInteractive
ActiveDirectoryServicePrincipal
ActiveDirectoryServicePrincipalCertificate		 12.6.4 msal4j 1.15.1
ActiveDirectoryManagedIdentity
ActiveDirectoryMSI
ActiveDirectoryDefault		 12.6.4 azure-identity 1.12.2
ActiveDirectoryPassword
ActiveDirectoryIntegrated
ActiveDirectoryInteractive
ActiveDirectoryServicePrincipal
ActiveDirectoryServicePrincipalCertificate		 12,8 msal4j 1.15.1
ActiveDirectoryManagedIdentity
ActiveDirectoryMSI
ActiveDirectoryDefault		 12,8 azure-identity 1.12.2

Подключение с помощью режима проверки подлинности ActiveDirectoryManagedIdentity

Этот режим проверки подлинности поддерживается начиная с версии 7.2. Чтобы использовать его, укажите authentication=ActiveDirectoryMSI. Начиная с версии 12.2 authentication=ActiveDirectoryManagedIdentity , также можно указать.

Помимо требований зависимостей библиотеки, перечисленных в требованиях к настройке клиента, эта функция имеет следующие требования:

Следующий пример иллюстрирует использование режима authentication=ActiveDirectoryManagedIdentity. Запустите этот пример из ресурса Azure, настроенного для управляемого удостоверения.

Чтобы запустить пример, замените имя сервера или базы данных именем сервера или базы данных в следующих строках:

ds.setServerName("msentra-managed-demo.database.windows.net"); // replace 'msentra-managed-demo' with your server name
ds.setDatabaseName("demo"); // replace with your database name
//Optional
ds.setMSIClientId("<managed_identity_client>"); // Replace with Client ID of user-assigned managed identity to be used

Пример использования ActiveDirectoryMSI режима проверки подлинности:

import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.Statement;

import com.microsoft.sqlserver.jdbc.SQLServerDataSource;

public class MsEntraMSI {
    public static void main(String[] args) throws Exception {

        SQLServerDataSource ds = new SQLServerDataSource();
        ds.setServerName("msentra-managed-demo.database.windows.net"); // Replace with your server name
        ds.setDatabaseName("demo"); // Replace with your database name
        ds.setAuthentication("ActiveDirectoryMSI");
        // Optional
        ds.setMSIClientId("<managed_identity_client_guid>"); // Replace with Client ID of user-assigned managed identity to be used

        try (Connection connection = ds.getConnection();
                Statement stmt = connection.createStatement();
                ResultSet rs = stmt.executeQuery("SELECT SUSER_SNAME()")) {
            if (rs.next()) {
                System.out.println("You have successfully logged on as: " + rs.getString(1));
            }
        }
    }
}

В следующем примере показано, как использовать authentication=ActiveDirectoryManagedIdentity режим.

import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.Statement;

import com.microsoft.sqlserver.jdbc.SQLServerDataSource;

public class MSEntraManagedIdentity {
    public static void main(String[] args) throws Exception {

        SQLServerDataSource ds = new SQLServerDataSource();
        ds.setServerName("msentra-managed-demo.database.windows.net"); // Replace with your server name
        ds.setDatabaseName("demo"); // Replace with your database name
        ds.setAuthentication("ActiveDirectoryManagedIdentity"); // ActiveDirectoryManagedIdentity for JDBC driver version v12.2.0+
        // Optional
        ds.setUser("<managed_identity_client>"); // Replace with Client ID of User-Assigned Managed Identity to be used

        try (Connection connection = ds.getConnection();
                Statement stmt = connection.createStatement();
                ResultSet rs = stmt.executeQuery("SELECT SUSER_SNAME()")) {
            if (rs.next()) {
                System.out.println("You have successfully logged on as: " + rs.getString(1));
            }
        }
    }
}

В этих примерах на виртуальной машине Azure извлекается маркер доступа из управляемого удостоверения, назначенного системой, или управляемого удостоверения пользователя (если msiClientId или user указан идентификатор клиента управляемого удостоверения) и устанавливается подключение с помощью маркера доступа, полученного с помощью маркера доступа. Если подключение установлено, отобразится следующее сообщение:

You have successfully logged on as: <your Managed Identity username>

Подключение с помощью режима проверки подлинности ActiveDirectoryDefault

Параметр ActiveDirectoryDefault проверки подлинности использует прицеленную TokenCredential реализацию клиентской библиотеки DefaultAzureCredential удостоверений Azure. Учетные данные объединяют часто используемые методы проверки подлинности, связанные друг с другом.

ActiveDirectoryDefault Для проверки подлинности требуется зависимость времени выполнения от клиентской библиотеки удостоверений Azure для управляемого удостоверения. Сведения о версии библиотеки см. в разделе "Требования к настройке клиента".

В следующей таблице перечислены цепочки DefaultAzureCredential учетных данных для каждой версии драйвера JDBC.

Версия драйвера Документация по версии azure identity DefaultAzureCredential цепь
12,2 azure-identity 1.7.0 Среда
Управляемое удостоверение
IntelliJ
Azure CLI
Azure PowerShell
12,4 azure-identity 1.9.0 Среда
Удостоверение рабочей нагрузки
Управляемое удостоверение
Azure Developer CLI
IntelliJ
Azure CLI
Azure PowerShell
12,6 azure-identity 1.11.1 Среда
Удостоверение рабочей нагрузки
Управляемое удостоверение
Azure Developer CLI
IntelliJ
Azure CLI
Azure PowerShell
12,8 azure-identity 1.12.2 Среда
Удостоверение рабочей нагрузки
Управляемое удостоверение
Azure Developer CLI
IntelliJ
Azure CLI
Azure PowerShell

Существует множество переменных, которые можно задать для настройки учетных Environment данных. Дополнительные сведения о настройке DefaulAzureCredential цепочки, включая Environment учетные данные, см. в соответствующей версии документации azure-identity, связанной в предыдущей таблице.

Чтобы использовать IntellijCredential его в Windows, задайте переменную INTELLIJ_KEEPASS_PATH среды в расположение keepass файла. Например, INTELLIJ_KEEPASS_PATH=C:\user\your\path\to\the\keepass\file.

Чтобы предоставить больше клиентов DefaultAzureCredentialв переменную среды, используйте ADDITIONALLY_ALLOWED_TENANTS переменную среды. Эта переменная принимает список с разделителями-запятыми. Например: ADDITIONALLY_ALLOWED_TENANTS=<your-tenant-id-0>,<your-tenant-id-1>,<your-tenant-id-2>,...

В следующем примере показано, как использовать authentication=ActiveDirectoryDefault режим с AzureCliCredential в пределах.DefaultAzureCredential

  1. Сначала войдите в Azure CLI с помощью следующей команды.

    az login

  2. После успешного входа в Azure CLI выполните следующий код.

    import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.Statement;

import com.microsoft.sqlserver.jdbc.SQLServerDataSource;

public class MSEntraDefault {
    public static void main(String[] args) throws Exception {

        SQLServerDataSource ds = new SQLServerDataSource();
        ds.setServerName("msentra-managed-demo.database.windows.net"); // Replace with your server name
        ds.setDatabaseName("demo"); // Replace with your database name
        ds.setAuthentication("ActiveDirectoryDefault");

        try (Connection connection = ds.getConnection();
                Statement stmt = connection.createStatement();
                ResultSet rs = stmt.executeQuery("SELECT SUSER_SNAME()")) {
            if (rs.next()) {
                System.out.println("You have successfully logged on as: " + rs.getString(1));
            }
        }
    }
}

Установка подключения с использованием режима проверки подлинности ActiveDirectoryIntegrated

Существует два способа использования ActiveDirectoryIntegrated проверки подлинности в драйвере Microsoft JDBC для SQL Server:

  • В Windows mssql-jdbc_auth-<version>-<arch>.dll скачанный пакет можно скопировать в расположение в системном пути.
  • Если нет возможности использовать библиотеку DLL, то начиная с версии 6.4 можно настроить билет Kerberos. Этот метод поддерживается на разных платформах (Windows, Linux и macOS). Дополнительные сведения см. в разделе Настройка билета Kerberos в Windows, Linux и macOS.

Убедитесь, что у вас есть необходимые зависимые библиотеки от требований к настройке клиента.

Следующий пример иллюстрирует использование режима authentication=ActiveDirectoryIntegrated. В этом примере выполняется компьютер, присоединенный к домену, который федеративный с идентификатором Microsoft Entra. Пользователь базы данных, представляющий пользователя Windows, должен существовать в базе данных и иметь разрешение CONNECT.

Перед выполнением примера замените имена сервера и базы данных именами ваших сервера и базы данных в следующих строках:

ds.setServerName("msentra-managed-demo.database.windows.net"); // replace 'msentra-managed-demo' with your server name
ds.setDatabaseName("demo"); // replace with your database name

Пример использования режима проверки подлинности ActiveDirectoryIntegrated:

import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.Statement;

import com.microsoft.sqlserver.jdbc.SQLServerDataSource;

public class MSEntraIntegrated {
    public static void main(String[] args) throws Exception {

        SQLServerDataSource ds = new SQLServerDataSource();
        ds.setServerName("msentra-managed-demo.database.windows.net"); // Replace with your server name
        ds.setDatabaseName("demo"); // Replace with your database name
        ds.setAuthentication("ActiveDirectoryIntegrated");

        try (Connection connection = ds.getConnection();
                Statement stmt = connection.createStatement();
                ResultSet rs = stmt.executeQuery("SELECT SUSER_SNAME()")) {
            if (rs.next()) {
                System.out.println("You have successfully logged on as: " + rs.getString(1));
            }
        }
    }
}

В этом примере автоматически используется билет Kerberos на клиентской платформе и пароль не требуется. Если подключение установлено, отобразится следующее сообщение:

You have successfully logged on as: <your domain user name>

Настройка билета Kerberos в Windows, Linux и macOS

Вам необходимо настроить билет Kerberos, связывающий текущего пользователя с учетной записью домена Windows. Ниже приведены краткие сведения о ключевых шагах.

Windows

Примечание.

В Windows mssql-jdbc_auth-<version>-<arch>.dll скачанный пакет можно использовать вместо этих шагов конфигурации Kerberos. Эти действия требуется выполнять только в том случае, если нет возможности использовать библиотеку DLL.

JDK поставляется с kinitпакетом управления , с помощью которого можно получить TGT из центра распространения ключей (KDC) на присоединенном к домену компьютере, федеративном с идентификатором Microsoft Entra.

Шаг 1. Получение билета

  • Запуск в: Windows

  • Действие:

    • Выполните команду kinit username@DOMAIN.COMPANY.COM, чтобы получить TGT из KDC, и появится запрос на пароль вашего домена.
    • Выполните команду klist, чтобы просмотреть доступные билеты. Если kinit был успешным, вы должны увидеть билет из krbtgt/DOMAIN.COMPANY.COM@ DOMAIN.COMPANY.COM.

    Примечание.

    Чтобы приложение нашло KDC, может потребоваться указать файл .ini с -Djava.security.krb5.conf.

Linux и macOS

Требования

Доступ к компьютеру, присоединенному к домену Windows, для обращения к контроллеру домена Kerberos.

Шаг 1. Поиск KDC Kerberos

  • Запуск: командная строка Windows

  • Действие: nltest /dsgetdc:DOMAIN.COMPANY.COM (где DOMAIN.COMPANY.COM сопоставляется с именем домена)

  • Образец вывода

    DC: \\co1-red-dc-33.domain.company.com
Address: \\2111:4444:2111:33:1111:ecff:ffff:3333
...
The command completed successfully

  • Информация для извлечения: доменное имя, в данном случае — co1-red-dc-33.domain.company.com.

Шаг 2. Настройка KDC в krb5.conf

  • Запуск: Linux или macOS

  • Действие. Изменение /etc/krb5.conf выбранного редактора. Настройте следующие ключи.

    [libdefaults]
  default_realm = DOMAIN.COMPANY.COM

[realms]
DOMAIN.COMPANY.COM = {
   kdc = co1-red-dc-28.domain.company.com
}

    Затем сохраните krb5.conf файл и закройте его.

    Примечание.

    Домен должен быть указан прописными буквами.

Шаг 3. Тестирование извлечения билета на получение билетов
  • Запуск: Linux или macOS
  • Действие:
    • Выполните команду kinit username@DOMAIN.COMPANY.COM, чтобы получить TGT из KDC, и появится запрос на пароль вашего домена.
    • Выполните команду klist, чтобы просмотреть доступные билеты. Если kinit был успешным, вы должны увидеть билет из krbtgt/DOMAIN.COMPANY.COM@ DOMAIN.COMPANY.COM.

Установка подключения с использованием режима проверки подлинности ActiveDirectoryPassword

Следующий пример иллюстрирует использование режима authentication=ActiveDirectoryPassword.

Сборка и запуск примера

  1. Убедитесь, что у вас есть необходимые зависимые библиотеки от требований к настройке клиента.

  2. Найдите приведенные ниже строки кода и замените имена сервера и базы данных именами своих сервера и базы данных.

    ds.setServerName("msentra-managed-demo.database.windows.net"); // replace 'msentra-managed-demo' with your server name
ds.setDatabaseName("demo"); // replace with your database name

  3. Найдите приведенные ниже строки кода. Замените имя пользователя именем пользователя Microsoft Entra, который вы хотите подключить как.

    ds.setUser("bob@example.com"); // replace with your username
ds.setPassword("password");     // replace with your password

Пример использования ActiveDirectoryPassword режима проверки подлинности:

import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.Statement;

import com.microsoft.sqlserver.jdbc.SQLServerDataSource;

public class MSEntraUserPassword {

    public static void main(String[] args) throws Exception{

        SQLServerDataSource ds = new SQLServerDataSource();
        ds.setServerName("msentra-managed-demo.database.windows.net"); // Replace with your server name
        ds.setDatabaseName("demo"); // Replace with your database
        ds.setUser("bob@example.com"); // Replace with your username
        ds.setPassword("password"); // Replace with your password
        ds.setAuthentication("ActiveDirectoryPassword");

        try (Connection connection = ds.getConnection();
                Statement stmt = connection.createStatement();
                ResultSet rs = stmt.executeQuery("SELECT SUSER_SNAME()")) {
            if (rs.next()) {
                System.out.println("You have successfully logged on as: " + rs.getString(1));
            }
        }
    }
}

Если установлено подключение, вы увидите следующее сообщение в виде выходных данных:

You have successfully logged on as: <your user name>

Установка подключения с использованием режима проверки подлинности ActiveDirectoryInteractive

Следующий пример иллюстрирует использование режима authentication=ActiveDirectoryInteractive.

Сборка и запуск примера

  1. Убедитесь, что у вас есть необходимые зависимые библиотеки от требований к настройке клиента.

  2. Найдите приведенные ниже строки кода и замените имена сервера и базы данных именами своих сервера и базы данных.

    ds.setServerName("msentra-managed-demo.database.windows.net"); // replace 'msentra-managed-demo' with your server name
ds.setDatabaseName("demo"); // replace with your database name

  3. Найдите приведенные ниже строки кода. Замените имя пользователя Microsoft Entra, который вы хотите подключить как.

    ds.setUser("bob@example.com"); // replace with your username

Пример использования ActiveDirectoryInteractive режима проверки подлинности:

import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.Statement;

import com.microsoft.sqlserver.jdbc.SQLServerDataSource;

public class MSEntraInteractive {
    public static void main(String[] args) throws Exception{

        SQLServerDataSource ds = new SQLServerDataSource();
        ds.setServerName("msentra-managed-demo.database.windows.net"); // Replace with your server name
        ds.setDatabaseName("demo"); // Replace with your database
        ds.setAuthentication("ActiveDirectoryInteractive");

        // Optional login hint
        ds.setUser("bob@example.com"); // Replace with your user name

        try (Connection connection = ds.getConnection();
                Statement stmt = connection.createStatement();
                ResultSet rs = stmt.executeQuery("SELECT SUSER_SNAME()")) {
            if (rs.next()) {
                System.out.println("You have successfully logged on as: " + rs.getString(1));
            }
        }
    }
}

При запуске программы отображается окно браузера, в котором выполняется проверка подлинности пользователя. Точно то, что вы видите, зависит от настройки идентификатора Microsoft Entra. Он может включать или не включать многофакторную проверку подлинности для имени пользователя, пароля, ПИН-кода или второй проверки подлинности устройства через телефон. Когда в одной программе выполняется несколько интерактивных запросов проверки подлинности, пользователь может даже не получать последующие запросы, если библиотека проверки подлинности может повторно использовать ранее кэшированный маркер.

Сведения о настройке идентификатора Microsoft Entra для многофакторной проверки подлинности см. в статье "Начало работы с многофакторной проверкой подлинности Microsoft Entra" в облаке.

Снимок экрана этих диалоговых окон см. в разделе "Использование многофакторной проверки подлинности Microsoft Entra".

Если проверка подлинности пользователя успешно завершена, в браузере должно появиться следующее сообщение.

Authentication complete. You can close the browser and return to the application.

Оно означает лишь то, что проверка подлинности пройдена успешно, но необязательно то, что соединение с сервером установлено. Если подключение к серверу установлено, вернувшись в приложение, вы должны увидеть следующее сообщение.

You have successfully logged on as: <your user name>

Установка подключения с использованием режима проверки подлинности ActiveDirectoryServicePrincipal

Следующий пример иллюстрирует использование режима authentication=ActiveDirectoryServicePrincipal.

Сборка и запуск примера

  1. Убедитесь, что у вас есть необходимые зависимые библиотеки от требований к настройке клиента.

  2. Найдите приведенные ниже строки кода и замените имена сервера и базы данных именами своих сервера и базы данных.

    ds.setServerName("msentra-managed-demo.database.windows.net"); // replace 'msentra-managed-demo' with your server name
ds.setDatabaseName("demo"); // replace with your database name

  3. Найдите приведенные ниже строки кода. Замените значение principalId идентификатором приложения или идентификатором клиента субъекта-службы Microsoft Entra, который требуется подключить как. Замените значение principalSecret на секрет.

    String principalId = "<service_principal_guid>"; // Replace with your Microsoft Entra service principal ID.
String principalSecret = "..."; // Replace with your Microsoft Entra principal secret.

  4. Задайте идентификатор субъекта и секрет субъекта с помощью и setPassword в setUser версии 10.2 и выше, а setAADSecurePrincipalId также setAADSecurePrincipalSecret в версии 9.4 и ниже.

Пример использования ActiveDirectoryServicePrincipal режима проверки подлинности:

import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.Statement;

import com.microsoft.sqlserver.jdbc.SQLServerDataSource;

public class MSEntraServicePrincipal {
    public static void main(String[] args) throws Exception{
        String principalId = "<service_principal_guid>"; // Replace with your Microsoft Entra service principal ID.
        String principalSecret = "..."; // Replace with your Microsoft Entra principal secret.

        SQLServerDataSource ds = new SQLServerDataSource();
        ds.setServerName("msentra-managed-demo.database.windows.net"); // Replace with your server name
        ds.setDatabaseName("demo"); // Replace with your database
        ds.setAuthentication("ActiveDirectoryServicePrincipal");
        ds.setUser(principalId); // setAADSecurePrincipalId for JDBC Driver 9.4 and below
        ds.setPassword(principalSecret); // setAADSecurePrincipalSecret for JDBC Driver 9.4 and below 

        try (Connection connection = ds.getConnection();
                Statement stmt = connection.createStatement();
                ResultSet rs = stmt.executeQuery("SELECT SUSER_SNAME()")) {
            if (rs.next()) {
                System.out.println("You have successfully logged on as: " + rs.getString(1));
            }
        }
    }
}

Если подключение установлено успешно, отобразится следующее сообщение.

You have successfully logged on as: <your app/client ID>

Подключение с помощью режима проверки подлинности ActiveDirectoryServicePrincipalCertificate

Следующий пример иллюстрирует использование режима authentication=ActiveDirectoryServicePrincipalCertificate.

Сборка и запуск примера

  1. Убедитесь, что у вас есть необходимые зависимые библиотеки от требований к настройке клиента.

  2. Найдите приведенные ниже строки кода и замените имена сервера и базы данных именами своих сервера и базы данных.

    ds.setServerName("msentra-managed-demo.database.windows.net"); // replace 'msentra-managed-demo' with your server name
ds.setDatabaseName("demo"); // replace with your database name

  3. Найдите приведенные ниже строки кода. Замените значение principalId идентификатором приложения или идентификатором клиента субъекта-службы Microsoft Entra, который требуется подключить как. Замените значение clientCertificate расположения сертификата субъекта-службы.

    String principalId = "<service_principal_guid>"; // Replace with your Microsoft Entra service principal ID.

String clientCertificate = "..."; // Replace with the location for your Microsoft Entra service principal certificate.

  4. Если упомянутый ранее сертификат нуждается в пароле, задайте основной секрет, используя его setPassword в версии 10.2 и выше или setAADSecurePrincipalSecret в версии 9.4 и ниже.

  5. Если сертификат имеет связанный закрытый ключ, задайте закрытый ключ с помощью setClientKey. Если для этого ключа требуется пароль, задайте пароль для закрытого ключа с помощью setClientKeyPassword.

Пример использования ActiveDirectoryServicePrincipalCertificate режима проверки подлинности:

import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.Statement;

import com.microsoft.sqlserver.jdbc.SQLServerDataSource;

public class MSEntraServicePrincipalCertificate {
    public static void main(String[] args) throws Exception{
        String principalId = "<service_principal_guid>"; // Replace with your Microsoft Entra service principal ID.
        String clientCertificate = "..."; // Replace with the location of your service principal certificate.

        SQLServerDataSource ds = new SQLServerDataSource();
        ds.setServerName("msentra-managed-demo.database.windows.net"); // Replace with your server name
        ds.setDatabaseName("demo"); // Replace with your database
        ds.setAuthentication("ActiveDirectoryServicePrincipalCertificate");
        ds.setUser(principalId); // setAADSecurePrincipalId for JDBC Driver 9.4 and below
        ds.setClientCertificate(clientCertificate);

        try (Connection connection = ds.getConnection();
             Statement stmt = connection.createStatement();
             ResultSet rs = stmt.executeQuery("SELECT SUSER_SNAME()")) {
            if (rs.next()) {
                System.out.println("You have successfully logged on as: " + rs.getString(1));
            }
        }
    }
}

Если подключение установлено успешно, отобразится следующее сообщение.

You have successfully logged on as: <your app/client ID>

Подключение с помощью токена доступа.

Приложения и службы могут получить маркер доступа из идентификатора Microsoft Entra и использовать его для подключения к База данных SQL Azure, Управляемый экземпляр SQL Azure и Azure Synapse Analytics.

Примечание.

accessToken можно задать только с помощью параметра getConnection() Properties метода в классе DriverManager. Его нельзя использовать в строке подключения. Начиная с драйвера версии 12.2 пользователи могут реализовывать и предоставлять обратный accessToken вызов драйверу для продления маркеров в сценариях пула подключений. Для сценариев пула подключений требуется реализация пула подключений для использования стандартных классов пула подключений JDBC.

В следующем примере содержится простое приложение Java, которое подключается к Azure с помощью проверки подлинности на основе маркеров доступа.

Сборка и запуск примера

  1. Создайте учетную запись приложения в идентификаторе Microsoft Entra для службы.

    1. Войдите на портал Azure.
    2. Перейдите к идентификатору Microsoft Entra в области навигации слева.
    3. Щелкните Регистрация приложений.
    4. Выберите Создать регистрацию.
    5. Введите mytokentest понятное имя приложения.
    6. Оставьте выбор по умолчанию для поддерживаемых типов учетных записей, которые могут использовать приложение.
    7. Выберите " Зарегистрировать " в нижней части экрана.
    8. Не требуется URL-адрес входа. Укажите что-нибудь: https://mytokentest
    9. Выберите Create внизу.
    10. После выбора регистрации приложение сразу же создается и вы перейдете на страницу ресурсов.
    11. В поле Essentials найдите идентификатор приложения (клиента) и скопируйте его. Это значение потребуется позже для настройки приложения.
    12. Выберите сертификаты и секреты в области навигации. На вкладке секреты клиента (0) выберите новый секрет клиента. Введите описание секрета и выберите срок действия (по умолчанию это нормально). Выберите " Добавить " внизу. Важно перед выходом из этой страницы скопировать созданное значение для секрета клиента. Это значение нельзя просмотреть после выхода страницы. Это значение является секретом клиента.
    13. Вернитесь к области Регистрация приложений идентификатора Microsoft Entra и найдите вкладку "Конечные точки". Скопируйте URL-адрес в разделе OAuth 2.0 token endpoint. Этот URL-адрес — это URL-адрес STS.

    Конечная точка для регистрации приложений на портале Azure — URL-адрес службы токенов безопасности

  2. Подключитесь к базе данных в качестве администратора Microsoft Entra и используйте команду T-SQL для подготовки пользователя автономной базы данных для субъекта приложения. Дополнительные сведения о создании администратора Microsoft Entra и пользователя автономной базы данных см. в разделе "Подключение с помощью проверки подлинности Microsoft Entra".

    CREATE USER [mytokentest] FROM EXTERNAL PROVIDER

  3. На клиентском компьютере, где выполняется пример, скачайте библиотеку проверки подлинности Майкрософт (MSAL) для библиотеки Java и ее зависимости. MSAL требуется только для выполнения этого конкретного примера. В примере используются API из этой библиотеки для получения маркера доступа из идентификатора Microsoft Entra. Если у вас уже есть маркер доступа, этот шаг можно пропустить и удалить из примера раздел, который извлекает маркер доступа.

В приведенном ниже примере замените собственными значениями URL-адрес службы токенов безопасности, идентификатор клиента, секрет клиента, имя сервера и базы данных.

import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.Statement;
import java.util.concurrent.Executors;
import java.util.concurrent.Future;
import com.microsoft.sqlserver.jdbc.SQLServerDataSource;

// The microsoft-authentication-library-for-java is needed to retrieve the access token in this example.
import com.microsoft.aad.msal4j.ClientCredentialFactory;
import com.microsoft.aad.msal4j.ClientCredentialParameters;
import com.microsoft.aad.msal4j.ConfidentialClientApplication;
import com.microsoft.aad.msal4j.IAuthenticationResult;
import com.microsoft.aad.msal4j.IClientCredential;

public class MSEntraTokenBased {

    public static void main(String[] args) throws Exception {

        // Retrieve the access token from Microsoft Entra ID.
        String spn = "https://database.windows.net/";
        String stsurl = "https://login.microsoftonline.com/..."; // Replace with your STS URL.
        String clientId = "<service_principal_guid>"; // Replace with your client ID.
        String clientSecret = "..."; // Replace with your client secret.

        String scope = spn +  "/.default";
        Set<String> scopes = new HashSet<>();
        scopes.add(scope);

        ExecutorService executorService = Executors.newSingleThreadExecutor();
        IClientCredential credential = ClientCredentialFactory.createFromSecret(clientSecret);
        ConfidentialClientApplication clientApplication = ConfidentialClientApplication
            .builder(clientId, credential).executorService(executorService).authority(stsurl).build();
        CompletableFuture<IAuthenticationResult> future = clientApplication
            .acquireToken(ClientCredentialParameters.builder(scopes).build());

        IAuthenticationResult authenticationResult = future.get();
        String accessToken = authenticationResult.accessToken();

        System.out.println("Access Token: " + accessToken);

        // Connect with the access token.
        SQLServerDataSource ds = new SQLServerDataSource();

        ds.setServerName("msentra-managed-demo.database.windows.net"); // Replace with your server name.
        ds.setDatabaseName("demo"); // Replace with your database name.
        ds.setAccessToken(accessToken);

        try (Connection connection = ds.getConnection();
                Statement stmt = connection.createStatement();
                ResultSet rs = stmt.executeQuery("SELECT SUSER_SNAME()")) {
            if (rs.next()) {
                System.out.println("You have successfully logged on as: " + rs.getString(1));
            }
        }
    }
}

Если подключение установлено успешно, отобразится следующее сообщение:

Access Token: <your access token>
You have successfully logged on as: <your client ID>

Подключение с помощью обратного вызова маркера доступа

Как и свойство маркера доступа, обратный вызов маркера доступа позволяет зарегистрировать метод, предоставляющий маркер доступа драйверу. Преимуществом этого обратного вызова по сравнению со свойством является обратный вызов, позволяющий драйверу запрашивать новый маркер доступа при истечении срока действия маркера. Например, пул соединений, создающий новое подключение, может запросить новый маркер с новой датой окончания срока действия. Дополнительные сведения см. в разделе "Использование пула подключений".

В следующем примере демонстрируется реализация и настройка обратного вызова accessToken.

import com.microsoft.aad.msal4j.IClientCredential;
import com.microsoft.aad.msal4j.ClientCredentialFactory;
import com.microsoft.aad.msal4j.ConfidentialClientApplication;
import com.microsoft.aad.msal4j.IAuthenticationResult;
import com.microsoft.aad.msal4j.ClientCredentialParameters;
import java.sql.Connection;
import java.util.HashSet;
import java.util.Set;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;

public class MSEntraAccessTokenCallback {

    public static void main(String[] args) {

        SQLServerAccessTokenCallback callback = new SQLServerAccessTokenCallback() {
            @Override
            public SqlAuthenticationToken getAccessToken(String spn, String stsurl) {

                String clientSecret = "..."; // Replace with your client secret.
                String clientId = "<service_principal_guid>"; // Replace with your client ID.

                String scope = spn + "/.default";
                Set<String> scopes = new HashSet<>();
                scopes.add(scope);

                try {
                    ExecutorService executorService = Executors.newSingleThreadExecutor();
                    IClientCredential credential = ClientCredentialFactory.createFromSecret(clientSecret);
                    ConfidentialClientApplication clientApplication = ConfidentialClientApplication
                            .builder(clientId, credential).executorService(executorService).authority(stsurl).build();
                    CompletableFuture<IAuthenticationResult> future = clientApplication
                            .acquireToken(ClientCredentialParameters.builder(scopes).build());

                    IAuthenticationResult authenticationResult = future.get();
                    String accessToken = authenticationResult.accessToken();

                    return new SqlAuthenticationToken(accessToken, authenticationResult.expiresOnDate().getTime());
                } catch (Exception e) {
                    e.printStackTrace();
                }
                return null;
            }
        };

        SQLServerDataSource ds = new SQLServerDataSource();
        ds.setServerName("msentra-managed-demo.database.windows.net"); // Replaces with your server name.
        ds.setDatabaseName("demo"); // Replace with your database name.
        ds.setAccessTokenCallback(callback);

        try (Connection connection = ds.getConnection();
                Statement stmt = connection.createStatement();
                ResultSet rs = stmt.executeQuery("SELECT SUSER_SNAME()")) {
            if (rs.next()) {
                System.out.println("You have successfully logged on as: " + rs.getString(1));
            }
        }
    }
}

Если подключение установлено успешно, отобразится следующее сообщение:

You have successfully logged on as: <your client ID>

Начиная с версии 12.4 accessToken обратный accessTokenCallbackClass вызов можно задать с помощью свойства строка подключения. В следующем примере показано, как задать обратный accessToken вызов с помощью этого свойства:

import com.microsoft.aad.msal4j.IClientCredential;
import com.microsoft.aad.msal4j.ClientCredentialFactory;
import com.microsoft.aad.msal4j.ConfidentialClientApplication;
import com.microsoft.aad.msal4j.IAuthenticationResult;
import com.microsoft.aad.msal4j.ClientCredentialParameters;
import java.sql.Connection;
import java.util.HashSet;
import java.util.Set;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;

 

public class MSEntraAccessTokenCallbackClass {
    public static class AccessTokenCallbackClass implements SQLServerAccessTokenCallback {
        @Override
        public SqlAuthenticationToken getAccessToken(String spn, String stsurl) {
            String clientSecret = "..."; // Replace with your client secret.
            String clientId = "<service_principal_guid>"; // Replace with your client ID.
            
            String scope = spn + "/.default";
            Set<String> scopes = new HashSet<>();
            scopes.add(scope);
            
            try {
                ExecutorService executorService = Executors.newSingleThreadExecutor();
                IClientCredential credential = ClientCredentialFactory.createFromSecret(clientSecret);
                ConfidentialClientApplication clientApplication = ConfidentialClientApplication

                        .builder(clientId, credential).executorService(executorService).authority(stsurl).build();
                
                CompletableFuture<IAuthenticationResult> future = clientApplication
                        .acquireToken(ClientCredentialParameters.builder(scopes).build());
                
                IAuthenticationResult authenticationResult = future.get();
                String accessToken = authenticationResult.accessToken();
                
                return new SqlAuthenticationToken(accessToken, authenticationResult.expiresOnDate().getTime());
            } catch (Exception e) {
                e.printStackTrace();
            }
            return null;
        }
    }
    
    public static void main(String[] args) throws Exception {
        
        SQLServerDataSource ds = new SQLServerDataSource();
        ds.setServerName("msentra-managed-demo.database.windows.net"); // Replaces with your server name.
        ds.setDatabaseName("demo"); // Replace with your database name.
        ds.setAccessTokenCallbackClass(AccessTokenCallbackClass.class.getName());
        
        try (Connection connection = ds.getConnection();
             Statement stmt = connection.createStatement();
             ResultSet rs = stmt.executeQuery("SELECT SUSER_SNAME()")) {
            if (rs.next()) {
                System.out.println("You have successfully logged on as: " + rs.getString(1));
            }
        }
    }
}

Если подключение установлено успешно, отобразится следующее сообщение:

You have successfully logged on as: <your client ID>

Следующие шаги

Дополнительные сведения о связанных понятиях см. в следующих статьях: