Microsoft Entra autentikasi dengan mssql-django

Artikel ini menjelaskan cara mengonfigurasi autentikasi Microsoft Entra untuk aplikasi Django menggunakan mssql-django backend. Microsoft Entra autentikasi menghilangkan kebutuhan untuk menyimpan kata sandi dalam konfigurasi aplikasi Anda.

Prasyarat

  • Microsoft ODBC Driver 18 untuk SQL Server (disarankan). Semua mode autentikasi dalam artikel ini didukung dengan Microsoft ODBC Driver 18 untuk SQL Server. ActiveDirectoryInteractive hanya untuk Windows, apa pun versi drivernya. Jika Anda harus menggunakan ODBC Driver 17, lihat referensi autentikasi ODBC untuk mengetahui versi minimum 17.x bagi setiap mode.
  • Untuk autentikasi token akses: pip install azure-identity.

Metode autentikasi

Konfigurasikan setiap metode dengan menambahkan atau mengedit DATABASES pengaturan dalam file proyek settings.py Django Anda. Contoh dalam artikel ini menunjukkan blok penuh DATABASES["default"] untuk kejelasan; salin kunci yang relevan ke dalam konfigurasi Anda yang ada.

mssql-djangomendukung autentikasi Microsoft Entra dengan dua cara:

  • Autentikasi driver ODBC melalui OPTIONS["extra_params"]. Aplikasi backend menambahkan string ini ke string koneksi ODBC apa adanya, sehingga nilai Authentication= yang tersedia berasal dari Microsoft ODBC Driver for SQL Server yang terinstal, bukan dari mssql-django itu sendiri.
  • Autentikasi token akses secara terprogram melalui pengaturan TOKEN. Backend meneruskan TOKEN ke driver ODBC sebagai SQL_COPT_SS_ACCESS_TOKEN, yang mengabaikan kata kunci Authentication= ODBC.

Sekilas metode autentikasi

Metode Konfigurasikan dengan Paling cocok untuk
Token akses TOKEN Pengembangan, skrip yang berumur pendek, atau aplikasi dengan penyegaran token kustom
ActiveDirectoryMsi extra_params aplikasi produksi yang dihosting di Azure (identitas terkelola yang ditetapkan sistem dan yang ditetapkan pengguna)
ActiveDirectoryServicePrincipal USER, PASSWORD, extra_params Pendaftaran aplikasi jika identitas terkelola tidak tersedia
ActiveDirectoryIntegrated extra_params Konteks pengguna yang tergabung ke domain
ActiveDirectoryInteractive USER, extra_params Masuk pengguna dengan autentikasi multifaktor (Windows)
ActiveDirectoryDefault extra_params Pengembangan lokal dan aplikasi yang harus menggunakan rantai kredensial Microsoft Entra default milik driver ODBC
ActiveDirectoryPassword USER, PASSWORD, extra_params Hanya untuk skenario versi lama sebagai pilihan terakhir (sudah usang)

Note

mssql-django 1.7.3 dan versi yang lebih baru mendukung Authentication=ActiveDirectoryDefault hingga OPTIONS["extra_params"] jika Microsoft ODBC Driver for SQL Server yang terinstal mendukung mode tersebut. Jika Anda memerlukan kontrol eksplisit atas perilaku akuisisi dan refresh token, gunakan pola TOKEN dengan azure.identity.DefaultAzureCredential kelas .

Memberikan akses identitas di Azure SQL

Untuk autentikasi identitas terkelola atau perwakilan layanan, buat pengguna database dan berikan hanya peran yang dibutuhkan aplikasi Anda:

CREATE USER [<identity-name>] FOR EXTERNAL PROVIDER;

ALTER ROLE db_datareader ADD MEMBER [<identity-name>];
ALTER ROLE db_datawriter ADD MEMBER [<identity-name>];
ALTER ROLE db_ddladmin ADD MEMBER [<identity-name>];

Peran database tetap db_ddladmin diperlukan hanya jika aplikasi menjalankan migrasi. Untuk beban kerja baca-saja, db_datareader sudah cukup.

Note

FROM EXTERNAL PROVIDERmengharuskan server SQL memanggil Microsoft Graph untuk menyelesaikan nama utama. Jika server dikonfigurasi untuk autentikasi Microsoft Entra saja atau jika tidak dapat mengakses Graph, pernyataan tersebut gagal dengan Msg 33130 (Principal '<name>' could not be found...). Buat pengguna secara manual dengan menyediakan SID eksplisit:

CREATE USER [<identity-name>] WITH SID = 0x<sid-hex>, TYPE = E;

Untuk identitas terkelola atau prinsipal layanan, turunkan SID dari ID aplikasi (klien) milik identitas tersebut, bukan dari ID objeknya. Azure SQL menggunakan ID aplikasi untuk perwakilan layanan dan identitas terkelola, dan ID objek hanya untuk pengguna Entra reguler. Konversi GUID dengan membalik urutan tiga grup pertama yang dipisahkan oleh tanda hubung per byte, dan membiarkan dua grup terakhir apa adanya. Misalnya, ID 00001111-aaaa-2222-bbbb-3333cccc4444 aplikasi menjadi SID 0x11110000AAAA2222BBBB3333CCCC4444. Di PowerShell:

$b = ([Guid]"<app-id>").ToByteArray()
"0x" + (($b | ForEach-Object { $_.ToString('X2') }) -join '')

Jika Anda menggunakan ID objek secara tidak sengaja, koneksi berhasil memperoleh token, tetapi Azure SQL mengembalikan Login failed for user '<token-identified principal>' karena tidak ada prinsipal database yang cocok dengan klaim tokenappid.

Jika Anda melihat kesalahan VIEW ANY COLUMN MASTER KEY DEFINITION permission denied , berikan identitas akses tambahan untuk skenario Always Encrypted:

GRANT VIEW ANY COLUMN MASTER KEY DEFINITION TO [<identity-name>];
GRANT VIEW ANY COLUMN ENCRYPTION KEY DEFINITION TO [<identity-name>];

Autentikasi identitas terkelola (ActiveDirectoryMsi)

Gunakan identitas terkelola saat aplikasi Django Anda berjalan pada layanan Azure seperti Azure App Service, Azure Container Apps, atau Azure Virtual Machines. Pendekatan ini direkomendasikan untuk lingkungan produksi karena driver ODBC memperoleh dan menyegarkan token secara otomatis.

Identitas terkelola yang ditetapkan sistem:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "HOST": "<your-server>.database.windows.net",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "Authentication=ActiveDirectoryMsi",
        },
    },
}

Identitas terkelola yang ditetapkan pengguna:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "HOST": "<your-server>.database.windows.net",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": (
                "Authentication=ActiveDirectoryMsi;"
                "UID=<managed-identity-client-id-or-object-id>"
            ),
        },
    },
}

ActiveDirectoryMsi adalah mode ODBC untuk identitas terkelola yang ditetapkan sistem (SAMI) dan identitas terkelola yang ditetapkan pengguna (UAMI). Untuk UAMI, driver ODBC mengharapkan UID untuk mengidentifikasi identitas terkelola: gunakan ID klien untuk Azure App Service atau Azure Container Instance, jika tidak, gunakan ID objek. Masukkan itu UID ke dalam extra_params, karena extra_params diteruskan langsung ke driver ODBC.

Jika Anda menggunakan identitas terkelola, buat database pengujian secara manual dan lewati --keepdb saat Anda menjalankan pengujian unit.

Autentikasi perwakilan layanan (ActiveDirectoryServicePrincipal)

Gunakan pendaftaran aplikasi Microsoft Entra (service principal) ketika aplikasi Anda berjalan tanpa konteks pengguna dan identitas terkelola tidak tersedia.

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<application-client-id>",
        "PASSWORD": "<client-secret>",
        "HOST": "<your-server>.database.windows.net",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "Authentication=ActiveDirectoryServicePrincipal",
        },
    },
}

Jangan hardcode rahasia klien di settings.py. Gunakan variabel lingkungan atau manajer rahasia seperti Azure Key Vault untuk memberikan info masuk saat runtime.

Autentikasi terintegrasi (ActiveDirectoryIntegrated)

Gunakan autentikasi terintegrasi saat proses Django berjalan di bawah konteks pengguna yang bergabung dengan domain dan Anda ingin driver ODBC menukarkan identitas Windows atau Kerberos tersebut untuk autentikasi Microsoft Entra.

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "HOST": "<your-server>.database.windows.net",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "Authentication=ActiveDirectoryIntegrated",
        },
    },
}

Referensi autentikasi ODBC mendokuensikan mode ini pada Windows, dan di Linux atau macOS dengan ODBC Driver 17.6 dan versi yang lebih baru untuk lingkungan federasi.

Autentikasi interaktif (ActiveDirectoryInteractive)

Gunakan autentikasi interaktif untuk masuk pengguna lokal saat Anda ingin driver meminta kredensial dan menangani autentikasi multifaktor.

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<user@email.com>",
        "HOST": "<your-server>.database.windows.net",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "Authentication=ActiveDirectoryInteractive",
        },
    },
}

Dokumen referensi utama autentikasi ODBC mendokumentasikan ActiveDirectoryInteractive sebagai khusus Windows. Jika Anda berencana untuk menggunakannya di platform lain, validasi perilaku dengan versi driver yang tepat terlebih dahulu.

Autentikasi rantai kredensial default (ActiveDirectoryDefault)

Gunakan mode ini ketika Anda ingin driver ODBC menerapkan rantai kredensial Microsoft Entra defaultnya.

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "HOST": "<your-server>.database.windows.net",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "Authentication=ActiveDirectoryDefault",
        },
    },
}

mssql-django 1.7.3 dan versi yang lebih baru meneruskan mode ini ke driver ODBC. Jika Anda memerlukan kontrol eksplisit atas sumber kredensial atau perilaku refresh token, gunakan autentikasi token akses.

Autentikasi token akses (TOKEN)

Gunakan TOKEN saat Anda ingin kode Python Anda memperoleh token Microsoft Entra itu sendiri.

from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
token = credential.get_token("https://database.windows.net/.default").token

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "HOST": "<your-server>.database.windows.net",
        "PORT": "1433",
        "TOKEN": token,
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
        },
    },
}

Jalur ini berfungsi dengan kelas kredensial Python apa pun, termasuk DefaultAzureCredential, , ManagedIdentityCredentialdan ClientSecretCredential.

Token akses yang diambil di settings.py dievaluasi sekali pada proses startup dan biasanya kedaluwarsa setelah 60 hingga 90 menit. Jika proses Django Anda tetap berjalan melebihi masa berlaku token, Anda harus memperbarui token dalam kode aplikasi. Untuk sebagian besar aplikasi produksi yang berjalan lama, gunakan mode driver ODBC yang menyegarkan token secara otomatis, seperti ActiveDirectoryMsi atau ActiveDirectoryServicePrincipal.

Autentikasi kata sandi (ActiveDirectoryPassword, tidak digunakan lagi)

Important

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.

Jika Anda harus menggunakannya untuk skenario warisan, konfigurasikan secara eksplisit:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<user@email.com>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>.database.windows.net",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "Authentication=ActiveDirectoryPassword",
        },
    },
}

Konten terkait

  • Last updated on