Udostępnij za pomocą

Połącz przy użyciu uwierzytelniania Microsoft Entra

pobierz sterownik JDBC

Ten artykuł zawiera informacje na temat tworzenia aplikacji Java korzystających z funkcji uwierzytelniania Microsoft Entra za pomocą sterownika JDBC firmy Microsoft dla programu SQL Server.

Uwierzytelnianie Entra firmy Microsoft jest mechanizmem umożliwiającym połączenie z Azure SQL Database, Azure SQL Managed Instance i Azure Synapse Analytics przy użyciu tożsamości w Microsoft Entra ID. Uwierzytelnianie Microsoft Entra umożliwia centralne zarządzanie tożsamościami użytkowników bazy danych i stanowi alternatywę dla uwierzytelniania w programie SQL Server. Sterownik JDBC umożliwia określenie poświadczeń usługi Microsoft Entra w parametrach połączenia JDBC w celu nawiązania połączenia z usługą Azure SQL. Aby uzyskać informacje na temat konfigurowania uwierzytelniania w usłudze Microsoft Entra, odwiedź stronę Connecting to Azure SQL By Using Microsoft Entra authentication.

Właściwości połączenia do obsługi uwierzytelniania firmy Microsoft Entra w sterowniku JDBC firmy Microsoft dla programu SQL Server są następujące:

  • uwierzytelnianie: Użyj tej właściwości, aby określić, która metoda uwierzytelniania SQL ma być używana dla połączenia. Możliwe wartości to:

    • ActiveDirectoryManagedIdentity

      • Od wersji sterownika 8.3.1, authentication=ActiveDirectoryMSI można użyć do połączenia z usługą Azure SQL Database/Synapse Analytics z zasobu Azure z włączoną obsługą tożsamości. Opcjonalnie msiClientId można określić we właściwościach Connection/DataSource wraz z tym trybem uwierzytelniania. msiClientId musi zawierać identyfikator klienta tożsamości zarządzanej, który ma być używany do uzyskiwania accessToken na potrzeby nawiązywania połączenia. Od wersji sterownika 12.2 można również użyć authentication=ActiveDirectoryManagedIdentity do nawiązania połączenia z bazą danych Azure SQL Database/Synapse Analytics z zasobu Azure, który obsługuje włączoną funkcję "Identity". Opcjonalnie identyfikator klienta tożsamości zarządzanej można również ustawić we właściwości user. Aby uzyskać więcej informacji, zobacz Połącz przy użyciu trybu uwierzytelniania za pomocą zarządzanej tożsamości ActiveDirectory.

    • ActiveDirectoryDefault

      • Od wersji sterownika 12.2, authentication=ActiveDirectoryDefault można użyć do nawiązania połączenia z usługą Azure SQL/Synapse Analytics za pośrednictwem DefaultAzureCredential z biblioteki klienta Azure Identity. Aby uzyskać więcej informacji, zobacz Połącz, używając trybu uwierzytelniania ActiveDirectoryDefault.

    • ActiveDirectoryIntegrated

      • Od wersji sterownika 6.0, authentication=ActiveDirectoryIntegrated można używać do połączenia z usługą Azure SQL/Synapse Analytics przez zintegrowane uwierzytelnianie. Aby użyć tego trybu uwierzytelniania, należy powiązać lokalne usługi Active Directory Federation Services (ADFS) z usługą Microsoft Entra ID w chmurze. Po skonfigurowaniu można nawiązać połączenie, dodając bibliotekę natywną mssql-jdbc_auth-<version>-<arch>.dll do ścieżki klasy aplikacji w systemie Windows lub konfigurując bilet Protokołu Kerberos na potrzeby obsługi uwierzytelniania międzyplatformowego. Możesz uzyskać dostęp do Azure SQL/Azure Synapse Analytics bez konieczności podawania poświadczeń, po zalogowaniu się na komputerze podłączonym do domeny. Aby uzyskać więcej informacji, zobacz Połącz się, używając trybu uwierzytelniania ActiveDirectoryIntegrated.

    • ActiveDirectoryPassword

    • ActiveDirectoryInteractive

    • ActiveDirectoryServicePrincipal

      • Od wersji sterownika 9.2, authentication=ActiveDirectoryServicePrincipal może być używany do nawiązywania połączenia z Azure SQL/Synapse Analytics, określając identyfikator aplikacji/klienta w polu userName i sekretny klucz tożsamości jednostki usługi w polu password. Aby uzyskać więcej informacji, zobacz Połącz za pomocą trybu uwierzytelniania ActiveDirectoryServicePrincipal.

    • CertyfikatGłównegoUżytkownikaUsługiActiveDirectory

      • Od wersji 12.4 sterownika, authentication=ActiveDirectoryServicePrincipalCertificate można użyć do nawiązania połączenia z usługą Azure SQL Database/Synapse Analytics, określając identyfikator aplikacji/klienta we właściwości userName i lokalizację certyfikatu podmiotu usługi we właściwości clientCertificate. Aby uzyskać więcej informacji, zobacz Podłącz używając trybu uwierzytelniania ActiveDirectoryServicePrincipalCertificate.

    • SqlPassword

      • Użyj authentication=SqlPassword, aby nawiązać połączenie z programem SQL Server przy użyciu właściwości userName/user i password.

    • Nieokreślone

      • Użyj authentication=NotSpecified lub pozostaw ją jako domyślną, gdy żadna z tych metod uwierzytelniania nie jest wymagana.

    • accessToken: użyj tej właściwości połączenia, aby nawiązać połączenie z usługą SQL Database przy użyciu tokenu dostępu. accessToken można ustawić tylko przy użyciu parametru Properties metody getConnection() w klasie DriverManager. Nie można jej używać w adresie URL połączenia.

