Autentikasi Microsoft Entra dengan mssql-python

Microsoft Entra ID menyediakan autentikasi berbasis identitas untuk Azure SQL Database, Azure SQL Managed Instance, dan database SQL di Microsoft Fabric melalui driver mssql-python. Autentikasi Microsoft Entra menawarkan kemampuan ini melalui autentikasi SQL:

• Manajemen identitas terpusat melalui Microsoft Entra ID.
• Autentikasi berbasis token yang menghilangkan kebutuhan akan kata sandi.
• Dukungan untuk kebijakan akses bersyarat.
• Identitas terkelola untuk aplikasi yang dihosting Azure.

Driver mssql-python mendukung tujuh mode autentikasi Microsoft Entra, semuanya dikonfigurasi melalui Authentication kata kunci string koneksi.

Modus autentikasi

Atur Authentication kata kunci di string koneksi Anda ke salah satu nilai berikut:

Nilai autentikasi	Deskripsi
ActiveDirectoryDefault	Menggunakan DefaultAzureCredential, yang mencoba beberapa metode secara otomatis.
ActiveDirectoryInteractive	Masuk interaktif berbasis browser.
ActiveDirectoryDeviceCode	Entri kode di https://microsoft.com/devicelogin.
ActiveDirectoryPassword	Nama pengguna dan kata sandi dengan Microsoft Entra ID. Tidak digunakan lagi.
ActiveDirectoryMSI	Identitas terkelola (ditetapkan sistem atau ditetapkan pengguna).
ActiveDirectoryServicePrincipal	Perwakilan layanan dengan ID klien dan rahasia.
ActiveDirectoryIntegrated	Windows Terintegrasi dengan Microsoft Entra ID (Kerberos).

Note

Mode ActiveDirectoryDefault, ActiveDirectoryInteractive, dan ActiveDirectoryDeviceCode memerlukan paket azure-identity. Instal itu dengan pip install azure-identity.

DefaultAzureCredential

Mode ActiveDirectoryDefault ini menggunakan DefaultAzureCredential dari Azure Identity SDK, yang mencoba metode autentikasi berikut dalam urutan ini:

1. Variabel lingkungan.
2. Identitas beban kerja untuk Kubernetes.
3. Identitas yang dikelola
4. Kredensial Azure CLI.
5. Kredensial Azure PowerShell.
6. Kredensial CLI Pengembang Azure.
7. Browser interaktif, jika diaktifkan.

Contoh: Autentikasi bawaan

Contoh berikut terhubung dengan ActiveDirectoryDefault, yang menggunakan DefaultAzureCredential rantai untuk menemukan kredensial yang valid secara otomatis:

import mssql_python

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDefault;"
    "Encrypt=yes;"
)

cursor = conn.cursor()
cursor.execute("SELECT USER_NAME()")
print(f"Connected as: {cursor.fetchval()}")

Gunakan mode ini untuk pengembangan lokal karena mengambil kredensial Azure CLI secara otomatis. Untuk produksi, gunakan mode autentikasi tertentu (ActiveDirectoryMSI, ActiveDirectoryServicePrincipal) sebagai gantinya. DefaultAzureCredential memeriksa beberapa penyedia kredensial pada setiap koneksi awal, yang menambah latensi yang tidak diperlukan oleh beban kerja produksi.

Autentikasi interaktif

Untuk aplikasi interaktif, gunakan autentikasi berbasis browser. Pengguna harus memiliki akun database yang dibuat dengan CREATE USER [user@domain.com] FROM EXTERNAL PROVIDER. Untuk prasyarat lengkap, lihat Mengonfigurasi autentikasi Microsoft Entra.

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryInteractive;"
    "Encrypt=yes;"
)

Di Windows, mode ini mendelegasikan ke alur interaktif asli driver ODBC. Pada platform lain, ini menggunakan autentikasi berbasis browser Azure Identity SDK.

Autentikasi kode perangkat

Gunakan autentikasi kode perangkat untuk lingkungan tanpa browser, seperti sesi atau kontainer SSH. Pengguna harus memiliki akun database yang dibuat dengan CREATE USER [user@domain.com] FROM EXTERNAL PROVIDER. Untuk prasyarat, lihat Mengonfigurasi autentikasi Microsoft Entra.

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDeviceCode;"
    "Encrypt=yes;"
)
# Output: To sign in, use a web browser to open https://microsoft.com/devicelogin
# and enter the code XXXXXXX to authenticate.

Ikuti perintah untuk mengautentikasi di browser di perangkat lain.

Autentikasi pokok layanan

Gunakan autentikasi perwakilan layanan untuk aplikasi otomatis yang tidak memerlukan interaksi pengguna:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryServicePrincipal;"
    "UID=<client-id>;"       # Application (client) ID
    "PWD=<client-secret>;"   # Client secret
    "Encrypt=yes;"
)

Membuat "Service Principal"

1. Daftarkan aplikasi di Microsoft Entra ID.
2. Buat rahasia klien.
3. Berikan akses kepada perwakilan layanan ke database Anda:

-- In Azure SQL
CREATE USER [app-name] FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER [app-name];
ALTER ROLE db_datawriter ADD MEMBER [app-name];

Tip

Jika CREATE USER gagal dengan kesalahan 33131 (nama tampilan duplikat), gunakan WITH OBJECT_ID untuk menentukan ID Objek perwakilan layanan dari halaman aplikasi Perusahaan di portal Azure (bukan halaman pendaftaran aplikasi):

CREATE USER [app-name] FROM EXTERNAL PROVIDER
    WITH OBJECT_ID = '<enterprise-app-object-id>';

Untuk detailnya, lihat Login Microsoft Entra dan pengguna dengan nama tampilan nonunik.

Identitas yang dikelola

Gunakan autentikasi identitas terkelola untuk aplikasi yang dihosting Azure, seperti App Service, Azure Functions, dan VM:

Identitas terkelola yang diberikan oleh sistem

Sambungkan menggunakan identitas yang ditetapkan langsung ke sumber daya Azure:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryMSI;"
    "Encrypt=yes;"
)

Identitas terkelola yang ditetapkan pengguna

Tentukan ID klien dari identitas terkelola yang ditetapkan pengguna dalam bidang UID:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryMSI;"
    "UID=<managed-identity-client-id>;"
    "Encrypt=yes;"
)

Mengonfigurasi akses database

Berikan akses identitas terkelola di database Anda. Admin Microsoft Entra harus dikonfigurasi di server sebelum Anda dapat membuat pengguna eksternal. Untuk mengaktifkan identitas terkelola pada sumber daya Azure Anda, lihat Identitas terkelola untuk sumber daya Azure.

-- Replace 'my-app-service' with your Azure resource name
CREATE USER [my-app-service] FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER [my-app-service];
ALTER ROLE db_datawriter ADD MEMBER [my-app-service];

Autentikasi sandi (tidak digunakan lagi)

Penting

Opsi autentikasi ActiveDirectoryPassword (autentikasi kata sandi Microsoft Entra ID) tidak digunakan lagi di driver SQL Microsoft. Alur autentikasi berisiko tinggi ini tidak kompatibel dengan autentikasi multifaktor (MFA) Microsoft Entra wajib dan mungkin tidak berfungsi di penyewa tempat MFA diberlakukan. Rencanakan untuk bermigrasi ke metode autentikasi Microsoft Entra yang berbeda.

Autentikasi kata sandi Microsoft Entra ID didasarkan pada grant OAuth 2.0 Resource Owner Password Credentials (ROPC), yang memungkinkan aplikasi mengautentikasi pengguna dengan menangani kata sandi mereka secara langsung.

Microsoft menyarankan agar Anda tidak menggunakan alur ROPC karena tidak kompatibel dengan MFA. Dalam sebagian besar 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. Gunakan alur ini hanya jika opsi 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 pengguna hadir saat proses masuk, gunakan autentikasi ActiveDirectoryInteractive atau ActiveDirectoryIntegrated sehingga jejak audit dikaitkan dengan pengguna yang masuk dan kebijakan Akses Bersyarat diterapkan.

Untuk skenario layanan ke layanan tanpa pengawas, ikuti panduan akun layanan Microsoft Entra:

• Jika aplikasi Anda berjalan pada infrastruktur Azure, gunakan ActiveDirectoryMSI (atau ActiveDirectoryManagedIdentity di beberapa driver). Identitas terkelola menghilangkan overhead untuk memelihara dan memutar rahasia dan sertifikat.
• Jika identitas terkelola tidak tersedia (misalnya, aplikasi berjalan di luar Azure), gunakan ActiveDirectoryServicePrincipal. Di mana driver mendukungnya, lebih memilih sertifikat klien daripada rahasia klien. Dengan sertifikat, kunci privat tetap berada di klien dan hanya pernyataan yang ditandatangani yang dikirim ke Microsoft Entra untuk mengautentikasi klien. Jika kunci disimpan di perangkat keras (seperti TPM atau HSM) atau ditandai sebagai tidak dapat diekspor, kunci tersebut tidak dapat disalin keluar sebagai string sebagaimana rahasia klien dapat disalin.
• Jangan gunakan akun pengguna Microsoft Entra sebagai akun layanan.

Gunakan autentikasi kata sandi saat Anda memerlukan nama pengguna dan kata sandi dengan akun Microsoft Entra. Pengguna harus memiliki akun database yang dibuat dengan CREATE USER [user@domain.com] FROM EXTERNAL PROVIDER:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryPassword;"
    "UID=<login@domain.com>;"
    "PWD=<password>;"
    "Encrypt=yes;"
)

Autentikasi terintegrasi Windows

Gunakan autentikasi Terintegrasi Windows untuk lingkungan Windows yang bergabung dengan domain dengan Kerberos. Mode ini mengharuskan Active Directory lokal Anda untuk difederasikan dengan Microsoft Entra ID dan administrator Microsoft Entra yang dikonfigurasi di server:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryIntegrated;"
    "Encrypt=yes;"
)

Mode ini menggunakan kredensial Kerberos pengguna Windows saat ini. Di Linux dan macOS, Anda harus mengonfigurasi Kerberos secara manual (krb5.conf dan keytab atau tiket yang valid). Lihat Menggunakan autentikasi Direktori Aktif dengan SQL Server on Linux untuk penyiapan Kerberos sisi klien.

Akses autentikasi token

Anda dapat memperoleh token secara eksternal, misalnya, melalui penyedia token kustom atau cache token bersama. Dalam kasus ini, gunakan SQL_COPT_SS_ACCESS_TOKEN dengan attrs_before parameter untuk meneruskan token secara langsung. Pendekatan ini melewati alur akuisisi token bawaan driver.

import mssql_python
from azure.identity import DefaultAzureCredential
import struct

def get_token():
    credential = DefaultAzureCredential(
        exclude_interactive_browser_credential=False
    )
    token_bytes = credential.get_token(
        "https://database.windows.net/.default"
    ).token.encode("utf-16le")
    token_struct = struct.pack(
        f'<I{len(token_bytes)}s', len(token_bytes), token_bytes
    )
    return token_struct

SQL_COPT_SS_ACCESS_TOKEN = 1256

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;",
    attrs_before={SQL_COPT_SS_ACCESS_TOKEN: get_token()}
)

Penting

Saat menggunakan SQL_COPT_SS_ACCESS_TOKEN, string koneksi tidak boleh menyertakan UID, PWD, Authentication, atau Trusted_Connection. Token itu sendiri menangani autentikasi.

Memilih mode autentikasi

Scenario	Mode yang disarankan
Komputer pengembangan	ActiveDirectoryDefault(menggunakan Azure CLI)
Azure App Service / Fungsi	ActiveDirectoryMSI (lebih cepat dari Default)
Azure Kubernetes Service	ActiveDirectoryDefault (identitas beban kerja)
Skrip otomatis di lingkungan lokal	ActiveDirectoryServicePrincipal
Aplikasi desktop interaktif	ActiveDirectoryInteractive
SSH/kontainer tanpa browser	ActiveDirectoryDeviceCode

Troubleshoot

Log masuk gagal bagi pengguna 'NT AUTHORITY\ANONYMOUS LOGON'

Verifikasi bahwa pengguna atau identitas terkelola ada di database:

CREATE USER [identity-name] FROM EXTERNAL PROVIDER;

"AADSTS700016: Aplikasi tidak ditemukan"

Perwakilan layanan atau ID aplikasi salah. Verifikasi ID klien dan aplikasi terdaftar di penyewa Microsoft Entra Anda.

"Titik akhir Identitas Terkelola tidak dapat dijangkau"

• Verifikasi bahwa identitas terkelola diaktifkan pada sumber daya Azure.
• Untuk identitas yang ditetapkan pengguna, pastikan ID klien sudah benar.
• Periksa apakah sumber daya memiliki akses jaringan ke titik akhir identitas.

Batas waktu akuisisi token

ActiveDirectoryDefault menggunakan DefaultAzureCredential, yang menelusuri rangkaian penyedia kredensial secara berurutan hingga salah satunya berhasil. Penelusuran rantai ini menambah latensi beberapa detik pada koneksi pertama, terutama ketika penyedia yang lebih awal dalam rantai (variabel lingkungan, identitas beban kerja) gagal sebelum mencapai penyedia yang berfungsi. Di lingkungan produksi, tentukan jenis kredensial secara langsung untuk menghindari rantai tersebut:

# Slow: DefaultAzureCredential tries multiple providers
conn = mssql_python.connect(connection_string, authentication="ActiveDirectoryDefault")

# Fast: Skip directly to managed identity
conn = mssql_python.connect(connection_string, authentication="ActiveDirectoryMSI")

Konten terkait

• String koneksi
• Troubleshooting
• Migrasi tanpa kata sandi Azure SQL
• Autentikasi Microsoft Entra dengan Azure SQL