Herstellen einer Verbindung mithilfe der Microsoft Entra-Authentifizierung

  • Artikel

JDBC-Treiber herunterladen

Dieser Artikel enthält Informationen zum Entwickeln von Java-Anwendungen, die das Microsoft Entra-Authentifizierungsfeature mit dem Microsoft-JDBC-Treiber für SQL Server verwenden.

Sie können die Microsoft Entra-Authentifizierung verwenden, bei der es sich um einen Mechanismus zum Herstellen einer Verbindung zu Azure SQL-Datenbank, Azure SQL Managed Instance und Azure Synapse Analytics unter Verwendung von Identitäten in Microsoft Entra ID handelt. Verwenden Sie die Microsoft Entra-Authentifizierung zur zentralen Verwaltung von Identitäten von Datenbankbenutzer*innen und als Alternative zur SQL Server-Authentifizierung. Mit JDBC Treiber können Sie Ihre Microsoft Entra-Anmeldedaten in der JDBC-Verbindungszeichenfolge angeben, um die Verbindung zu Azure SQL herzustellen. Weitere Informationen zur Konfiguration der Microsoft Entra-Authentifizierung finden Sie unter Herstellen einer Verbindung mit Azure AQL unter Verwendung der Microsoft Entra-Authentifizierung.

Folgende Verbindungseigenschaften im Microsoft-JDBC-Treiber für SQL Server unterstützen die Microsoft Entra-Authentifizierung:

  • Authentifizierung: Geben Sie mit dieser Eigenschaft an, welche SQL-Authentifizierung-Methode für die Verbindung verwendet werden soll. Mögliche Werte sind:

    • ActiveDirectoryManagedIdentity

      • Ab der Treiberversion 8.3.1 kann authentication=ActiveDirectoryMSI verwendet werden, um von einer Azure-Ressource mit aktivierter Identitätsunterstützung eine Verbindung mit einer Azure SQL-Datenbank- oder Synapse Analytics-Instanz herzustellen. Optional kann mit diesem Authentifizierungsmodus msiClientId in den Verbindungs-/Datenquelleneigenschaften angegeben werden. msiClientId muss die Client-ID einer verwalteten Identität enthalten, die zum Abrufen von accessToken zum Herstellen der Verbindung verwendet werden soll. Ab der Treiberversion 12.2 kann authentication=ActiveDirectoryManagedIdentity auch verwendet werden, um von einer Azure-Ressource mit aktivierter Identitätsunterstützung eine Verbindung mit einer Azure SQL-Datenbank- oder Synapse Analytics-Instanz herzustellen. Optional kann die Client-ID einer verwalteten Identität jetzt auch in der user-Eigenschaft festgelegt werden. Weitere Informationen finden Sie unter Herstellen einer Verbindung mithilfe des Authentifizierungsmodus ActiveDirectoryManagedIdentity.

    • ActiveDirectoryDefault

    • ActiveDirectoryIntegrated

      • Ab der Treiberversion 6.0 kann authentication=ActiveDirectoryIntegrated verwendet werden, um mithilfe der integrierten Authentifizierung eine Verbindung zu Azure SQL/Synapse Analytics herzustellen. Um diesen Authentifizierungsmodus zu verwenden, müssen Sie einen Verbund zwischen den lokalen Active Directory-Verbunddiensten (AD FS) und Microsoft Entra ID in der Cloud einrichten. Sobald dieser Verbund eingerichtet ist, können Sie eine Verbindung herstellen, indem Sie entweder die native Bibliothek mssql-jdbc_auth-<version>-<arch>.dll zum Anwendungsklassenpfad im Windows hinzufügen oder ein Kerberos-Ticket einrichten, um eine plattformübergreifende Authentifizierung zu unterstützen. Wenn Sie bei einem in die Domäne eingebundenen Computer angemeldet sind, können Sie auf Azure SQL/Azure Synapse Analytics zugreifen, ohne zur Eingabe von Anmeldedaten aufgefordert zu werden. Weitere Informationen finden Sie unter Herstellen einer Verbindung im ActiveDirectoryIntegrated-Authentifizierungsmodus.

    • ActiveDirectoryPassword

    • ActiveDirectoryInteractive

    • ActiveDirectoryServicePrincipal

      • Ab Treiberversion 9.2 kann authentication=ActiveDirectoryServicePrincipal verwendet werden, um eine Verbindung mit einer Instanz von Azure SQL/Synapse Analytics herzustellen, indem die Anwendungs-/Client-ID in der userName-Eigenschaft und das Geheimnis einer Dienstprinzipalidentität in der Kennworteigenschaft angegeben wird. Weitere Informationen finden Sie unter Herstellen einer Verbindung im ActiveDirectoryServicePrincipal-Authentifizierungsmodus.

    • ActiveDirectoryServicePrincipalCertificate

      • Ab Treiberversion 12.4 kann authentication=ActiveDirectoryServicePrincipalCertificate verwendet werden, um eine Verbindung mit einer Instanz von Azure SQL-Datenbank bzw. Synapse Analytics herzustellen, indem die Anwendungs-/Client-ID in der userName-Eigenschaft und der Speicherort des Dienstprinzipal-Zertifikats in der clientCertificate-Eigenschaft angegeben werden. Weitere Informationen finden Sie unter Herstellen einer Verbindung im ActiveDirectoryServicePrincipalCertificate-Authentifizierungsmodus.

    • SqlPassword

      • Verwenden Sie authentication=SqlPassword, um unter Verwendung der Eigenschaften „userName/user“ und „password“ eine Verbindung mit einer SQL Server-Instanz herzustellen.

    • NotSpecified

      • Verwenden Sie authentication=NotSpecified, oder behalten Sie den Standardwert bei, wenn keine dieser Authentifizierungsmethoden benötigt wird.

    • accessToken: Verwenden Sie diese Verbindungseigenschaft, um mithilfe eines Zugriffstokens eine Verbindung mit einer SQL-Datenbank-Instanz herzustellen. accessToken kann nur über den Properties-Parameter der getConnection()-Methode in der DriverManager-Klasse festgelegt werden. Eine Verwendung in der Verbindungs-URL ist nicht möglich.