Aby uzyskać więcej informacji, zobacz właściwość uwierzytelniania na stronie Ustawianie właściwości połączenia.

Wymagania dotyczące konfiguracji klienta

Oprócz podstawowego sterownika wymagania systemowe, następujące tryby uwierzytelniania mają więcej wymagań.

W poniższej tabeli wymieniono wymagane zależności biblioteki dla każdego trybu uwierzytelniania i wersji sterownika. Potrzebne są również zależności do zależności.

Uwaga

W przypadkach, gdy poprawka dla wersji głównej ma inną wersję zależności niż wersja główna, poprawka jest również wymieniona.

Opcja uwierzytelniania Wersje sterowników Zależności biblioteki
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 Adal4j 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

Nawiązywanie połączenia przy użyciu trybu uwierzytelniania ActiveDirectoryManagedIdentity

Ten tryb uwierzytelniania jest obsługiwany od wersji 7.2. Aby go użyć, określ authentication=ActiveDirectoryMSI. Począwszy od wersji 12.2, można również określić authentication=ActiveDirectoryManagedIdentity.

Oprócz wymagań dotyczących zależności biblioteki wymienionych w Wymagania dotyczące konfiguracji klientata funkcja ma następujące wymagania:

W poniższym przykładzie pokazano, jak używać trybu authentication=ActiveDirectoryManagedIdentity. Uruchom ten przykład z poziomu zasobu platformy Azure skonfigurowanego pod kątem tożsamości zarządzanej.

Aby uruchomić przykład, zastąp nazwę serwera/bazy danych nazwą serwera/bazy danych w następujących wierszach:

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

Przykład użycia trybu uwierzytelniania 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));
            }
        }
    }
}

W poniższym przykładzie pokazano, jak używać trybu 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));
            }
        }
    }
}

Te przykłady na maszynie wirtualnej Azure pobierają token dostępu z tożsamości zarządzanej przypisanej systemowo lub tożsamości zarządzanej przypisanej użytkownikowi (jeśli msiClientId lub user jest określone z identyfikatorem klienta tożsamości zarządzanej) i ustanawiają połączenie przy użyciu pobranego tokenu dostępu. Jeśli połączenie zostanie nawiązane, powinien zostać wyświetlony następujący komunikat:

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

Nawiązywanie połączenia przy użyciu trybu uwierzytelniania ActiveDirectoryDefault

Opcja uwierzytelniania ActiveDirectoryDefault używa DefaultAzureCredentialTokenCredential implementacji DefaultAzureCredential biblioteki klienta tożsamości platformy Azure. Poświadczenie łączy często używane metody uwierzytelniania połączone w łańcuch.

ActiveDirectoryDefault uwierzytelnianie wymaga zależności czasu wykonywania od biblioteki klienta tożsamości platformy Azure dla tożsamości zarządzanej. Aby uzyskać szczegółowe informacje o wersji biblioteki, zobacz wymagania dotyczące konfiguracji klienta .

W poniższej tabeli wymieniono łańcuch poświadczeń DefaultAzureCredential dla każdej wersji sterownika JDBC.

Wersja sterownika wersja usługi azure-identity łańcuch DefaultAzureCredential
12.2 azure-identity 1.7.0 Środowisko
Tożsamość zarządzana
IntelliJ
Interfejs wiersza polecenia platformy Azure
Azure PowerShell
12.4 azure-identity 1.9.0 Środowisko
Tożsamość obciążenia roboczego
Tożsamość zarządzana
Azure Developer CLI
IntelliJ
Interfejs wiersza polecenia platformy Azure
Azure PowerShell
12.6 azure-identity 1.11.1 Środowisko
Tożsamość obciążenia roboczego
Tożsamość zarządzana
Azure Developer CLI
IntelliJ
Interfejs wiersza polecenia platformy Azure
Azure PowerShell
12.8 azure-identity 1.12.2 Środowisko
Tożsamość obciążenia roboczego
Tożsamość zarządzana
Azure Developer CLI
IntelliJ
Interfejs wiersza polecenia platformy Azure
Azure PowerShell
12.10 azure-identity 1.15.3 Środowisko
Tożsamość obciążenia roboczego
Tożsamość zarządzana
Azure Developer CLI
IntelliJ
Interfejs wiersza polecenia platformy Azure
Azure PowerShell

Istnieje wiele zmiennych, które można ustawić w celu skonfigurowania poświadczeń Environment. Aby uzyskać szczegółowe informacje na temat konfigurowania łańcucha DefaultAzureCredential, w tym poświadczeń Environment, zobacz odpowiednią wersję dokumentacji tożsamości platformy Azure połączoną w poprzedniej tabeli.

Aby użyć IntellijCredential w systemie Windows, ustaw zmienną środowiskową INTELLIJ_KEEPASS_PATH na lokalizację pliku keepass. Na przykład INTELLIJ_KEEPASS_PATH=C:\user\your\path\to\the\keepass\file.

Aby udostępnić więcej klientów w DefaultAzureCredential, użyj zmiennej środowiskowej ADDITIONALLY_ALLOWED_TENANTS. Ta zmienna przyjmuje listę rozdzielaną przecinkami. Na przykład ADDITIONALLY_ALLOWED_TENANTS=<your-tenant-id-0>,<your-tenant-id-1>,<your-tenant-id-2>,...

W poniższym przykładzie pokazano, jak używać trybu authentication=ActiveDirectoryDefault z AzureCliCredential w DefaultAzureCredential.

  1. Najpierw zaloguj się do interfejsu wiersza polecenia platformy Azure przy użyciu następującego polecenia.

    az login

  2. Po pomyślnym zalogowaniu się do interfejsu wiersza polecenia platformy Azure uruchom następujący kod.

    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));
            }
        }
    }
}

Połącz się, używając trybu uwierzytelniania Active-Directory-Integrated

Istnieją dwa sposoby używania uwierzytelniania ActiveDirectoryIntegrated w sterowniku JDBC firmy Microsoft dla programu SQL Server:

  • W systemie Windows mssql-jdbc_auth-<version>-<arch>.dll z pobranego pakietu można skopiować do lokalizacji znajdującej się w ścieżce systemowej.
  • Jeśli nie możesz użyć biblioteki DLL, od wersji 6.4 możesz skonfigurować bilet Kerberos. Ta metoda jest obsługiwana na różnych platformach (Windows, Linux i macOS). Aby uzyskać więcej informacji, zobacz Konfigurowanie biletu Kerberos w systemach Windows, Linux i macOS.

