Menggunakan MICROSOFT Entra ID dengan Driver ODBC

Unduh driver ODBC

Catatan

Meskipun MICROSOFT Entra ID adalah nama baru untuk Azure Active Directory (Azure AD), untuk mencegah mengganggu lingkungan yang ada, Azure AD masih tetap berada di beberapa elemen yang dikodekan secara permanen seperti bidang UI, penyedia koneksi, kode kesalahan, dan cmdlet. Dalam artikel ini, dua nama tersebut dapat dipertukarkan.

Tujuan

Driver Microsoft ODBC untuk SQL Server versi 13.1 ke atas memungkinkan aplikasi ODBC tersambung ke Azure SQL Database atau Azure SQL Managed Instance menggunakan identitas di ID Microsoft Entra. Autentikasi dapat dilakukan dengan nama pengguna dan kata sandi, token akses Microsoft Entra, identitas terkelola Microsoft Entra (17.3+), atau Autentikasi Windows Terintegrasi di lingkungan gabungan yang bergabung dengan domain (17.6+ di Linux/macOS). Untuk Driver ODBC versi 13.1, autentikasi token akses Microsoft Entra hanya tersedia untuk sistem operasi Windows. Driver ODBC versi 17 ke atas mendukung autentikasi ini di semua platform (Windows, Linux, dan macOS). Metode autentikasi interaktif Microsoft Entra baru, yang mendukung autentikasi multifaktor, diperkenalkan dalam Driver ODBC versi 17.1 untuk Windows. Metode autentikasi identitas terkelola Microsoft Entra baru ditambahkan di Driver ODBC versi 17.3.1.1 untuk identitas terkelola yang ditetapkan sistem dan ditetapkan pengguna. Semua opsi ini dicapai dengan menggunakan kata kunci DSN dan string koneksi baru, dan atribut koneksi.

Untuk menggunakan autentikasi Microsoft Entra, Anda harus mengonfigurasi sumber data Azure SQL Anda. Untuk informasi selengkapnya, lihat Mengonfigurasi dan mengelola autentikasi Microsoft Entra dengan Azure SQL.

Catatan

Driver ODBC di Linux dan macOS sebelum versi 17.6 hanya mendukung autentikasi Microsoft Entra langsung terhadap ID Microsoft Entra. Jika Anda menggunakan autentikasi nama pengguna/kata sandi Microsoft Entra dari klien Linux atau macOS dan konfigurasi Microsoft Entra Anda mengharuskan klien untuk mengautentikasi terhadap titik akhir Microsoft Entra Federation Services, autentikasi mungkin gagal. Pada driver versi 17.6, batasan ini telah dihapus.

Kata Kunci DSN dan String Koneksi yang Baru dan/atau Dimodifikasi

Kata Authentication kunci dapat digunakan saat menyambungkan dengan DSN atau string koneksi untuk mengontrol modus autentikasi. Nilai yang ditetapkan dalam string koneksi menggantikan nilai dalam pengaturan DSN, jika disediakan. Nilai pra-atribut dari pengaturan Authentication adalah nilai yang dihitung dari string koneksi dan nilai DSN.

Nama	Nilai/Default	Deskripsi
Authentication	(not set)(default), (empty string), SqlPassword, ActiveDirectoryIntegratedActiveDirectoryInteractive, ActiveDirectoryMsi, ActiveDirectoryServicePrincipal, ActiveDirectoryPassword [DEPRECATED]	Mengontrol mode autentikasi. (not set) - Mode autentikasi ditentukan oleh kata kunci lain (opsi koneksi warisan yang ada.) (empty string) - (Hanya untuk string koneksi.) Timpa dan hapus nilai yang diatur dalam DSN. SqlPassword - Langsung autentikasi ke SQL menggunakan nama pengguna dan kata sandi. ActiveDirectoryIntegrated - Windows, dan Linux/Mac 17.6+, hanya driver. Autentikasi menggunakan kredensial Windows yang difederasikan melalui Microsoft Entra ID dengan autentikasi terintegrasi. ActiveDirectoryInteractive - Driver Windows saja. Autentikasi dengan identitas Microsoft Entra menggunakan autentikasi interaktif. ActiveDirectoryMsi - Mengautentikasi dengan identitas terkelola Microsoft Entra. Untuk identitas yang ditetapkan pengguna, atur UID ke ID klien identitas untuk Azure App Service atau Azure Container Instance; jika tidak, gunakan ID objeknya. Untuk identitas yang ditetapkan sistem, UID tidak diperlukan. ActiveDirectoryServicePrincipal - (17.7+) Autentikasi dengan perwakilan layanan Microsoft Entra. UID diatur ke ID klien prinsipal layanan. PWD diatur ke rahasia klien. ActiveDirectoryPassword - [TIDAK DIGUNAKAN LAGI] Autentikasi dengan identitas Microsoft Entra menggunakan nama pengguna dan kata sandi. ActiveDirectoryPassword tidak digunakan lagi. Untuk informasi selengkapnya, lihat ActiveDirectoryPassword tidak digunakan lagi.
Encrypt	(not set)(default), Yes/Mandatory(18.0+),No/Optional (18.0+), Strict(18.0+)	Mengontrol enkripsi untuk koneksi. Jika nilai pra-nilai atribut dari pengaturan Authentication bukan none dalam DSN atau string koneksi, defaultnya adalah Yes. Defaultnya juga Yes dalam versi 18.0.1+. Jika tidak, defaultnya adalah No. Jika atribut SQL_COPT_SS_AUTHENTICATION menggantikan nilai pra-atribut dari Authentication, tetapkan secara eksplisit nilai Enkripsi dalam atribut DSN, string koneksi, atau atribut koneksi. Nilai pra-atribut Enkripsi adalah Yes jika nilai diatur ke Yes di DSN atau string koneksi.

Atribut Koneksi Baru dan/atau Yang Dimodifikasi

Atribut koneksi pra-sambungan berikut telah diperkenalkan atau dimodifikasi untuk mendukung autentikasi Microsoft Entra. Ketika atribut koneksi memiliki string koneksi atau kata kunci DSN yang sesuai dan telah ditetapkan, atribut koneksi akan mengesampingkan yang lain.

Atribut	Jenis	Nilai	Default	Deskripsi
SQL_COPT_SS_AUTHENTICATION	SQL_IS_INTEGER	SQL_AU_NONE, SQL_AU_PASSWORD, SQL_AU_AD_INTEGRATED, SQL_AU_AD_PASSWORD, SQL_AU_AD_INTERACTIVE, SQL_AU_AD_MSI, SQL_AU_AD_SPA, SQL_AU_RESET	(tidak diatur)	Lihat deskripsi Authentication kata kunci di atas. SQL_AU_NONEdisediakan untuk secara eksplisit mengambil alih nilai yang ditetapkan Authentication di DSN dan/atau string koneksi, sambil SQL_AU_RESET membatalkan set atribut jika ditetapkan, memungkinkan nilai DSN atau string koneksi diutamakan.
SQL_COPT_SS_ACCESS_TOKEN	SQL_IS_POINTER	Pointer ke ACCESSTOKEN atau NULL	NULL	Jika non-null, menentukan token akses Microsoft Entra untuk digunakan. Ini adalah kesalahan untuk menentukan token akses dan juga kata kunci UID, PWD, Trusted_Connection, atau Authentication string koneksi atau atribut yang setara dengan mereka. CATATAN: Driver ODBC versi 13.1 hanya mendukung pengaturan ini di Windows.
SQL_COPT_SS_ENCRYPT	SQL_IS_INTEGER	SQL_EN_OFF, SQL_EN_ON	(lihat deskripsi)	Mengontrol enkripsi untuk koneksi. SQL_EN_OFF dan SQL_EN_ON menonaktifkan dan mengaktifkan enkripsi, masing-masing. Jika nilai pra-atribut dari pengaturan Authentication bukan none atau SQL_COPT_SS_ACCESS_TOKEN diatur, dan Encrypt tidak ditentukan baik di DSN maupun dalam string koneksi, maka defaultnya adalah SQL_EN_ON. Jika tidak, defaultnya adalah SQL_EN_OFF. Jika atribut SQL_COPT_SS_AUTHENTICATION koneksi diatur ke bukan none, secara eksplisit diatur SQL_COPT_SS_ENCRYPT ke nilai yang diinginkan jika Encrypt tidak ditentukan dalam DSN atau string koneksi. Nilai efektif atribut ini mengontrol apakah enkripsi digunakan untuk koneksi.
SQL_COPT_SS_OLDPWD	-	-	-	Tidak didukung dengan ID Microsoft Entra, karena perubahan kata sandi pada prinsipal Microsoft Entra tidak dapat dicapai melalui koneksi ODBC. Kedaluwarsa kata sandi untuk Autentikasi SQL Server diperkenalkan di SQL Server 2005. Atribut SQL_COPT_SS_OLDPWD ditambahkan untuk memungkinkan klien menyediakan kata sandi lama dan baru untuk koneksi. Ketika properti ini diatur, penyedia tidak akan menggunakan kumpulan koneksi untuk koneksi pertama atau untuk koneksi di masa mendatang, karena string koneksi berisi "kata sandi lama", yang sekarang telah berubah.
SQL_COPT_SS_INTEGRATED_SECURITY	SQL_IS_INTEGER	SQL_IS_OFF,SQL_IS_ON	SQL_IS_OFF	Tidak digunakan lagi; gunakan SQL_COPT_SS_AUTHENTICATION atur ke SQL_AU_AD_INTEGRATED sebagai gantinya. Memaksa penggunaan Autentikasi Windows (Kerberos di Linux dan macOS) untuk validasi akses pada login server. Ketika Autentikasi Windows digunakan, driver mengabaikan nilai pengidentifikasi pengguna dan kata sandi yang disediakan sebagai bagian dari pemrosesan SQLConnect, SQLDriverConnect, atau SQLBrowseConnect.

ActiveDirectoryPassword tidak digunakan lagi

Catatan

Opsi autentikasi ActiveDirectoryPassword (autentikasi Kata Sandi Microsoft Entra ID) tidak digunakan lagi.

Kata sandi ID Microsoft Entra didasarkan pada pemberian OAuth 2.0 Resource Owner Password Credentials (ROPC), yang memungkinkan aplikasi untuk memasukkan pengguna dengan langsung menangani kata sandi mereka.

Microsoft menyarankan Agar Anda tidak menggunakan alur ROPC; tidak kompatibel dengan autentikasi multifaktor (MFA). Dalam kebanyakan skenario, alternatif yang lebih aman tersedia dan direkomendasikan. Alur ini membutuhkan tingkat kepercayaan yang tinggi pada aplikasi, dan membawa risiko yang tidak ada dalam alur lain. Sebaiknya Anda hanya menggunakan alur ini ketika alur yang lebih aman tidak memungkinkan. Microsoft menjauh dari alur autentikasi berisiko tinggi ini untuk melindungi pengguna dari serangan berbahaya. Untuk informasi selengkapnya, lihat Merencanakan autentikasi multifaktor wajib untuk Azure.

Saat konteks pengguna tersedia, gunakan autentikasi ActiveDirectoryInteractive.

Saat konteks pengguna tidak tersedia dan aplikasi Anda berjalan di infrastruktur Azure, gunakan ActiveDirectoryMSI (atau ActiveDirectoryManagedIdentity di beberapa driver). Identitas Terkelola menghilangkan overhead mengelola dan mengganti secara berkala data rahasia dan sertifikat. Jika Anda tidak dapat menggunakan Identitas Terkelola, gunakan autentikasi ActiveDirectoryServicePrincipal.

Peringatan

Jangan gunakan autentikasi Perwakilan Layanan ketika konteks pengguna tersedia. Akses yang hanya untuk aplikasi secara bawaan memiliki hak istimewa tinggi, sering kali memberikan akses seluas penyewa dan berpotensi memungkinkan penyerang jahat mengakses data pelanggan dari setiap pengguna.

Penambahan antarmuka pengguna untuk ID Microsoft Entra (hanya untuk driver Windows)

Pengaturan DSN dan UI koneksi driver telah ditingkatkan dengan opsi tambahan yang diperlukan untuk mengautentikasi dengan ID Microsoft Entra.

Membuat dan mengedit DSN di UI

Dimungkinkan untuk menggunakan opsi autentikasi Microsoft Entra saat membuat atau mengedit DSN yang ada menggunakan antarmuka pengguna penyiapan driver:

Authentication=ActiveDirectoryIntegrated untuk autentikasi terintegrasi Microsoft Entra ke Azure SQL

Authentication=ActiveDirectoryPassword untuk autentikasi nama pengguna/kata sandi Microsoft Entra ke Azure SQL

Catatan

ActiveDirectoryPassword tidak digunakan lagi. Untuk informasi selengkapnya, lihat ActiveDirectoryPassword tidak digunakan lagi.

Authentication=ActiveDirectoryInteractive untuk autentikasi interaktif Microsoft Entra ke Azure SQL

Catatan

Pada driver versi 17.9, perilaku autentikasi interaktif telah berubah. Pengguna akan selalu dimintai kredensial kecuali driver memiliki token akses yang valid yang di-cache. Perubahan ini mencegah pengguna di perangkat yang bergabung dengan Microsoft Entra melewati perintah dan secara otomatis masuk dengan kredensial cache saat menggunakan ActiveDirectoryInteractive autentikasi.

Authentication=SqlPassword untuk autentikasi nama pengguna/kata sandi ke SQL Server dan Azure SQL

Trusted_Connection=Yes untuk autentikasi terintegrasi SSPI warisan Windows

Authentication=ActiveDirectoryMsi untuk autentikasi identitas terkelola Microsoft Entra

Authentication=ActiveDirectoryServicePrincipal untuk autentikasi prinsipal layanan Microsoft Entra

Tujuh opsi tersebut sesuai dengan Trusted_Connection=Yes (autentikasi terintegrasi khusus SSPI Windows legacy yang sudah ada) dan masing-masing Authentication=, ActiveDirectoryIntegrated, SqlPassword, ActiveDirectoryPassword, ActiveDirectoryInteractive, ActiveDirectoryMsi, serta ActiveDirectoryServicePrincipal.

Prompt SQLDriverConnect (khusus driver Windows)

Dialog perintah yang ditampilkan oleh SQLDriverConnect saat meminta informasi yang diperlukan untuk menyelesaikan koneksi berisi empat opsi baru untuk autentikasi Microsoft Entra:

Opsi ini sesuai dengan enam opsi yang sama tersedia di antarmuka pengguna penyiapan DSN di atas.

Contoh string penghubung

1. Autentikasi SQL Server - sintaks lama. Sertifikat server tidak divalidasi, dan enkripsi hanya digunakan jika server memberlakukannya. Nama pengguna/kata sandi diteruskan dalam string koneksi.

   server=Server;database=Database;UID=UserName;PWD=<password>;Encrypt=no;TrustServerCertificate=yes;

2. Autentikasi SQL - sintaks baru. Klien meminta enkripsi (nilai Encrypt defaultnya adalah true) dan sertifikat server akan divalidasi, apa pun pengaturan enkripsinya (kecuali TrustServerCertificate diatur ke true). Nama pengguna/kata sandi diteruskan dalam string koneksi.

   server=Server;database=Database;UID=UserName;PWD=<password>;Authentication=SqlPassword;

3. Autentikasi Windows Terintegrasi (Kerberos di Linux dan macOS) menggunakan SSPI (ke SQL Server atau SQL IaaS) - Sintaks Saat Ini. Sertifikat server tidak divalidasi, kecuali enkripsi diperlukan oleh server.

   server=Server;database=Database;Trusted_Connection=yes;Encrypt=no;

4. (Hanya driver Windows.) Autentikasi Windows terintegrasi menggunakan SSPI (jika database target berada di SQL Server atau SQL Server di Azure VM) - sintaks baru. Klien meminta enkripsi (nilai Encrypt defaultnya adalah true) dan sertifikat server akan divalidasi, apa pun pengaturan enkripsinya (kecuali TrustServerCertificate diatur ke true).

   server=Server;database=Database;Authentication=ActiveDirectoryIntegrated;

5. Autentikasi nama pengguna/kata sandi Microsoft Entra (jika database target berada di Azure SQL Database atau Azure SQL Managed Instance). Sertifikat server akan divalidasi, apa pun pengaturan enkripsi (kecuali TrustServerCertificate diatur ke true). Nama pengguna/kata sandi diteruskan dalam string koneksi.

   Catatan

   ActiveDirectoryPassword tidak digunakan lagi. Untuk informasi selengkapnya, lihat ActiveDirectoryPassword tidak digunakan lagi.

   server=Server;database=Database;UID=UserName;PWD=<password>;Authentication=ActiveDirectoryPassword;Encrypt=yes;

6. (Windows, dan Linux/macOS 17.6+, hanya driver.) Autentikasi Windows terintegrasi menggunakan ADAL atau Kerberos, yang melibatkan penggunaan kredensial akun Windows untuk mendapatkan token akses Microsoft Entra, dengan asumsi database target ada di Azure SQL. Sertifikat server akan divalidasi, apa pun pengaturan enkripsi (kecuali TrustServerCertificate diatur ke true). Di Linux/macOS, tiket Kerberos yang sesuai harus tersedia. Untuk informasi selengkapnya, lihat bagian di bawah ini tentang Akun Federasi dan Menggunakan Autentikasi Terintegrasi.

   server=Server;database=Database;Authentication=ActiveDirectoryIntegrated;Encrypt=yes;

7. (Hanya driver Windows.) Autentikasi Interaktif Microsoft Entra menggunakan teknologi autentikasi multifaktor Microsoft Entra untuk menyiapkan koneksi. Dalam mode ini, dengan memberikan ID masuk, dialog Autentikasi Azure dipicu dan memungkinkan pengguna untuk memasukkan verifikasi tambahan untuk menyelesaikan koneksi. Nama pengguna diteruskan dalam string koneksi.

   server=Server;database=Database;UID=UserName;Authentication=ActiveDirectoryInteractive;Encrypt=yes;

   

8. Autentikasi identitas terkelola Microsoft Entra dapat menggunakan identitas terkelola yang ditetapkan sistem atau ditetapkan pengguna. Untuk identitas yang ditetapkan pengguna, atur UID ke ID klien identitas untuk Azure App Service atau Azure Container Instance; jika tidak, gunakan ID objeknya. Untuk identitas yang ditetapkan sistem, UID tidak diperlukan.
   

   Untuk identitas yang ditetapkan sistem:

   server=Server;database=Database;Authentication=ActiveDirectoryMsi;Encrypt=yes;

   Untuk identitas yang ditetapkan pengguna dengan ID objek sama dengan myObjectId:

   server=Server;database=Database;UID=myObjectId;Authentication=ActiveDirectoryMsi;Encrypt=yes;

9. Autentikasi prinsip layanan Microsoft Entra

   server=Server;database=Database;UID=clientId;PWD=<password>;Authentication=ActiveDirectoryServicePrincipal;Encrypt=yes;

Keterangan

• Saat menggunakan opsi Microsoft Entra dengan driver Windows ODBC sebelum versi 17.4.2, pastikan bahwa Pustaka Autentikasi Direktori Aktif untuk SQL Server telah diinstal. Saat menggunakan driver Linux dan macOS, pastikan bahwa libcurl telah diinstal. Untuk driver versi 17.2 dan yang lebih baru, ini bukan dependensi eksplisit karena tidak diperlukan untuk metode autentikasi atau operasi ODBC lainnya.

• Ketika konfigurasi Microsoft Entra menyertakan kebijakan akses bersyarah, dan klien adalah Windows 10 atau Server 2016 atau yang lebih baru, autentikasi melalui Terintegrasi atau nama pengguna/kata sandi mungkin gagal. Kebijakan akses bersyarat memerlukan penggunaan Web Account Manager (WAM), yang didukung di driver versi 17.6 atau yang lebih baru untuk Windows. Untuk menggunakan WAM, buat nilai string baru bernama ADALuseWAM di HKLM\Software\ODBC\ODBCINST.INI\ODBC Driver 17 for SQL Server, , HKCU\Software\ODBC\ODBC.INI\<your-user-DSN-name>atau HKLM\Software\ODBC\ODBC.INI\<your-system-DSN-name> untuk konfigurasi cakupan DSN pengguna global, atau sistem DSN masing-masing, dan atur ke nilai 1. Perhatikan bahwa autentikasi dengan WAM tidak mendukung menjalankan aplikasi sebagai pengguna yang berbeda menggunakan runas. Skenario yang memerlukan kebijakan Akses Bersyarat tidak didukung untuk Linux atau macOS.

• Untuk menyambungkan menggunakan nama pengguna dan kata sandi akun SQL Server, Anda sekarang dapat menggunakan opsi baru SqlPassword , yang direkomendasikan terutama untuk Azure SQL karena opsi ini mengaktifkan default koneksi yang lebih aman.

• Untuk menyambungkan menggunakan nama pengguna dan kata sandi akun Microsoft Entra, tentukan Authentication=ActiveDirectoryPassword di string koneksi serta kata kunci UID dan PWD dengan nama pengguna dan kata sandi, masing-masing.

  Catatan

  ActiveDirectoryPassword tidak digunakan lagi. Untuk informasi selengkapnya, lihat ActiveDirectoryPassword tidak digunakan lagi.

• Untuk menyambungkan menggunakan autentikasi Windows Integrated atau Microsoft Entra Integrated (Windows, dan Linux/macOS 17.6+, hanya driver), tentukan Authentication=ActiveDirectoryIntegrated dalam string koneksi. Pengandar akan memilih mode autentikasi yang benar secara otomatis. Untuk driver versi 17.7 atau yang lebih lama, UID dan PWD tidak boleh ditentukan. Dimulai dengan driver versi 17.8, UID dan PWD diabaikan.

• Untuk menyambungkan menggunakan autentikasi interaktif Microsoft Entra (hanya driver Windows), UID harus ditentukan. Untuk driver versi 17.7 dan yang lebih lama, PWD tidak boleh ditentukan. Dimulai dengan driver versi 17.8, PWD diabaikan.

• Dimulai dengan versi 18.1, Trusted_Connection=Yes tidak lagi menggunakan autentikasi federasi ID Microsoft Entra secara default dan menggunakan terintegrasi SSPI sebagai gantinya. Untuk menggunakan ID Microsoft Entra untuk opsi ini, TrustedConnection_UseAAD=Yes harus dikonfigurasi.

• Driver ODBC versi 17.7 dan yang lebih rendah memiliki masalah yang diketahui dengan batas waktu koneksi ketika autentikasi Microsoft Entra dan Enkripsi Paksa diaktifkan pada instans SQL Server. Errorlog SQL Server mungkin berisi pesan kesalahan seperti: "Kesalahan: 33155, Tingkat Keparahan: 20, Status: 1. Peristiwa pemutusan sambungan dimunculkan saat server menunggu token Autentikasi Federasi. Ini bisa disebabkan oleh penutupan klien atau batas waktu server kedaluwarsa.". Jika Anda menggunakan solusi ketersediaan tinggi seperti grup ketersediaan AlwaysOn atau instans kluster failover, komunikasi kluster internal untuk SQL Server dapat dipengaruhi oleh perilaku ini yang dapat memengaruhi ketersediaan sumber daya. Di log kluster, Anda mungkin melihat pesan kesalahan seperti: [hadrag] Connect to SQL Server ...ODBC Error: [HY000] [Microsoft][ODBC Driver 17 for SQL Server]An unknown error has occurred. Detailed error information is not available. (0). Driver ODBC versi 17.10 dan yang lebih tinggi memperbaiki masalah ini dan dengan SQL Server 2022 GDR KB5021522 /CU1 KB5022375, driver terbaru yang berisi perbaikan ini diinstal dengan penginstalan SQL Server. Anda dapat memverifikasi versi driver ODBC mana yang telah Anda instal dengan merujuk ke Administrator Sumber Data ODBC.

• Dimulai dengan driver ODBC versi 18.3, autentikasi Identitas Terkelola (ActiveDirectoryMSI) didukung di Azure Arc dan Azure Cloud Shell.

Mengautentikasi dengan token akses

Atribut SQL_COPT_SS_ACCESS_TOKEN pra-sambungan memungkinkan penggunaan token akses yang diperoleh dari Microsoft Entra ID untuk autentikasi alih-alih nama pengguna dan kata sandi, serta melewati proses negosiasi dan perolehan token akses oleh driver. Untuk menggunakan token akses, atur SQL_COPT_SS_ACCESS_TOKEN atribut koneksi ke struktur ACCESSTOKEN penunjuk:

typedef struct AccessToken
{
    DWORD dataSize;
    BYTE data[];
} ACCESSTOKEN;

ACCESSTOKEN adalah struktur panjang variabel yang terdiri dari panjang 4 byte diikuti dengan byte panjang data buram yang membentuk token akses. Karena cara SQL Server menangani token akses, satu token yang diperoleh melalui respons JSON OAuth 2.0 perlu diperluas sehingga setiap byte diikuti oleh byte nol sebagai padding, mirip dengan string UCS-2 yang hanya berisi karakter ASCII. Namun, token adalah nilai buram dan panjang yang ditentukan, dalam byte, TIDAK boleh menyertakan terminator null. Karena batasan panjang dan formatnya yang cukup besar, metode autentikasi ini hanya tersedia secara terprogram melalui SQL_COPT_SS_ACCESS_TOKEN atribut koneksi.

ACCESSTOKEN harus tetap dialokasikan selama pegangan koneksi dialokasikan. Jika tidak, pelanggaran akses mungkin terjadi. Penunjuk adalah bagian dari kunci kumpulan koneksi, sehingga pointer baru menghasilkan kumpulan baru dan koneksi baru. Jika token kedaluwarsa, Anda dapat memperbarui token akses dengan memperbarui buffer data secara langsung untuk terus menggunakan koneksi yang ada.

Tidak ada kata kunci DSN atau string koneksi yang sesuai. String koneksi tidak boleh berisi kata kunci UID, PWD, Authentication, atau Trusted_Connection.

Catatan

Driver ODBC versi 13.1 hanya mendukung autentikasi ini di Windows. Versi berikutnya mendukung autentikasi ini di semua platform.

Kode contoh untuk autentikasi Microsoft Entra

Contoh berikut menunjukkan kode yang diperlukan untuk menyambungkan ke SQL Server menggunakan ID Microsoft Entra dengan kata kunci koneksi. Tidak perlu mengubah kode aplikasi itu sendiri. string koneksi, atau DSN jika digunakan, adalah satu-satunya modifikasi yang diperlukan untuk menggunakan ID Microsoft Entra untuk autentikasi:

    ...
    SQLCHAR connString[] = "Driver={ODBC Driver 18 for SQL Server};Server={server};UID=myuser;PWD=<password>;Authentication=ActiveDirectoryInteractive;Encrypt=yes;"
    ...
    SQLDriverConnect(hDbc, NULL, connString, SQL_NTS, NULL, 0, NULL, SQL_DRIVER_NOPROMPT);
    ...

Contoh berikut menunjukkan kode yang diperlukan untuk menyambungkan ke SQL Server menggunakan autentikasi token akses Microsoft Entra. Dalam hal ini, perlu untuk memodifikasi kode aplikasi untuk memproses token akses dan mengatur atribut koneksi terkait.

    SQLCHAR connString[] = "Driver={ODBC Driver 18 for SQL Server};Server={server};Encrypt=yes;"
    SQLCHAR accessToken[] = "eyJ0eXAiOi..."; // In the format extracted from an OAuth JSON response
    ...
    DWORD dataSize = 2 * strlen(accessToken);
    ACCESSTOKEN *pAccToken = malloc(sizeof(ACCESSTOKEN) + dataSize);
    pAccToken->dataSize = dataSize;
    // Expand access token with padding bytes
    for(int i = 0, j = 0; i < dataSize; i += 2, j++) {
        pAccToken->data[i] = accessToken[j];
        pAccToken->data[i+1] = 0;
    }
    ...
    SQLSetConnectAttr(hDbc, SQL_COPT_SS_ACCESS_TOKEN, (SQLPOINTER)pAccToken, SQL_IS_POINTER);
    SQLDriverConnect(hDbc, NULL, connString, SQL_NTS, NULL, 0, NULL, SQL_DRIVER_NOPROMPT);
    ...
    free(pAccToken);

Contoh berikut string koneksi digunakan dengan autentikasi interaktif Microsoft Entra. Ini tidak berisi bidang PWD karena kata sandi akan dimasukkan di layar Autentikasi Azure.

SQLCHAR connString[] = "Driver={ODBC Driver 18 for SQL Server};Server={server};UID=myuser;Authentication=ActiveDirectoryInteractive;Encrypt=yes;"

Contoh string koneksi sampel berikut untuk digunakan dengan autentikasi identitas terkelola Microsoft Entra. UID diatur ke ID objek/klien identitas pengguna ketika menggunakan identitas yang ditetapkan sendiri oleh pengguna.

// For system-assigned identity,
SQLCHAR connString[] = "Driver={ODBC Driver 18 for SQL Server};Server={server};Authentication=ActiveDirectoryMsi;Encrypt=yes;"
...
// For user-assigned identity with object ID equals to myObjectId
SQLCHAR connString[] = "Driver={ODBC Driver 18 for SQL Server};Server={server};UID=myObjectId;Authentication=ActiveDirectoryMsi;Encrypt=yes;"

Pertimbangan untuk menggunakan Akun Federasi ADFS di Linux/macOS

Dimulai dengan versi 17.6, driver untuk Linux dan macOS mendukung autentikasi menggunakan akun federasi Microsoft Entra ADFS menggunakan nama pengguna/kata sandi (ActiveDirectoryPassword) atau Kerberos (ActiveDirectoryIntegrated). Ada beberapa batasan tergantung pada platform saat menggunakan mode Terintegrasi.

Saat mengautentikasi dengan pengguna yang akhiran UPN-nya berbeda dari realm Kerberos, yaitu, ketika akhiran UPN alternatif sedang digunakan, perlu menggunakan opsi Prinsipal Perusahaan (gunakan opsi -E bersama kinit, dan berikan nama prinsipal dalam formulir user@federated-domain) saat mendapatkan tiket Kerberos. Dengan cara ini, driver dapat menentukan domain federasi dan realm Kerberos dengan benar.

Anda dapat memverifikasi bahwa tiket Kerberos yang sesuai tersedia dengan memeriksa output klist perintah. Jika domain federasi sama dengan ranah Kerberos dan akhiran UPN, nama utamanya adalah dalam bentuk user@realm. Jika berbeda, nama utama harus dalam bentuk user@federated-domain@realm.

Linux

Pada SUSE 11, pustaka Kerberos default versi 1.6.x tidak mendukung opsi Enterprise Principal yang diperlukan untuk menggunakan akhiran UPN alternatif. Untuk menggunakan akhiran UPN alternatif dengan autentikasi terintegrasi Microsoft Entra, tingkatkan pustaka Kerberos ke 1.7 atau yang lebih baru.

Di Alpine Linux, default libcurl tidak mendukung autentikasi SPNEGO/Kerberos yang diperlukan untuk autentikasi terintegrasi Microsoft Entra.

macOS

Pustaka sistem Kerberos kinit mendukung Enterprise Principal dengan opsi --enterprise, tetapi juga secara implisit melakukan kanonisasi nama, yang mencegah penggunaan akhiran UPN alternatif. Untuk menggunakan akhiran UPN alternatif dengan autentikasi terintegrasi Microsoft Entra, instal pustaka Kerberos yang lebih baru dengan menggunakan brew install krb5 dan opsi -E seperti yang dijelaskan di atas. Gunakan kinit bersama opsi tersebut.

Konten terkait

• Dukungan autentikasi berbasis token untuk Azure SQL Database menggunakan autentikasi Microsoft Entra
• Menggunakan Autentikasi Terintegrasi