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

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

  • Статья

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

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

Вы можете использовать проверку подлинности Microsoft Entra, которая является механизмом подключения к базе данных Azure SQL, управляемому экземпляру Azure SQL и Azure Synapse Analytics с помощью идентификаторов Microsoft Entra ID. Используйте проверку подлинности 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 можно также использовать для подключения к базе данных Azure SQL/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 Federation Services (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, authentication=ActiveDirectoryServicePrincipal можно использовать для подключения к Azure SQL/Synapse Analytics, указав идентификатор приложения или клиента в свойстве userName и секрет удостоверения основной сущности службы в свойстве password. Дополнительные сведения см. в разделе "Подключение с помощью режима проверки подлинности ActiveDirectoryServicePrincipal".

    • Сертификат главного компонента службы Active Directory

      • Начиная с версии драйвера 12.4, authentication=ActiveDirectoryServicePrincipalCertificate можно использовать для подключения к базе данных SQL Azure/Synapse Analytics, указав идентификатор приложения/клиента в свойстве 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
ActiveDirectoryPassword
ActiveDirectoryIntegrated
ActiveDirectoryInteractive
ActiveDirectoryServicePrincipal
ActiveDirectoryServicePrincipalCertificate
ActiveDirectoryManagedIdentity
ActiveDirectoryMSI
ActiveDirectoryDefault		 12.10 azure-identity 1.15.3

Подключение с помощью режима проверки подлинности 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 аутентификации использует цепную реализацию клиентской библиотеки удостоверений 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
12.10 azure-identity 1.15.3 Окружающая среда
Идентификация рабочей нагрузки
Управляемая идентичность
CLI разработчика Azure
IntelliJ
Azure CLI
Azure PowerShell

Существует множество переменных, которые можно задать для настройки учетных Environment данных. Дополнительные сведения о настройке DefaultAzureCredential цепочки, включая 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 ID. Пользователь базы данных, представляющий пользователя 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 ID.

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

  • Работает на: Windows

  • Действие:

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

    Примечание.

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

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. Найдите приведенные ниже строки кода. Замените username на имя пользователя 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. Задайте идентификатор субъекта и секрет субъекта с помощью setUser и setPassword в версии 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 ID и использовать его для подключения к базе данных SQL Azure, управляемому экземпляру SQL Azure и Azure Synapse Analytics.

Примечание.

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

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

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

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

    1. Войдите на портал Azure.
    2. Перейдите к Microsoft Entra ID в левой навигационной панели.
    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.

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

    CREATE USER [mytokentest] FROM EXTERNAL PROVIDER

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

В приведенном ниже примере замените собственными значениями 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>

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

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