Upewnij się, że masz wymagane biblioteki zależne od wymagań dotyczących konfiguracji klienta .

W poniższym przykładzie pokazano, jak używać trybu authentication=ActiveDirectoryIntegrated. Ten przykład działa na maszynie przyłączonej do domeny, która jest sfederowana z identyfikatorem Entra firmy Microsoft. Użytkownik bazy danych reprezentujący użytkownika systemu Windows musi istnieć w bazie danych i musi mieć uprawnienie CONNECT.

Przed wykonaniem przykładu zastąp nazwę serwera/bazy danych nazwą serwera/bazy danych w następujących wierszach:

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

Przykład użycia trybu uwierzytelniania 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));
            }
        }
    }
}

Uruchomienie tego przykładu automatycznie wykorzystuje bilet Kerberos na platformie klienta i nie jest wymagane żadne hasło. Jeśli połączenie zostanie nawiązane, powinien zostać wyświetlony następujący komunikat:

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

Ustaw bilet Kerberos w systemach Windows, Linux i macOS

Aby połączyć bieżącego użytkownika z kontem domeny systemu Windows, musisz utworzyć bilet protokołu Kerberos. Poniżej przedstawiono podsumowanie kluczowych kroków.

Windows

Uwaga

W systemie Windows można użyć mssql-jdbc_auth-<version>-<arch>.dll z pobranego pakietu zamiast tych kroków konfiguracji protokołu Kerberos. Te kroki są wymagane tylko wtedy, gdy nie można użyć biblioteki DLL.

Zestaw JDK jest dostarczany z kinit, którego można użyć do pobrania biletu TGT z centrum dystrybucji kluczy (KDC) na maszynie przyłączonej do domeny, która jest sfederowana z identyfikatorem Entra firmy Microsoft.

Krok 1. Pobieranie biletu udzielania biletu

  • Uruchom w: Windows

  • Akcja:

    • Użyj polecenia kinit username@DOMAIN.COMPANY.COM, aby uzyskać bilet TGT z centrum dystrybucji kluczy (KDC), a następnie zostaniesz poproszony o podanie hasła do domeny.
    • Użyj klist, aby wyświetlić dostępne bilety. Jeśli kinit zakończył się pomyślnie, powinien zostać wyświetlony bilet z krbtgt/DOMAIN.COMPANY.COM@ DOMAIN.COMPANY.COM.

    Uwaga

    Może być konieczne określenie pliku .ini za pomocą -Djava.security.krb5.conf, aby aplikacja mogła zlokalizować centrum dystrybucji kluczy (KDC).

Linux i macOS

Wymagania

Dostęp do maszyny przyłączonej do domeny systemu Windows w celu wykonywania zapytań do kontrolera domeny Kerberos.

Krok 1: Znajdź serwer KDC Kerberos

  • Uruchom w: wiersz polecenia systemu Windows

  • akcja: nltest /dsgetdc:DOMAIN.COMPANY.COM (gdzie DOMAIN.COMPANY.COM jest mapowane do nazwy domeny)

  • Przykładowe wyjście

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

  • Informacje dotyczące wyodrębniania nazwy kontrolera domeny, w tym przypadku co1-red-dc-33.domain.company.com

Krok 2. Konfigurowanie KDC w pliku krb5.conf

  • Uruchom w: Linux/macOS

  • Akcja: edytuj /etc/krb5.conf w wybranym edytorze. Konfigurowanie następujących kluczy

    [libdefaults]
  default_realm = DOMAIN.COMPANY.COM

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

    Następnie zapisz plik krb5.conf i zamknij

    Uwaga

    Domena musi być zapisana WIELKIMI LITERAMI.

Krok 3: Testowanie pobierania biletu przyznającego uprawnienia
  • Uruchom w: Linux/macOS
  • Akcja:
    • Użyj polecenia kinit username@DOMAIN.COMPANY.COM, aby uzyskać bilet TGT z centrum dystrybucji kluczy (KDC), a następnie zostaniesz poproszony o podanie hasła do domeny.
    • Użyj klist, aby wyświetlić dostępne bilety. Jeśli kinit zakończył się pomyślnie, powinien zostać wyświetlony bilet z krbtgt/DOMAIN.COMPANY.COM@ DOMAIN.COMPANY.COM.

Nawiązywanie połączenia przy użyciu trybu uwierzytelniania ActiveDirectoryPassword

W poniższym przykładzie pokazano, jak używać trybu authentication=ActiveDirectoryPassword.

Aby skompilować i uruchomić przykład:

  1. Upewnij się, że masz wymagane biblioteki zależne od wymagań dotyczących konfiguracji klienta .

  2. Znajdź następujące wiersze kodu i zastąp nazwę serwera/bazy danych nazwą serwera/bazy danych.

    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. Znajdź następujące wiersze kodu. Zastąp nazwę użytkownika nazwą użytkownika Microsoft Entra, z którym chcesz się połączyć.

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

Przykład użycia trybu uwierzytelniania 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));
            }
        }
    }
}

Jeśli połączenie zostanie nawiązane, powinien zostać wyświetlony następujący komunikat jako dane wyjściowe:

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

Nawiązywanie połączenia przy użyciu trybu uwierzytelniania ActiveDirectoryInteractive

W poniższym przykładzie pokazano, jak używać trybu authentication=ActiveDirectoryInteractive.

Aby skompilować i uruchomić przykład:

  1. Upewnij się, że masz wymagane biblioteki zależne od wymagań dotyczących konfiguracji klienta .

  2. Znajdź następujące wiersze kodu i zastąp nazwę serwera/bazy danych nazwą serwera/bazy danych.

    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. Znajdź następujące wiersze kodu. Zastąp nazwę użytkownika nazwą użytkownika Microsoft Entra, jako którego chcesz się połączyć.

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

Przykład użycia trybu uwierzytelniania 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));
            }
        }
    }
}

Po uruchomieniu programu zostanie wyświetlona przeglądarka w celu uwierzytelnienia użytkownika. Dokładnie to, co widzisz, zależy od sposobu konfigurowania identyfikatora Entra firmy Microsoft. Może to lub nie zawierać monity uwierzytelniania wieloskładnikowego dotyczące nazwy użytkownika, hasła, numeru PIN lub drugiego uwierzytelniania urządzenia za pośrednictwem telefonu. Jeśli wiele interakcyjnych żądań uwierzytelniania odbywa się w tym samym programie, późniejsze żądania mogą nawet nie monitować, czy biblioteka uwierzytelniania może ponownie użyć wcześniej buforowanego tokenu uwierzytelniania.

Aby uzyskać informacje o sposobie konfigurowania Microsoft Entra ID w celu wymagania uwierzytelniania wieloskładnikowego, zobacz Wprowadzenie do uwierzytelniania wieloskładnikowego w chmurze Microsoft Entra.

Aby uzyskać zrzuty ekranu tych okien dialogowych, zobacz Używanie wielopoziomowego uwierzytelniania Microsoft Entra.

Jeśli uwierzytelnianie użytkownika zostało ukończone pomyślnie, w przeglądarce powinien zostać wyświetlony następujący komunikat:

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

Ten komunikat wskazuje tylko, że uwierzytelnianie użytkownika zakończyło się pomyślnie, ale niekoniecznie pomyślne połączenie z serwerem. Po powrocie do aplikacji, jeśli połączenie zostanie nawiązane z serwerem, powinien zostać wyświetlony następujący komunikat jako dane wyjściowe:

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

Nawiązywanie połączenia przy użyciu trybu uwierzytelniania ActiveDirectoryServicePrincipal

W poniższym przykładzie pokazano, jak używać trybu authentication=ActiveDirectoryServicePrincipal.

Aby skompilować i uruchomić przykład:

  1. Upewnij się, że masz wymagane biblioteki zależne od wymagań dotyczących konfiguracji klienta .

  2. Znajdź następujące wiersze kodu i zastąp nazwę serwera/bazy danych nazwą serwera/bazy danych.

    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. Znajdź następujące wiersze kodu. Zastąp wartość principalId identyfikatorem aplikacji/identyfikatorem klienta jednostki usługi Microsoft Entra, z którą chcesz nawiązać połączenie. Zastąp wartość principalSecret sekretem.

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

  4. Ustaw identyfikator podmiotu zabezpieczeń i klucz tajny podmiotu zabezpieczeń przy użyciu setUser i setPassword w wersji 10.2 i nowszej oraz setAADSecurePrincipalId i setAADSecurePrincipalSecret w wersji 9.4 i nowszej.

Przykład użycia trybu uwierzytelniania 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));
            }
        }
    }
}

Jeśli połączenie zostanie nawiązane, powinien zostać wyświetlony następujący komunikat jako dane wyjściowe:

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

Połącz przy użyciu trybu uwierzytelniania ActiveDirectoryServicePrincipalCertificate

W poniższym przykładzie pokazano, jak używać trybu authentication=ActiveDirectoryServicePrincipalCertificate.

Aby skompilować i uruchomić przykład:

  1. Upewnij się, że masz wymagane biblioteki zależne od wymagań dotyczących konfiguracji klienta .

  2. Znajdź następujące wiersze kodu i zastąp nazwę serwera/bazy danych nazwą serwera/bazy danych.

    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. Znajdź następujące wiersze kodu. Zastąp wartość principalId identyfikatorem aplikacji/identyfikatorem klienta jednostki usługi Microsoft Entra, z którą chcesz nawiązać połączenie. Zastąp wartość clientCertificate ścieżką pliku do certyfikatu jednostki usługi.

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

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

  4. Jeśli wcześniej wymieniony certyfikat wymaga hasła, ustaw główny klucz tajny przy użyciu setPassword w wersji 10.2 i nowszej lub setAADSecurePrincipalSecret w wersji 9.4 lub nowszej.

  5. Jeśli certyfikat ma skojarzony klucz prywatny, ustaw klucz prywatny przy użyciu setClientKey. Jeśli ten klucz wymaga hasła, ustaw hasło dla klucza prywatnego przy użyciu setClientKeyPassword.

Przykład użycia trybu uwierzytelniania 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 path to 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));
            }
        }
    }
}

Jeśli połączenie zostanie nawiązane, powinien zostać wyświetlony następujący komunikat jako dane wyjściowe:

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

Nawiązywanie połączenia przy użyciu tokenu dostępu

Aplikacje/usługi mogą pobierać token dostępu z identyfikatora Entra firmy Microsoft i używać go do łączenia się z usługami Azure SQL Database, Azure SQL Managed Instance i Azure Synapse Analytics.

Uwaga

accessToken można ustawić tylko przy użyciu parametru Properties metody getConnection() w klasie DriverManager. Nie można go używać w parametrach połączenia. Począwszy od wersji 12.2 sterownika, użytkownicy mogą implementować i dostarczać wywołanie zwrotne accessToken do sterownika w celu odnowienia tokena w scenariuszach puli połączeń. Scenariusze zarządzania pulą połączeń wymagają, aby implementacja puli połączeń używała standardowych klas JDBC do zarządzania pulami .

Poniższy przykład zawiera prostą aplikację Java, która łączy się z platformą Azure przy użyciu uwierzytelniania opartego na tokenach dostępu.

Aby skompilować i uruchomić przykład:

  1. Utwórz konto aplikacji w usłudze Microsoft Entra ID dla swojej usługi.

    1. Zaloguj się do witryny Azure Portal.
    2. Przejdź do pozycji Microsoft Entra ID w lewym pasku nawigacyjnym.
    3. Wybierz : Rejestracje aplikacji.
    4. Wybierz pozycję Nowa rejestracja.
    5. Wprowadź mytokentest jako przyjazną nazwę aplikacji.
    6. Pozostaw wybór domyślny dla obsługiwanych typów kont, które mogą używać aplikacji.
    7. Wybierz pozycję Zarejestruj u dołu.
    8. Nie potrzeba SIGN-ON adresu URL. Dostarcz cokolwiek: https://mytokentest.
    9. Wybierz Create u dołu.
    10. Po wybraniu Zarejestrujaplikacja zostanie natychmiast utworzona i zostanie wyświetlona strona zasobu.
    11. W polu Essentials znajdź identyfikator aplikacji (klienta) i skopiuj go. Ta wartość będzie potrzebna później do skonfigurowania aplikacji.
    12. Wybierz pozycję Certyfikaty tajemnice & w okienku nawigacji. Na karcie Sekrety klienta (0) wybierz opcję Nowy sekret klienta. Wprowadź opis sekretu i wybierz datę wygaśnięcia (wartość domyślna jest odpowiednia). Wybierz pozycję Dodaj u dołu. Ważne przed opuszczeniem tej strony skopiuj wygenerowaną wartość dla tajnego klucza klienta. Tej wartości nie można wyświetlić po opuszczeniu strony. Ta wartość jest kluczem tajnym klienta.
    13. Wróć do okienka Rejestracje aplikacji dla identyfikatora Entra firmy Microsoft i znajdź kartę punktów końcowych. Skopiuj adres URL w obszarze OAuth 2.0 token endpoint. Ten adres to Twój adres URL usługi STS.

  2. Połącz się z bazą danych jako administrator Microsoft Entra i użyj polecenia T-SQL, aby utworzyć użytkownika bazy danych z ograniczeniami dla głównego obiektu aplikacji. Aby uzyskać więcej informacji na temat tworzenia administratora Microsoft Entra i użytkownika bazy danych zawartej, zobacz Łączenie przy użyciu uwierzytelniania Microsoft Entra.

    CREATE USER [mytokentest] FROM EXTERNAL PROVIDER

  3. Na komputerze klienckim, na którym uruchomiono przykład, pobierz bibliotekę Microsoft Authentication Library (MSAL) dla języka Java i jej zależności. Do uruchomienia tego konkretnego przykładu wymagana jest tylko MSAL. W przykładzie użyto interfejsów API z tej biblioteki do pobrania tokenu dostępu z identyfikatora Entra firmy Microsoft. Jeśli masz już token dostępu, możesz pominąć ten krok i usunąć sekcję w przykładzie, który pobiera token dostępu.

W poniższym przykładzie zastąp wartościami adres URL usługi STS, identyfikator klienta, klucz tajny klienta, serwer i nazwę bazy danych.

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));
            }
        }
    }
}

Jeśli połączenie zakończy się pomyślnie, powinien zostać wyświetlony następujący komunikat jako dane wyjściowe:

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

Nawiązywanie połączenia za pomocą wywołania zwrotnego tokenu dostępu

Podobnie jak właściwość tokenu dostępu, wywołanie zwrotne tokenu dostępu umożliwia zarejestrowanie metody, która zapewnia token dostępu do sterownika. Zaletą tego wywołania zwrotnego w porównaniu z właściwością jest to, że umożliwia sterownikowi żądanie nowego tokenu dostępu, gdy tymczasowy token wygaśnie. Na przykład pula połączeń tworząca nowe połączenie może zażądać nowego tokenu z nową datą wygaśnięcia. Aby uzyskać więcej informacji, zobacz Korzystanie z puli połączeń.

W poniższym przykładzie pokazano implementację i ustawienie wywołania zwrotnego 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));
            }
        }
    }
}

Jeśli połączenie zakończy się pomyślnie, powinien zostać wyświetlony następujący komunikat jako dane wyjściowe:

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

Począwszy od wersji 12.4, wywołanie zwrotne accessToken można ustawić za pomocą właściwości parametrów połączenia accessTokenCallbackClass. W poniższym przykładzie pokazano, jak ustawić wywołanie zwrotne accessToken przy użyciu tej właściwości:

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));
            }
        }
    }
}

Jeśli połączenie zakończy się pomyślnie, powinien zostać wyświetlony następujący komunikat jako dane wyjściowe:

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

Następne kroki

Dowiedz się więcej o powiązanych pojęciach w następujących artykułach:

  • Last updated on