Weitere Informationen finden Sie in der Beschreibung der Authentifizierungseigenschaft auf der Seite Festlegen von Verbindungseigenschaften.

Anforderungen an das Clientsetup

Zusätzlich zu den grundlegenden Treibersystemanforderungen haben die folgenden Authentifizierungsmodi mehr Anforderungen.

In der folgenden Tabelle sind die erforderlichen Bibliotheksabhängigkeiten für jeden Authentifizierungsmodus und jede Treiberversion aufgeführt. Abhängigkeiten von Abhängigkeiten sind ebenfalls erforderlich.

Authentifizierungsoption Treiberversionen Bibliotheksabhängigkeiten
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		 12,2 msal4j 1.13.3
ActiveDirectoryManagedIdentity
ActiveDirectoryMSI		 12,2 azure-identity 1.7.0
ActiveDirectoryPassword
ActiveDirectoryIntegrated
ActiveDirectoryInteractive
ActiveDirectoryServicePrincipal		 12,4 msal4j 1.13.8
ActiveDirectoryManagedIdentity
ActiveDirectoryMSI		 12,4 azure-identity 1.9.0
ActiveDirectoryPassword
ActiveDirectoryIntegrated
ActiveDirectoryInteractive
ActiveDirectoryServicePrincipal		 12.6 msal4j 1.14.1
ActiveDirectoryManagedIdentity
ActiveDirectoryMSI		 12.6 azure-identity 1.11.1

Herstellen einer Verbindung im ActiveDirectoryManagedIdentity-Authentifizierungsmodus

Dieser Authentifizierungsmodus wird ab Version 7.2 unterstützt. Um sie zu verwenden, geben Sie authentication=ActiveDirectoryMSI an. Ab Version 12.2 kann auch authentication=ActiveDirectoryManagedIdentity angegeben werden.

Zusätzlich zu den in Client-Setupanforderungen aufgeführten Bibliotheksabhängigkeitsanforderungen weist dieses Feature die folgenden Anforderungen auf:

Im folgenden Beispiel wird veranschaulicht, wie der Modus authentication=ActiveDirectoryManagedIdentity verwendet wird. Führen Sie dieses Beispiel in einer Azure-Ressource aus, die für die verwaltete Identität konfiguriert ist.

Ersetzen Sie die Server- und Datenbanknamen in den folgenden Zeilen durch die Namen Ihres Servers und Ihrer Datenbank, um das Beispiel auszuführen:

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("94de34e9-8e8c-470a-96df-08110924b814"); // Replace with Client ID of user-assigned managed identity to be used

Beispiel zur Verwendung des ActiveDirectoryMSI-Authentifizierungsmodus:

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("94de34e9-8e8c-470a-96df-08110924b814"); // 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));
            }
        }
    }
}

Das folgende Beispiel zeigt die Verwendung des authentication=ActiveDirectoryManagedIdentity-Modus.

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("94de34e9-8e8c-470a-96df-08110924b814"); // 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));
            }
        }
    }
}

Diese Beispiele rufen auf einer Azure-VM ein Zugriffstoken aus einer systemseitig zugewiesenen verwalteten Identität oder einer benutzerseitig zugewiesenen verwalteten Identität (wenn msiClientId oder user mit der Client-ID einer verwalteten Identität angegeben ist) ab und stellen mithilfe dieses Tokens eine Verbindung her. Wenn eine Verbindung hergestellt wurde, sollte die folgende Meldung angezeigt werden:

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

Herstellen einer Verbindung im ActiveDirectoryDefault-Authentifizierungsmodus

Die Authentifizierungsoption ActiveDirectoryDefault verwendet die verkettete TokenCredential-Implementierung der Azure Identity-Clientbibliothek DefaultAzureCredential. Die Anmeldeinformationen kombinieren häufig verwendete Authentifizierungsmethoden, die miteinander verkettet sind.

Für die ActiveDirectoryDefault-Authentifizierung ist eine Runtimeabhängigkeit von der Azure Identity-Clientbibliothek für verwaltete Identitäten erforderlich. Details zur Bibliotheksversion finden Sie unter Client-Setupanforderungen.

In der folgenden Tabelle ist die DefaultAzureCredential-Anmeldungskette für jede JDBC-Treiberversion aufgeführt.

Treiberversion azure-identity version docs Kette DefaultAzureCredential
12,2 azure-identity 1.7.0 Environment
Verwaltete Identität
IntelliJ
Azure CLI
Azure PowerShell
12,4 azure-identity 1.9.0 Environment
Workload-Identität
Verwaltete Identität
Azure Developer CLI
IntelliJ
Azure CLI
Azure PowerShell
12.6 azure-identity 1.11.1 Environment
Workload-Identität
Verwaltete Identität
Azure Developer CLI
IntelliJ
Azure CLI
Azure PowerShell

Es gibt viele Variablen, die zum Konfigurieren der Environment-Anmeldeinformationen festgelegt werden können. Ausführliche Informationen zum Konfigurieren der DefaulAzureCredential-Kette, einschließlich der Environment-Anmeldeinformationen, finden Sie in der relevanten Version der azure-identity-Dokumente, die in der vorherigen Tabelle verknüpft sind.

Um das IntellijCredential unter Windows zu verwenden, setzen Sie die Umgebungsvariable INTELLIJ_KEEPASS_PATH auf den Speicherort Ihrer keepass-Datei. Beispiel: INTELLIJ_KEEPASS_PATH=C:\user\your\path\to\the\keepass\file.

Um dem DefaultAzureCredential mehr Mandanten zur Verfügung zu stellen, verwenden Sie die Umgebungsvariable ADDITIONALLY_ALLOWED_TENANTS. Diese Variable akzeptiert eine durch Komma getrennte Liste. Beispiel: ADDITIONALLY_ALLOWED_TENANTS=<your-tenant-id-0>,<your-tenant-id-1>,<your-tenant-id-2>,...

Im folgenden Beispiel wird veranschaulicht, wie der Modus authentication=ActiveDirectoryDefault mit AzureCliCredential innerhalb von DefaultAzureCredential verwendet wird.

  1. Melden Sie sich zunächst mit dem folgenden Befehl bei der Azure CLI an.

    az login

  2. Führen Sie nach der erfolgreichen Anmeldung bei der Azure CLI den folgenden Code aus.

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

Herstellen einer Verbindung im ActiveDirectoryIntegrated-Authentifizierungsmodus

Es gibt zwei Möglichkeiten, die ActiveDirectoryIntegrated-Authentifizierung im Microsoft JDBC-Treiber für SQL Server zu verwenden:

  • Auf Windows kann mssql-jdbc_auth-<version>-<arch>.dll aus dem heruntergeladenen Paket an einen Speicherort im Systempfad kopiert werden.
  • Wenn Sie die DLL ab Version 6.4 nicht mehr verwenden können, können Sie ein Kerberos-Ticket konfigurieren. Diese Methode wird auf mehreren Plattformen (Windows, Linux und macOS) unterstützt. Weitere Informationen finden Sie unter Einrichten eines Kerberos-Tickets unter Windows, Linux und macOS.

Stellen Sie sicher, dass Sie abhängige Bibliotheken aus den Client-Setup-Anforderungen benötigen.

Im folgenden Beispiel wird veranschaulicht, wie der Modus authentication=ActiveDirectoryIntegrated verwendet wird. Dieses Beispiel wird auf einem in die Domäne eingebundenen Computer ausgeführt, der mit Microsoft Entra ID zusammengeschlossen ist. Ein Datenbankbenutzer, der Ihren Windows-Benutzer repräsentiert, muss in der Datenbank vorhanden sein und über die Berechtigung CONNECT verfügen.

Ersetzen Sie die Server- und Datenbanknamen in den folgenden Zeilen durch die Namen Ihres Servers und Ihrer Datenbank, bevor Sie das Beispiel ausführen:

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

Beispiel zur Verwendung des ActiveDirectoryIntegrated-Authentifizierungsmodus:

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

Wenn Sie dieses Beispiel ausführen, wird automatisch Ihr Kerberos-Ticket von der Client-Plattform verwendet, und es ist kein Passwort erforderlich. Wenn eine Verbindung hergestellt wurde, sollte die folgende Meldung angezeigt werden:

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

Einrichten eines Kerberos-Tickets unter Windows, Linux und macOS

Sie müssen ein Kerberos-Ticket einrichten, das den aktuellen Benutzer bzw. die aktuelle Benutzerin mit einem Windows-Domänenkonto verknüpft. Nachfolgend finden Sie eine Zusammenfassung der wichtigsten Schritte.

Windows

Hinweis

Auf Windows kann mssql-jdbc_auth-<version>-<arch>.dll aus dem heruntergeladenen Paket anstelle der Kerberos-Konfigurationsschritte verwendet werden. Diese Schritte sind nur erforderlich, wenn Sie die DLL nicht verwenden können.

Das JDK enthält kinit – hiermit können Sie auf einem in die Domäne eingebundenen Computer, der sich in einem Verbund mit Microsoft Entra ID befindet, ein TGT (Ticket-Granting Ticket) aus dem KDC (Key Distribution Center) abrufen.

Schritt 1: Abruf des TGT

  • Ausführung: Windows

  • Aktion:

    • Verwenden Sie den Befehl kinit username@DOMAIN.COMPANY.COM, um ein TGT aus dem KDC abzurufen. Sie werden zur Eingabe Ihres Domänenkennworts aufgefordert.
    • Verwenden Sie klist, um die verfügbaren Tickets anzuzeigen. Wenn kinit erfolgreich war, sollten Sie ein Ticket von krbtgt/DOMAIN.COMPANY.COM@ DOMAIN.COMPANY.COM sehen.

    Hinweis

    Möglicherweise müssen Sie eine .ini-Datei mit -Djava.security.krb5.conf angeben, damit Ihre Anwendung das KDC findet.

Linux und macOS

Requirements (Anforderungen)

Zugriff auf einen in die Windows-Domäne eingebundenen Computer, um den Kerberos-Domänencontroller abzufragen.

Schritt 1: Suchen des Kerberos-KDC

  • Ausführung: Windows-Befehlszeile

  • Aktion: nltest /dsgetdc:DOMAIN.COMPANY.COM (wobei DOMAIN.COMPANY.COM der Name Ihrer Domäne zugeordnet ist)

  • Beispielausgabe

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

  • Zu extrahierende Informationen: Der Name des Domänencontrollers, in diesem Fall co1-red-dc-33.domain.company.com

Schritt 2: Konfigurieren des KDC in „krb5.conf“

  • Ausführung: Linux/macOS

  • Aktion: Bearbeiten Sie /etc/krb5.conf in einem Editor Ihrer Wahl. Konfigurieren Sie die folgenden Schlüssel

    [libdefaults]
  default_realm = DOMAIN.COMPANY.COM

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

    Speichern Sie die krb5.conf-Datei, und beenden Sie den Vorgang

    Hinweis

    Die Domäne muss VOLLSTÄNDIG IN GROSSBUCHSTABEN angegeben werden.

Schritt 3: Testen des TGT-Abrufs
  • Ausführung: Linux/macOS
  • Aktion:
    • Verwenden Sie den Befehl kinit username@DOMAIN.COMPANY.COM, um ein TGT aus dem KDC abzurufen. Sie werden zur Eingabe Ihres Domänenkennworts aufgefordert.
    • Verwenden Sie klist, um die verfügbaren Tickets anzuzeigen. Wenn kinit erfolgreich war, sollten Sie ein Ticket von krbtgt/DOMAIN.COMPANY.COM@ DOMAIN.COMPANY.COM sehen.

Herstellen einer Verbindung im ActiveDirectoryPassword-Authentifizierungsmodus

Im folgenden Beispiel wird veranschaulicht, wie der Modus authentication=ActiveDirectoryPassword verwendet wird.

So erstellen Sie das Beispiel und führen es aus:

  1. Stellen Sie sicher, dass Sie abhängige Bibliotheken aus den Client-Setup-Anforderungen benötigen.

  2. Suchen Sie die folgenden Codezeilen, und ersetzen Sie die Server- und Datenbanknamen durch die Namen Ihres Servers und Ihrer Datenbank.

    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. Suchen Sie nach den folgenden Codezeilen. Ersetzen Sie den Benutzernamen durch den Namen des Microsoft Entra-Benutzers, mit dessen Identität Sie die Verbindung herstellen möchten.

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

Beispiel zur Verwendung des ActiveDirectoryPassword-Authentifizierungsmodus:

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

Wenn die Verbindung hergestellt wurde, sollte die folgende Meldung als Ausgabe angezeigt werden:

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

Herstellen einer Verbindung mithilfe des Authentifizierungsmodus „ActiveDirectoryInteractive“

Im folgenden Beispiel wird veranschaulicht, wie der Modus authentication=ActiveDirectoryInteractive verwendet wird.

So erstellen Sie das Beispiel und führen es aus:

  1. Stellen Sie sicher, dass Sie abhängige Bibliotheken aus den Client-Setup-Anforderungen benötigen.

  2. Suchen Sie die folgenden Codezeilen, und ersetzen Sie die Server- und Datenbanknamen durch die Namen Ihres Servers und Ihrer Datenbank.

    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. Suchen Sie nach den folgenden Codezeilen. Ersetzen Sie den Benutzernamen durch den Namen des Microsoft Entra-Benutzers, mit dessen Identität Sie die Verbindung herstellen möchten.

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

Beispiel zur Verwendung des ActiveDirectoryInteractive-Authentifizierungsmodus:

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

Wenn Sie das Programm ausführen, wird ein Browser zum Authentifizieren des Benutzers bzw. der Benutzerin angezeigt. Was genau angezeigt wird, hängt davon ab, wie Ihre Microsoft Entra ID-Instanz konfiguriert wurde. Sie enthält möglicherweise Aufforderungen zur Multi-Faktor-Authentifizierung für den Benutzernamen, das Kennwort, die PIN oder eine zweite Geräteauthentifizierung über ein Telefon. Wenn mehrere interaktive Authentifizierungsanforderungen im selben Programm ausgeführt werden, werden Ihnen bei anschließenden Anforderungen möglicherweise keine Eingabeaufforderungen mehr angezeigt, wenn die Authentifizierungsbibliothek ein zuvor zwischengespeichertes Authentifizierungstoken wiederverwenden kann.

Informationen darüber, wie Sie Microsoft Entra ID so konfigurieren, dass Multi-Faktor-Authentifizierung erforderlich ist, finden Sie unter Erste Schritte mit Multi-Faktor-Authentifizierung von Microsoft Entra in der Cloud.

Screenshots dieser Dialogfelder finden Sie unter Verwenden der Multi-Faktor-Authentifizierung von Microsoft Entra.

Wenn die Benutzerauthentifizierung erfolgreich abgeschlossen wurde, sollte die folgende Meldung im Browser angezeigt werden:

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

Diese Meldung weist lediglich darauf hin, dass die Benutzerauthentifizierung erfolgreich war, bedeutet jedoch nicht zwangsläufig, dass eine Verbindung mit dem Server hergestellt wurde. Wenn Sie zur Anwendung zurückkehren und die folgende Meldung angezeigt wird, wurde die Verbindung mit dem Server hergestellt:

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

Herstellen einer Verbindung im ActiveDirectoryServicePrincipal-Authentifizierungsmodus

Im folgenden Beispiel wird veranschaulicht, wie der Modus authentication=ActiveDirectoryServicePrincipal verwendet wird.

So erstellen Sie das Beispiel und führen es aus:

  1. Stellen Sie sicher, dass Sie abhängige Bibliotheken aus den Client-Setup-Anforderungen benötigen.

  2. Suchen Sie die folgenden Codezeilen, und ersetzen Sie die Server- und Datenbanknamen durch die Namen Ihres Servers und Ihrer Datenbank.

    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. Suchen Sie nach den folgenden Codezeilen. Ersetzen Sie den Wert von principalId durch die Anwendungs-ID/Client-ID des Microsoft Entra-Dienstprinzipals, mit dessen Identität Sie die Verbindung herstellen möchten. Ersetzen Sie den Wert von principalSecret durch das Geheimnis.

    String principalId = "1846943b-ad04-4808-aa13-4702d908b5c1"; // Replace with your Microsoft Entra service principal ID.
String principalSecret = "..."; // Replace with your Microsoft Entra principal secret.

  4. Legen Sie die Prinzipal-ID und das Prinzipalgeheimnis über setUser und setPassword in Version 10.2 und höher fest, sowie setAADSecurePrincipalId und setAADSecurePrincipalSecret in Version 9.4 und niedriger.

Beispiel zur Verwendung des ActiveDirectoryServicePrincipal-Authentifizierungsmodus:

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 = "1846943b-ad04-4808-aa13-4702d908b5c1"; // 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));
            }
        }
    }
}

Wenn eine Verbindung hergestellt wurde, sollte die folgende Meldung als Ausgabe angezeigt werden:

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

Herstellen einer Verbindung im ActiveDirectoryServicePrincipalCertificate-Authentifizierungsmodus

Im folgenden Beispiel wird veranschaulicht, wie der Modus authentication=ActiveDirectoryServicePrincipalCertificate verwendet wird.

So erstellen Sie das Beispiel und führen es aus:

  1. Stellen Sie sicher, dass Sie abhängige Bibliotheken aus den Client-Setup-Anforderungen benötigen.

  2. Suchen Sie die folgenden Codezeilen, und ersetzen Sie die Server- und Datenbanknamen durch die Namen Ihres Servers und Ihrer Datenbank.

    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. Suchen Sie nach den folgenden Codezeilen. Ersetzen Sie den Wert von principalId durch die Anwendungs-ID/Client-ID des Microsoft Entra-Dienstprinzipals, mit dessen Identität Sie die Verbindung herstellen möchten. Ersetzen Sie den Wert clientCertificate durch den Speicherort des Dienstprinzipalzertifikats.

    String principalId = "1846943b-ad04-4808-aa13-4702d908b5c1"; // Replace with your Microsoft Entra service principal ID.

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

  4. Wenn das oben genannte Zertifikat ein Kennwort benötigt, stellen Sie den Prinzipalschlüssel in setPassword Version 10.2 und höher oder setAADSecurePrincipalSecret in Version 9.4 und darunter ein.

  5. Wenn das obige Zertifikat über einen zugeordneten privaten Schlüssel verfügt, stellen Sie den privaten Schlüssel mithilfe von setClientKey ein. Wenn für diesen Schlüssel ein Kennwort erforderlich ist, stellen Sie das Kennwort für den privaten Schlüssel mithilfe von setClientKeyPassword ein.

Beispiel zur Verwendung des ActiveDirectoryServicePrincipalCertificate-Authentifizierungsmodus:

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 = "1846943b-ad04-4808-aa13-4702d908b5c1"; // 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));
            }
        }
    }
}

Wenn eine Verbindung hergestellt wurde, sollte die folgende Meldung als Ausgabe angezeigt werden:

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

Herstellen einer Verbindung über ein Zugriffstoken

Anwendungen und Dienste können ein Zugriffstoken aus Microsoft Entra ID abrufen und mit diesem eine Verbindung zu Azure SQL-Datenbank, Azure SQL Managed Instance und Azure Synapse Analytics herstellen.

Hinweis

accessToken kann nur über den Properties-Parameter der getConnection()-Methode in der DriverManager-Klasse festgelegt werden. Eine Verwendung in der Verbindungszeichenfolge ist nicht möglich. Ab der Treiberversion 12.2 können Benutzer*innen einen accessToken-Rückruf für den Treiber für die Tokenerneuerung in Verbindungspoolszenarios implementieren und bereitstellen. Verbindungspoolszenarios erfordern, dass die Verbindungspoolimplementierung die standardmäßigen JDBC-Verbindungspoolingklassen verwendet.

Das folgende Beispiel enthält eine einfache Java-Anwendung, die mithilfe der zugriffstokenbasierten Authentifizierung eine Verbindung zu Azure herstellt.

So erstellen Sie das Beispiel und führen es aus:

  1. Erstellt ein Anwendungskonto in Microsoft Entra ID für Ihren Dienst.

    1. Melden Sie sich beim Azure-Portal an.
    2. Gehen Sie zu Microsoft Entra ID in der linken Navigationsleiste.
    3. Wählen Sie App-Registrierungen aus.
    4. Wählen Sie Neue Registrierung aus.
    5. Geben Sie mytokentest als Anzeigenamen für die Anwendung ein.
    6. Belassen Sie die Standardauswahl für unterstützte Kontotypen, die die Anwendung verwenden können.
    7. Wählen Sie unten Registrieren aus.
    8. Sie benötigen keine Anmelde-URL, geben Sie etwas Beliebiges an: https://mytokentest.
    9. Wählen Sie unten Create aus.
    10. Wenn Sie Registrieren auswählen, wird die App sofort erstellt, und Sie gelangen zur Ressourcenseite.
    11. Suchen Sie im Feld Essentials die Anwendungs-ID (Client-ID) und kopieren Sie sie. Sie benötigen diesen Wert später beim Konfigurieren Ihrer Anwendung.
    12. Wählen Sie im Navigationsbereich Zertifikate und geheime Schlüssel aus. Wählen Sie auf der Registerkarte Geheime Clientschlüssel (0) die Option Neuer geheimer Clientschlüssel aus. Geben Sie eine Beschreibung für den geheimen Schlüssel ein und wählen Sie das Ablaufdatum aus (Standard ist in Ordnung). Wählen Sie unten Hinzufügen aus. Wichtig: Bevor Sie diese Seite verlassen, kopieren Sie den generierten Wert für Ihren geheimen Clientschlüssel. Nach dem Verlassen der Seite kann er nicht mehr angezeigt werden. Dieser Wert ist der geheime Clientschlüssel.
    13. Kehren Sie zum Bereich App-Registrierungen für Microsoft Entra ID zurück und suchen Sie die Registerkarte Endpunkte. Kopieren Sie die URL unter OAuth 2.0 token endpoint. Dies ist Ihre STS-URL.

    Azure Portal App Registration End Point - STS URL

  2. Stellen Sie als Microsoft Entra-Administrator eine Verbindung zu Ihrer Datenbank her und verwenden Sie einen T-SQL-Befehl, um einen eigenständigen Datenbankbenutzer für Ihren Anwendungsprinzipal bereitzustellen. Weitere Informationen zum Erstellen eines Microsoft Entra-Administrators und eines eigenständigen Datenbankbenutzers finden Sie unter Herstellen einer Verbindung mithilfe der Microsoft Entra-Authentifizierung.

    CREATE USER [mytokentest] FROM EXTERNAL PROVIDER

  3. Laden Sie auf dem Clientcomputer, auf dem Sie das Beispiel ausführen möchten, die Bibliothek Microsoft Authentication Library (MSAL) für Java und die zugehörigen Abhängigkeiten herunter. MSAL ist nur zum Ausführen dieses spezifischen Beispiels erforderlich. Das Beispiel verwendet die APIs aus dieser Bibliothek, um das Zugriffstoken aus Microsoft Entra ID abzurufen. Wenn Sie bereits über ein Zugriffstoken verfügen, können Sie diesen Schritt überspringen und den Abschnitt im Beispiel entfernen, in dem ein Zugriffstoken abgerufen wird.

Ersetzen Sie im folgenden Beispiel die Werte für die STS-URL, die Client-ID, das Clientgeheimnis, sowie den Server und den Datenbanknamen durch Ihre eigenen Werte.

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 = "1846943b-ad04-4808-aa13-4702d908b5c1"; // 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));
            }
        }
    }
}

Wenn die Verbindung erfolgreich hergestellt wurde, sollte die folgende Meldung als Ausgabe angezeigt werden:

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

Herstellen einer Verbindung über einen Zugriffstokenrückruf

Wie bei der Zugriffstokeneigenschaft ermöglicht der Zugriffstokenrückruf die Registrierung einer Methode, die dem Treiber ein Zugriffstoken bereitstellt. Der Vorteil dieses Rückrufs gegenüber der Eigenschaft besteht darin, dass der Rückruf dem Treiber ermöglicht, ein neues Zugriffstoken anzufordern, wenn das Token abgelaufen ist. So kann beispielsweise ein Verbindungspool, der eine neue Verbindung erstellt, ein neues Token mit ein neues Datum des Ablaufs anfordern. Weitere Informationen finden Sie unter Verwenden des Verbindungspoolings.

Im folgenden Beispiel wird das Implementieren und Festlegen des accessToken-Rückrufs veranschaulicht.

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 = "1846943b-ad04-4808-aa13-4702d908b5c1"; // 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));
            }
        }
    }
}

Wenn die Verbindung erfolgreich hergestellt wurde, sollte die folgende Meldung als Ausgabe angezeigt werden:

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

Ab Version 12.4 kann der accessToken-Rückruf über die accessTokenCallbackClass Verbindungszeichen-Folgeneigenschaft festgelegt werden. Das folgende Beispiel zeigt, wie accessToken-Rückruf mithilfe dieser Eigenschaft eingestellt wird:

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 = "1846943b-ad04-4808-aa13-4702d908b5c1"; // 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));
            }
        }
    }
}

Wenn die Verbindung erfolgreich hergestellt wurde, sollte die folgende Meldung als Ausgabe angezeigt werden:

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

Nächste Schritte

Weitere Informationen zu verwandten Konzepten finden Sie in den folgenden Artikeln: