Koneksi menggunakan autentikasi Microsoft Entra

Artikel
01/31/2024

Artikel ini menyediakan informasi tentang cara mengembangkan aplikasi Java yang menggunakan fitur autentikasi Microsoft Entra dengan Microsoft JDBC Driver untuk SQL Server.

Anda dapat menggunakan autentikasi Microsoft Entra, yang merupakan mekanisme untuk menyambungkan ke Azure SQL Database, Azure SQL Manged Instance, dan Azure Synapse Analytics menggunakan identitas di ID Microsoft Entra. Gunakan autentikasi Microsoft Entra untuk mengelola identitas pengguna database secara terpusat dan sebagai alternatif untuk autentikasi SQL Server. Driver JDBC memungkinkan Anda menentukan kredensial Microsoft Entra Anda di string koneksi JDBC untuk menyambungkan ke Azure SQL. Untuk informasi tentang cara mengonfigurasi autentikasi Microsoft Entra, kunjungi Koneksi ke Azure SQL Dengan Menggunakan autentikasi Microsoft Entra.

properti Koneksi ion untuk mendukung autentikasi Microsoft Entra di Microsoft JDBC Driver for SQL Server adalah:

autentikasi: Gunakan properti ini untuk menunjukkan metode autentikasi SQL mana yang akan digunakan untuk koneksi. Nilai yang mungkin adalah:
- ActiveDirectoryManagedIdentity
  - Karena driver versi 8.3.1, authentication=ActiveDirectoryMSI dapat digunakan untuk menyambungkan ke Azure SQL Database/Synapse Analytics dari Sumber Daya Azure dengan dukungan "Identitas" diaktifkan. Secara opsional, msiClientId dapat ditentukan di properti Koneksi ion/DataSource bersama dengan mode autentikasi ini. msiClientId harus berisi ID Klien identitas terkelola yang akan digunakan untuk memperoleh accessToken untuk membuat koneksi. Karena driver versi v12.2, authentication=ActiveDirectoryManagedIdentity juga dapat digunakan untuk menyambungkan ke Azure SQL Database/Synapse Analytics dari Sumber Daya Azure dengan dukungan "Identitas" diaktifkan. Secara opsional, ID Klien identitas terkelola sekarang juga dapat diatur di user properti . Untuk informasi selengkapnya, lihat Koneksi menggunakan mode autentikasi ActiveDirectoryManagedIdentity.
- ActiveDirectoryDefault
  - Karena driver versi 12.2, authentication=ActiveDirectoryDefault dapat digunakan untuk menyambungkan ke Azure SQL/Synapse Analytics melalui DefaultAzureCredential dari pustaka klien Azure Identity. Untuk informasi selengkapnya, lihat Koneksi menggunakan mode autentikasi ActiveDirectoryDefault.
- ActiveDirectoryIntegrated
  - Karena driver versi 6.0, authentication=ActiveDirectoryIntegrated dapat digunakan untuk menyambungkan ke Azure SQL/Synapse Analytics melalui autentikasi terintegrasi. Untuk menggunakan mode autentikasi ini, Anda harus menggabungkan Active Directory lokal Federation Services (ADFS) dengan ID Microsoft Entra di cloud. Setelah disiapkan, Anda dapat terhubung dengan menambahkan pustaka mssql-jdbc_auth-<version>-<arch>.dll asli ke jalur kelas aplikasi di Windows, atau dengan menyiapkan tiket Kerberos untuk dukungan autentikasi lintas platform. Anda dapat mengakses Azure SQL/Azure Synapse Analytics tanpa dimintai kredensial saat Anda masuk ke komputer yang bergabung dengan domain. Untuk informasi selengkapnya, lihat Koneksi menggunakan mode autentikasi ActiveDirectoryIntegrated.
- ActiveDirectoryPassword
  - Karena driver versi 6.0, authentication=ActiveDirectoryPassword dapat digunakan untuk menyambungkan ke Azure SQL/Synapse Analytics dengan nama pengguna dan kata sandi Microsoft Entra. Untuk informasi selengkapnya, lihat Koneksi menggunakan mode autentikasi ActiveDirectoryPassword.
- ActiveDirectoryInteractive
  - Karena driver versi 9.2, authentication=ActiveDirectoryInteractive dapat digunakan untuk menyambungkan ke Azure SQL/Synapse Analytics melalui alur autentikasi interaktif (autentikasi multifaktor). Untuk informasi selengkapnya, lihat Koneksi menggunakan mode autentikasi ActiveDirectoryInteractive.
- ActiveDirectoryServicePrincipal
  - Karena driver versi 9.2, authentication=ActiveDirectoryServicePrincipal dapat digunakan untuk menyambungkan ke Azure SQL/Synapse Analytics dengan menentukan ID aplikasi/klien di properti userName dan rahasia identitas perwakilan layanan di properti kata sandi. Untuk informasi selengkapnya, lihat Koneksi menggunakan mode autentikasi ActiveDirectoryServicePrincipal.
- ActiveDirectoryServicePrincipalCertificate
  - Karena driver versi 12.4, authentication=ActiveDirectoryServicePrincipalCertificate dapat digunakan untuk menyambungkan ke Azure SQL Database/Synapse Analytics dengan menentukan ID aplikasi/klien di properti userName dan lokasi sertifikat Perwakilan Layanan di clientCertificate properti . Untuk informasi selengkapnya, lihat Koneksi menggunakan mode autentikasi ActiveDirectoryServicePrincipalCertificate.
- SqlPassword
  - Gunakan authentication=SqlPassword untuk menyambungkan ke SQL Server menggunakan properti userName/user dan password.
- Tidak Ditentukan
  - Gunakan authentication=NotSpecified atau biarkan sebagai default ketika tidak ada metode autentikasi ini yang diperlukan.
- accessToken: Gunakan properti koneksi ini untuk menyambungkan ke SQL Database dengan token akses. accessToken hanya dapat diatur menggunakan parameter Properti metode getConnection() di kelas DriverManager. Ini tidak dapat digunakan dalam URL koneksi.

Untuk informasi selengkapnya, lihat properti autentikasi di halaman Mengatur Properti Koneksi ion.

Persyaratan penyiapan klien

Selain persyaratan Sistem driver dasar, mode autentikasi berikut memiliki lebih banyak persyaratan.

Tabel berikut mencantumkan dependensi pustaka yang diperlukan untuk setiap mode autentikasi dan versi driver. Dependensi dependensi juga diperlukan.

Opsi autentikasi	Versi driver	Dependensi pustaka
`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`l4j 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` `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

Koneksi menggunakan mode autentikasi ActiveDirectoryManagedIdentity

Mode autentikasi ini didukung dimulai dengan versi 7.2. Untuk menggunakannya, tentukan authentication=ActiveDirectoryMSI. Mulai versi 12.2, authentication=ActiveDirectoryManagedIdentity juga dapat ditentukan.

Selain persyaratan dependensi pustaka yang tercantum dalam Persyaratan penyiapan klien, fitur ini memiliki persyaratan berikut:

Database target harus memiliki pengguna database mandiri, dengan izin CONNECT. Pengguna yang terkandung harus mewakili Identitas Terkelola yang Ditetapkan Sistem Azure Resource atau Identitas Terkelola yang Ditetapkan Pengguna, atau salah satu grup milik Identitas Terkelola Anda.

Lingkungan klien harus menjadi Sumber Daya Azure dan harus mengaktifkan dukungan fitur "Identitas". Tabel berikut ini mencantumkan layanan Azure yang didukung oleh setiap versi driver JDBC:

Versi driver	Dependensi yang diperlukan	Layanan Azure didukung
7.2 - 11.2	Tidak	Azure App Service dan Azure Functions Azure Virtual Machines
12,2 12.4 12.6	azure-identity 1.7.0 azure-identity 1.9.0 azure-identity 1.11.1	Azure App Service dan Azure Functions Azure Arc Azure Cloud Shell Azure Kubernetes Service Azure Service Fabric Azure Virtual Machines Set Skala Azure Virtual Machines

Contoh berikut menunjukkan cara menggunakan authentication=ActiveDirectoryManagedIdentity mode. Jalankan contoh ini dari dalam Sumber Daya Azure yang dikonfigurasi untuk Identitas Terkelola.

Ganti nama server/database dengan nama server/database Anda di baris berikut untuk menjalankan contoh:

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

Contoh untuk menggunakan ActiveDirectoryMSI mode autentikasi:

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

Contoh berikut menunjukkan cara menggunakan authentication=ActiveDirectoryManagedIdentity mode.

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

Contoh-contoh pada Azure Virtual Machine ini mengambil token akses dari Identitas Terkelola yang Ditetapkan Sistem atau Identitas Terkelola yang Ditetapkan Pengguna (jika msiClientId atau user ditentukan dengan ID Klien Identitas Terkelola) dan membuat koneksi menggunakan token akses yang diambil. Jika koneksi dibuat, Anda akan melihat pesan berikut:

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

Koneksi menggunakan mode autentikasi ActiveDirectoryDefault

Opsi ActiveDirectoryDefault autentikasi menggunakan implementasi berantai TokenCredential pustaka DefaultAzureCredential klien Azure Identity. Kredensial menggabungkan metode autentikasi yang umum digunakan yang ditautkan bersama-sama.

ActiveDirectoryDefault autentikasi memerlukan dependensi run time pada pustaka klien Azure Identity untuk Identitas Terkelola. Untuk detail versi pustaka, lihat Persyaratan penyiapan klien.

Tabel berikut mencantumkan DefaultAzureCredential rantai kredensial untuk setiap versi driver JDBC.

Versi driver	dokumen versi azure-identity	`DefaultAzureCredential` Jaringan
12,2	azure-identity 1.7.0	Lingkungan Identitas Terkelola IntelliJ Azure CLI Azure PowerShell
12.4	azure-identity 1.9.0	Lingkungan Identitas Beban Kerja Identitas Terkelola Azure Developer CLI IntelliJ Azure CLI Azure PowerShell
12.6	azure-identity 1.11.1	Lingkungan Identitas Beban Kerja Identitas Terkelola Azure Developer CLI IntelliJ Azure CLI Azure PowerShell

Ada banyak variabel yang dapat diatur untuk mengonfigurasi Environment kredensial. Untuk detail tentang mengonfigurasi DefaulAzureCredential rantai, termasuk Environment kredensial, lihat versi dokumen identitas azure yang relevan yang ditautkan dalam tabel sebelumnya.

Untuk menggunakan IntellijCredential pada Windows, atur variabel INTELLIJ_KEEPASS_PATH lingkungan ke lokasi file Anda keepass . Contohnya, INTELLIJ_KEEPASS_PATH=C:\user\your\path\to\the\keepass\file.

Untuk menyediakan lebih banyak penyewa ke DefaultAzureCredential, gunakan ADDITIONALLY_ALLOWED_TENANTS variabel lingkungan. Variabel ini mengambil daftar yang dibatasi koma. Misalnya: ADDITIONALLY_ALLOWED_TENANTS=<your-tenant-id-0>,<your-tenant-id-1>,<your-tenant-id-2>,...

Contoh berikut menunjukkan cara menggunakan authentication=ActiveDirectoryDefault mode dengan AzureCliCredential dalam DefaultAzureCredential.

Pertama masuk ke Azure CLI dengan perintah berikut.
```
az login
```

Setelah berhasil masuk ke Azure CLI, jalankan kode berikut.

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

Koneksi menggunakan mode autentikasi ActiveDirectoryIntegrated

Ada dua cara untuk menggunakan ActiveDirectoryIntegrated autentikasi di Driver Microsoft JDBC untuk SQL Server:

Pada Windows, mssql-jdbc_auth-<version>-<arch>.dll dari paket yang diunduh dapat disalin ke lokasi di jalur sistem.
Jika Anda tidak dapat menggunakan DLL, dimulai dengan versi 6.4, Anda dapat mengonfigurasi tiket Kerberos. Metode ini didukung di seluruh platform (Windows, Linux, dan macOS). Untuk informasi selengkapnya, lihat Mengatur tiket Kerberos di Windows, Linux, dan macOS.

Pastikan Anda memiliki pustaka dependen yang diperlukan dari persyaratan penyiapan Klien.

Contoh berikut menunjukkan cara menggunakan authentication=ActiveDirectoryIntegrated mode. Contoh ini berjalan pada komputer yang bergabung dengan domain yang digabungkan dengan ID Microsoft Entra. Pengguna database yang mewakili pengguna Windows Anda harus ada di database dan harus memiliki izin CONNECT.

Ganti nama server/database dengan nama server/database Anda di baris berikut sebelum menjalankan contoh:

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

Contoh untuk menggunakan mode autentikasi 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));
            }
        }
    }
}

Menjalankan contoh ini secara otomatis menggunakan tiket Kerberos Anda dari platform klien dan tidak diperlukan kata sandi. Jika koneksi dibuat, Anda akan melihat pesan berikut:

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

Mengatur tiket Kerberos di Windows, Linux, dan macOS

Anda harus menautkan tiket Kerberos untuk menautkan pengguna Anda saat ini ke akun domain Windows. Berikut ini adalah ringkasan langkah-langkah utama.

Windows

Catatan

Di Windows, mssql-jdbc_auth-<version>-<arch>.dll dari paket yang diunduh dapat digunakan alih-alih langkah konfigurasi Kerberos ini. Langkah-langkah ini hanya diperlukan jika Anda tidak dapat menggunakan DLL.

JDK dilengkapi dengan kinit, yang dapat Anda gunakan untuk mendapatkan TGT dari Key Distribution Center (KDC) pada mesin gabungan domain yang digabungkan dengan ID Microsoft Entra.

Langkah 1: Pengambilan tiket pemberian tiket

Jalankan pada: Windows
Tindakan:
- Gunakan perintah kinit username@DOMAIN.COMPANY.COM untuk mendapatkan TGT dari KDC, lalu perintah meminta kata sandi domain Anda.
- Gunakan klist untuk melihat tiket yang tersedia. Jika kinit berhasil, Anda akan melihat tiket dari krbtgt/DOMAIN.COMPANY.COM@ DOMAIN.COMPANY.COM.
Catatan

Anda mungkin harus menentukan .ini file dengan -Djava.security.krb5.conf aplikasi Anda untuk menemukan KDC.

Linux dan macOS

Persyaratan

Akses ke komputer yang bergabung dengan domain Windows untuk mengkueri Pengendali Domain Kerberos Anda.

Langkah 1: Temukan Kerberos KDC

Jalankan pada: Baris perintah Windows
Tindakan: nltest /dsgetdc:DOMAIN.COMPANY.COM (di mana DOMAIN.COMPANY.COM memetakan ke nama domain Anda)

Output sampel

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

Informasi untuk mengekstrak Nama DC, dalam hal ini co1-red-dc-33.domain.company.com

Langkah 2: Mengonfigurasi KDC di krb5.conf

Jalankan pada: Linux/macOS
Tindakan: Edit /etc/krb5.conf di editor pilihan Anda. Konfigurasikan kunci berikut
```
[libdefaults]
  default_realm = DOMAIN.COMPANY.COM

[realms]
DOMAIN.COMPANY.COM = {
   kdc = co1-red-dc-28.domain.company.com
}
```
Kemudian simpan krb5.conf file dan keluar

Catatan

Domain harus berada di SEMUA CAPS.

Langkah 3: Uji pengambilan tiket yang memberikan tiket

Jalankan pada: Linux/macOS
Tindakan:
- Gunakan perintah kinit username@DOMAIN.COMPANY.COM untuk mendapatkan TGT dari KDC, lalu perintah meminta kata sandi domain Anda.
- Gunakan klist untuk melihat tiket yang tersedia. Jika kinit berhasil, Anda akan melihat tiket dari krbtgt/DOMAIN.COMPANY.COM@ DOMAIN.COMPANY.COM.

Koneksi menggunakan mode autentikasi ActiveDirectoryPassword

Contoh berikut menunjukkan cara menggunakan authentication=ActiveDirectoryPassword mode.

Untuk membangun dan menjalankan contoh:

Pastikan Anda memiliki pustaka dependen yang diperlukan dari persyaratan penyiapan Klien.

Temukan baris kode berikut dan ganti nama server/database dengan nama server/database Anda.

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

Temukan baris kode berikut. Ganti nama pengguna dengan nama pengguna Microsoft Entra yang ingin Anda sambungkan.

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

Contoh untuk menggunakan ActiveDirectoryPassword mode autentikasi:

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

Jika koneksi dibuat, Anda akan melihat pesan berikut sebagai output:

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

Koneksi menggunakan mode autentikasi ActiveDirectoryInteractive

Contoh berikut menunjukkan cara menggunakan authentication=ActiveDirectoryInteractive mode.

Untuk membangun dan menjalankan contoh:

Pastikan Anda memiliki pustaka dependen yang diperlukan dari persyaratan penyiapan Klien.

Temukan baris kode berikut dan ganti nama server/database dengan nama server/database Anda.

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

Temukan baris kode berikut. Ganti nama pengguna dengan nama pengguna Microsoft Entra yang ingin Anda sambungkan.
```
ds.setUser("bob@example.com"); // replace with your user name
```

Contoh untuk menggunakan ActiveDirectoryInteractive mode autentikasi:

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

Saat Anda menjalankan program, browser ditampilkan untuk mengautentikasi pengguna. Persis apa yang Anda lihat tergantung pada bagaimana ID Microsoft Entra Anda telah dikonfigurasi. Ini mungkin atau mungkin tidak menyertakan permintaan autentikasi multifaktor untuk nama pengguna, kata sandi, PIN, atau autentikasi perangkat kedua melalui telepon. Jika beberapa permintaan autentikasi interaktif dilakukan dalam program yang sama, permintaan selanjutnya mungkin bahkan tidak meminta Anda jika pustaka autentikasi dapat menggunakan kembali token autentikasi yang di-cache sebelumnya.

Untuk informasi tentang cara mengonfigurasi ID Microsoft Entra untuk memerlukan autentikasi multifaktor, lihat Mulai menggunakan autentikasi multifaktor Microsoft Entra di cloud.

Untuk cuplikan layar kotak dialog ini, lihat Menggunakan autentikasi multifaktor Microsoft Entra.

Jika autentikasi pengguna berhasil diselesaikan, Anda akan melihat pesan berikut di browser:

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

Pesan ini hanya menunjukkan bahwa autentikasi pengguna berhasil tetapi belum tentu koneksi yang berhasil ke server. Setelah kembali ke aplikasi, jika koneksi dibuat ke server, Anda akan melihat pesan berikut sebagai output:

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

Koneksi menggunakan mode autentikasi ActiveDirectoryServicePrincipal

Contoh berikut menunjukkan cara menggunakan authentication=ActiveDirectoryServicePrincipal mode.

Untuk membangun dan menjalankan contoh:

Pastikan Anda memiliki pustaka dependen yang diperlukan dari persyaratan penyiapan Klien.

Temukan baris kode berikut dan ganti nama server/database dengan nama server/database Anda.

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

Temukan baris kode berikut. Ganti nilai principalId dengan ID Aplikasi/ID Klien perwakilan layanan Microsoft Entra yang ingin Anda sambungkan. Ganti nilai principalSecret dengan rahasia.

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

Atur ID utama dan rahasia utama menggunakan setUser dan setPassword di versi 10.2 dan yang lebih baru, dan setAADSecurePrincipalIdsetAADSecurePrincipalSecret dalam versi 9.4 ke bawah.

Contoh untuk menggunakan ActiveDirectoryServicePrincipal mode autentikasi:

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

Jika koneksi dibuat, Anda akan melihat pesan berikut sebagai output:

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

Koneksi menggunakan mode autentikasi ActiveDirectoryServicePrincipalCertificate

Contoh berikut menunjukkan cara menggunakan authentication=ActiveDirectoryServicePrincipalCertificate mode.

Untuk membangun dan menjalankan contoh:

Pastikan Anda memiliki pustaka dependen yang diperlukan dari persyaratan penyiapan Klien.

Temukan baris kode berikut dan ganti nama server/database dengan nama server/database Anda.

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

Temukan baris kode berikut. Ganti nilai principalId dengan ID Aplikasi/ID Klien perwakilan layanan Microsoft Entra yang ingin Anda sambungkan. Ganti nilai clientCertificate dengan lokasi sertifikat perwakilan layanan.

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.

Jika sertifikat di atas memerlukan kata sandi, atur Rahasia utama menggunakan setPassword di versi 10.2 ke atas atau setAADSecurePrincipalSecret di versi 9.4 ke bawah.
Jika sertifikat di atas memiliki kunci privat terkait, atur kunci privat menggunakan setClientKey. Jika kunci ini memerlukan kata sandi, atur kata sandi untuk kunci privat menggunakan setClientKeyPassword.

Contoh untuk menggunakan ActiveDirectoryServicePrincipalCertificate mode autentikasi:

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

Jika koneksi dibuat, Anda akan melihat pesan berikut sebagai output:

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

Koneksi menggunakan token akses

Aplikasi/layanan dapat mengambil token akses dari MICROSOFT Entra ID dan menggunakannya untuk menyambungkan ke Azure SQL Database, Azure SQL Managed Instance, dan Azure Synapse Analytics.

Catatan

accessToken hanya dapat diatur menggunakan parameter Properti metode getConnection() di kelas DriverManager. Ini tidak dapat digunakan dalam string koneksi. Dimulai dengan driver versi 12.2, pengguna dapat menerapkan dan memberikan accessToken panggilan balik ke driver untuk perpanjangan token dalam skenario pengumpulan koneksi. skenario pengumpulan Koneksi ion memerlukan implementasi kumpulan koneksi untuk menggunakan standar Kelas pengumpulan koneksi JDBC.

Contoh berikut berisi aplikasi Java sederhana yang tersambung ke Azure menggunakan autentikasi berbasis token akses.

Untuk membangun dan menjalankan contoh:

Buat akun aplikasi di ID Microsoft Entra untuk layanan Anda.
1. Masuk ke portal Azure.
2. Buka ID Microsoft Entra di navigasi sebelah kiri.
3. Pilih Pendaftaran aplikasi.
4. Pilih Pendaftaran baru.
5. Masukkan mytokentest sebagai nama yang mudah diingat untuk aplikasi.
6. Biarkan pilihan default untuk jenis akun yang didukung yang dapat menggunakan aplikasi.
7. Pilih Daftar di bagian bawah.
8. Tidak memerlukan URL MASUK, berikan apa pun: https://mytokentest.
9. Pilih Create di bagian bawah.
10. Setelah memilih Daftarkan aplikasi segera dibuat dan Anda dibawa ke halaman sumber dayanya.
11. Dalam kotak Esensial , temukan ID Aplikasi (klien) dan salin. Anda memerlukan nilai ini nanti untuk mengonfigurasi aplikasi Anda.
12. Pilih Sertifikat & rahasia dari panel navigasi. Pada tab Rahasia klien (0), pilih Rahasia klien baru. Masukkan deskripsi untuk rahasia dan pilih kedaluwarsa (defaultnya baik-baik saja). Pilih Tambahkan di bagian bawah. Penting sebelum meninggalkan halaman ini, salin Nilai yang dihasilkan untuk rahasia klien Anda- ini tidak dapat dilihat setelah meninggalkan halaman. Nilai ini adalah rahasia klien.
13. Kembali ke panel Pendaftaran aplikasi untuk MICROSOFT Entra ID dan temukan tab Titik Akhir. Salin URL di bawah OAuth 2.0 token endpoint, ini adalah URL STS Anda.
Koneksi ke database Anda sebagai admin Microsoft Entra dan gunakan perintah T-SQL untuk menyediakan pengguna database mandiri untuk prinsipal aplikasi Anda. Untuk informasi selengkapnya tentang cara membuat admin Microsoft Entra dan pengguna database mandiri, lihat Koneksi dengan menggunakan autentikasi Microsoft Entra.
```
CREATE USER [mytokentest] FROM EXTERNAL PROVIDER
```
Pada komputer klien tempat Anda menjalankan contoh, unduh Pustaka Autentikasi Microsoft (MSAL) untuk pustaka Java dan dependensinya. MSAL hanya diperlukan untuk menjalankan contoh spesifik ini. Contoh menggunakan API dari pustaka ini untuk mengambil token akses dari ID Microsoft Entra. Jika Anda sudah memiliki token akses, Anda dapat melewati langkah ini dan menghapus bagian dalam contoh yang mengambil token akses.

Dalam contoh berikut, ganti URL STS, ID Klien, Rahasia Klien, server, dan nama database dengan nilai Anda.

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

Jika koneksi berhasil, Anda akan melihat pesan berikut sebagai output:

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

Koneksi menggunakan panggilan balik token akses

Seperti properti token akses, panggilan balik token akses memungkinkan Anda mendaftarkan metode yang menyediakan token akses ke driver. Manfaat dari panggilan balik ini melalui properti adalah panggilan balik memungkinkan driver untuk meminta token akses baru ketika token kedaluwarsa. Misalnya, kumpulan koneksi yang membuat koneksi baru dapat meminta token baru dengan tanggal kedaluwarsa baru. Untuk informasi selengkapnya, lihat Menggunakan pengumpulan koneksi.

Contoh berikut menunjukkan penerapan dan pengaturan panggilan balik 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 = "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));
            }
        }
    }
}

Jika koneksi berhasil, Anda akan melihat pesan berikut sebagai output:

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

Mulai dari versi 12.4, accessToken panggilan balik dapat diatur melalui accessTokenCallbackClass properti string koneksi. Contoh berikut menunjukkan cara mengatur accessToken panggilan balik menggunakan properti ini:

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

Jika koneksi berhasil, Anda akan melihat pesan berikut sebagai output:

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

Langkah berikutnya

Pelajari selengkapnya tentang konsep terkait dalam artikel berikut:

Koneksi menggunakan autentikasi Microsoft Entra

Persyaratan penyiapan klien

Koneksi menggunakan mode autentikasi ActiveDirectoryManagedIdentity

Koneksi menggunakan mode autentikasi ActiveDirectoryDefault

Koneksi menggunakan mode autentikasi ActiveDirectoryIntegrated

Mengatur tiket Kerberos di Windows, Linux, dan macOS

Windows

Langkah 1: Pengambilan tiket pemberian tiket

Linux dan macOS

Persyaratan

Langkah 1: Temukan Kerberos KDC

Langkah 2: Mengonfigurasi KDC di krb5.conf

Langkah 3: Uji pengambilan tiket yang memberikan tiket

Koneksi menggunakan mode autentikasi ActiveDirectoryPassword

Koneksi menggunakan mode autentikasi ActiveDirectoryInteractive

Koneksi menggunakan mode autentikasi ActiveDirectoryServicePrincipal

Koneksi menggunakan mode autentikasi ActiveDirectoryServicePrincipalCertificate

Koneksi menggunakan token akses

Koneksi menggunakan panggilan balik token akses

Langkah berikutnya

Saran dan Komentar

Saran dan Komentar

Sumber Daya Tambahan: