Gunakan identitas terkelola tingkat database dengan Azure SQL Database (pratinjau)

Berlaku untuk:Azure SQL Database

Identitas terkelola tingkat basis data memberikan identitas terkelola yang ditetapkan pengguna (UAMI) miliknya sendiri kepada basis data individual di Azure SQL Database. Sebuah basis data yang memiliki identitas terkelola mengautentikasi ke Azure Storage sebagai dirinya sendiri, bukan sebagai server logis yang menampungnya.

Tanpa identitas tingkat basis data, setiap basis data pada server logis berbagi identitas terkelola server tersebut, sehingga semuanya mengakses penyimpanan yang sama. Identitas tingkat basis data mempersempit akses tersebut ke satu basis data, sehingga Anda dapat memberikan setiap basis data hanya penyimpanan yang dibutuhkan.

Anda memilih identitas dalam kredensial berlingkup database, kredensial yang sama yang digunakan kueri virtualisasi data untuk membaca file Parquet, CSV, dan Delta dari Azure Blob Storage atau Azure Data Lake Storage (ADLS) Gen2. Pilih antara dua nilai identitas kredensial:

Identitas autentikasi	Gunakan saat
`DATABASE MANAGED IDENTITY`	Akun penyimpanan berada di tenant Microsoft Entra yang sama dengan database.
`DATABASE FEDERATED CLIENT IDENTITY`	Akun penyimpanan berada di tenant yang berbeda, diakses melalui federated identity credential (FIC).

Note

Sebagai fitur pratinjau, teknologi yang tersaji dalam artikel ini tunduk pada Ketentuan Penggunaan Tambahan untuk Pratinjau Microsoft Azure.

Prerequisites

Sebuah Azure SQL Database pada server logis. Semua tier layanan dan semua region Azure mendukung fitur ini.
Identitas terkelola yang ditetapkan pengguna dalam langganan yang sama. Untuk latar belakang, lihat Identitas yang dikelola di Microsoft Entra untuk Azure SQL.
Izin untuk menetapkan peran pada akun penyimpanan target, seperti Owner atau User Access Administrator.
Akun Azure Blob Storage atau ADLS Gen2 yang menyimpan file yang ingin Anda kueri.

Important

Sebuah database hanya dapat memiliki satu identitas terkelola yang ditetapkan pengguna di tingkat database, berbeda dengan server logis yang dapat memiliki beberapa. Rencanakan identitas per database sebelum Anda menetapkannya.

Jika database menggunakan kunci yang dikelola pelanggan di tingkat database, database sudah memiliki identitas tingkat database, dan untuk kunci lintas tenant, ID klien federasi. Fitur ini menggunakan dua pengaturan yang sama. Berikan akses penyimpanan ke identitas atau aplikasi yang sudah ada daripada menetapkan yang baru. Jika Anda menetapkan identitas atau aplikasi yang berbeda, pertama-tama berikan akses ke kunci enkripsi. Kalau tidak, pembaruan bisa gagal, atau database kehilangan akses ke kuncinya.

Pilih penyewa yang sama atau lintas penyewa

Kedua walkthrough membuat kredensial dengan cakupan tingkat database dan mengueri data eksternal. Mereka berbeda dalam cara identitas mengakses akun penyimpanan.

Jika database dan akun penyimpanan berada dalam tenant yang sama, ikuti Gunakan identitas tingkat database dalam tenant yang sama.
Jika akun penyimpanan berada di tenant yang berbeda, ikuti Menggunakan identitas klien federasi lintas tenant.

Gunakan identitas tingkat basis data dalam tenant yang sama

Langkah 1: Membuat identitas terkelola yang ditetapkan pengguna

Buat identitas dan catat baik ID Sumber Daya maupun ID Objek (principal). Anda membutuhkan Resource ID untuk menetapkan identitas pada database. Anda hanya membutuhkan ID Objek (principal) untuk walkthrough lintas tenant, di mana ID tersebut mengidentifikasi subjek kredensial identitas federasi.

az identity create \
    --name <identity-name> \
    --resource-group <resource-group> \
    --location <region>

Untuk metode lain, lihat Kelola identitas terkelola yang ditetapkan pengguna.

Langkah 2: Tetapkan identitas ke basis data

Tetapkan UAMI ke database, bukan ke server logis. Penugasan ini menggunakan mekanisme yang sama seperti enkripsi data transparan tingkat basis data (TDE) dengan kunci yang dikelola pelanggan, yang dijelaskan dalam Kunci yang dikelola pelanggan tingkat basis data. Untuk seluruh metode penugasan, lihat Dapatkan atau atur identitas terkelola untuk basis data.

Untuk menetapkan identitas di portal Azure:

Buka/masuk ke database SQL Anda.
Di bawah Keamanan, pilih Identitas.
Di bawah User-Assigned Managed Identity, pilih Add.
Pilih identitas yang Anda buat, lalu pilih Tambah.
Pilih Simpan.

Untuk menetapkan identitas dengan Azure CLI, gunakan az sql db update:

az sql db update \
    --resource-group <resource-group> \
    --server <server-name> \
    --name <database-name> \
    --assign-identity \
    --user-assigned-identity-id <identity-resource-id>

Untuk menetapkannya dengan PowerShell, gunakan Set-AzSqlDatabase:

Set-AzSqlDatabase -ResourceGroupName <ResourceGroupName> -ServerName <ServerName> -DatabaseName <DatabaseName> -AssignIdentity -UserAssignedIdentityId <UserAssignedIdentityId>

Identitas ID Sumber Daya terlihat seperti /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>. Temukan di bawah Properti pada identitas yang dikelola di portal Azure.

Langkah 3: Berikan identitas akses ke penyimpanan

Berikan akses baca identitas terkelola ke akun penyimpanan:

Buka akun penyimpanan.
Pilih Access Control (IAM).
Pilih Tambahkan>Tambahkan penugasan peran.
Pilih peran Storage Blob Data Reader, lalu pilih Berikutnya.
Untuk Tetapkan akses ke, pilih Identitas Terkelola.
Pilih Pilih anggota, pilih identitas terkelola yang ditetapkan pengguna, lalu pilih Pilih.
Pilih Tinjau + beri tugas.

Untuk akses yang lebih rinci pada ADLS Gen2, atur daftar kontrol akses (ACL) pada direktori tertentu daripada menetapkan peran di tingkat akun. Untuk informasi lebih lanjut, lihat daftar kontrol akses di Azure Data Lake Storage.

Langkah 4: Buat kredensial dengan cakupan database

Hubungkan ke database pengguna Anda, bukan master, dan buat kredensial:

CREATE DATABASE SCOPED CREDENTIAL MyDBIdentityCred
WITH IDENTITY = 'DATABASE MANAGED IDENTITY';

Kredensial ini tidak memerlukan rahasia dan tidak memerlukan kunci master basis data. Mesin akan menentukan identitas yang diberikan ke database saat waktu kueri.

Ekuivalen di tingkat server menggunakan nilai IDENTITY yang berbeda. Membandingkan:

-- Server-level identity: every database on the logical server shares this access
CREATE DATABASE SCOPED CREDENTIAL MyServerIdentityCred
WITH IDENTITY = 'MANAGED IDENTITY';

-- Database-level identity: only this database has this access
CREATE DATABASE SCOPED CREDENTIAL MyDBIdentityCred
WITH IDENTITY = 'DATABASE MANAGED IDENTITY';

Untuk sintaks lengkap, lihat CREATE DATABASE SCOPED CREDENTIAL.

Langkah 5: Buat sumber data eksternal

Buat sumber data eksternal yang mengarah ke kontainer Anda, dan lampirkan kredensial. Gunakan awalan yang sesuai dengan tipe penyimpanan Anda:

Jenis penyimpanan	Awalan lokasi
Azure Blob Storage	`abs://`
ADLS Gen2	`adls://`

CREATE EXTERNAL DATA SOURCE MyExternalStorage
WITH (
    LOCATION = 'abs://<container>@<storage-account>.blob.core.windows.net',
    CREDENTIAL = MyDBIdentityCred
);

Langkah 6: Query data

Kueri file secara ad hoc dengan OPENROWSET:

SELECT TOP 100 *
FROM OPENROWSET(
    BULK 'sales/2026/*.parquet',
    DATA_SOURCE = 'MyExternalStorage',
    FORMAT = 'parquet'
) AS externalData;

Atau definisikan tabel eksternal untuk kueri berulang:

CREATE EXTERNAL FILE FORMAT ParquetFormat
WITH (FORMAT_TYPE = PARQUET);

CREATE EXTERNAL TABLE dbo.Sales
(
    OrderId int,
    OrderDate date,
    Amount decimal(10, 2)
)
WITH (
    LOCATION = 'sales/2026/',
    DATA_SOURCE = MyExternalStorage,
    FILE_FORMAT = ParquetFormat
);

SELECT TOP 100 * FROM dbo.Sales;

Gunakan identitas klien terfederasi lintas tenant

Gunakan jalur ini ketika database Anda berada di satu tenant dan akun penyimpanan berada di tenant lain. Pendaftaran aplikasi multitenant menjadi dasar hubungan kepercayaan antara keduanya: UAMI basis data menjadi subjek kredensial identitas federasi pada aplikasi tersebut, dan penyewa penyimpanan memberikan akses kepada principal layanan aplikasi ke data tersebut.

Pola ini cocok dengan kunci yang dikelola pelanggan lintas tenant untuk enkripsi data transparan, sehingga pengaturan ini terlihat familiar jika Anda sudah menggunakan fitur tersebut.

Langkah 1: Daftarkan aplikasi multitenant

Di tenant yang menyimpan database, daftarkan aplikasi multitenant di Microsoft Entra ID dan catat Application (client) ID-nya.

Untuk informasi selengkapnya, lihat Daftarkan aplikasi dengan platform identitas Microsoft.

Langkah 2: Tambahkan kredensial identitas federasi

Tambahkan kredensial identitas federasi ke aplikasi tersebut agar dapat memercayai identitas terkelola yang ditetapkan pengguna milik basis data. Aplikasi dan identitas yang dikelola harus berada dalam tenant Microsoft Entra yang sama.

Dalam pendaftaran aplikasi, pilih Sertifikat & rahasia>Kredensial federasi>Tambahkan kredensial.
Untuk skenario kredensial Federated, pilih Managed Identity.
Pilih identitas terkelola yang Anda buat pada Langkah 1 dari walkthrough penyewa yang sama.
Verifikasi bahwa Issuer yang terisi secara otomatis mengidentifikasi tenant Anda. Untuk cloud publik Azure, penerbitnya adalah https://login.microsoftonline.com/<tenant-id>/v2.0.
Pastikan Audience adalah api://AzureADTokenExchange, nilai untuk cloud publik Azure.
Masukkan nama unik untuk kredensial, lalu simpan.

Subjek kredensial adalah ID Objek (principal) identitas terkelola, bukan ID kliennya. Jika Anda mengonfigurasi kredensial secara manual, salin ID Objek (principal) secara tepat, karena subjek tersebut sensitif huruf besar/kecil. Microsoft Entra ID menerima nilai penerbit, subjek, atau audiens yang salah saat Anda menyimpan kredensial, tetapi pertukaran token gagal kemudian.

Untuk informasi lebih lanjut, lihat Konfigurasikan aplikasi untuk mempercayai identitas terkelola.

Pada tenant yang memegang akun penyimpanan:

Seorang administrator memberikan persetujuan pada aplikasi multitenant, yang membuat service principal di tenant tersebut.
Tetapkan peran Storage Blob Data Reader ke service principal tersebut di akun penyimpanan. Ikuti Langkah 3: Berikan akses identitas ke penyimpanan, tetapi untuk Assign access to, pilih User, group, or service principal, lalu pilih service principal aplikasi.

Langkah 4: Atur ID klien federasi pada database

Di tenant yang memuat database, tetapkan identitas terkelola yang ditetapkan pengguna ke database, dan atur Application (client) ID dari Langkah 1 sebagai Federated Client ID:

Akses database SQL Anda.
Di bawah Keamanan, pilih Identitas.
Di bawah User-Assigned Managed Identity, periksa apakah identitas dari Step 1 walkthrough penyewa yang sama tercantum. Jika tidak, pilih Tambah, pilih identitas, lalu pilih Tambah.
Di bawah Federated client identity, pilih aplikasi, lalu pilih Save.

Untuk mengaturnya dengan Azure CLI:

az sql db update \
    --resource-group <resource-group> \
    --server <server-name> \
    --name <database-name> \
    --assign-identity \
    --user-assigned-identity-id <identity-resource-id> \
    --federated-client-id <application-client-id>

Untuk mengaturnya dengan PowerShell:

Set-AzSqlDatabase -ResourceGroupName <ResourceGroupName> -ServerName <ServerName> -DatabaseName <DatabaseName> -AssignIdentity -UserAssignedIdentityId <UserAssignedIdentityId> -FederatedClientId <ApplicationClientId>

Langkah 5: Buat kredensial dan kueri

CREATE DATABASE SCOPED CREDENTIAL MyCrossTenantCred
WITH IDENTITY = 'DATABASE FEDERATED CLIENT IDENTITY';

CREATE EXTERNAL DATA SOURCE PartnerStorage
WITH (
    LOCATION = 'adls://<container>@<storage-account>.dfs.core.windows.net',
    CREDENTIAL = MyCrossTenantCred
);

Kemudian buat tabel eksternal atau jalankan OPENROWSET terhadap PartnerStorage persis seperti pada Langkah 6: Query data.

Bandingkan identitas tingkat server dan identitas tingkat basis data

Karakteristik	Identitas terkelola tingkat-server	Identitas terkelola pada tingkat basis data
Ruang lingkup identitas	Server logis	Database tunggal
Sintaks kredensial	`IDENTITY = 'MANAGED IDENTITY'`	`IDENTITY = 'DATABASE MANAGED IDENTITY'`
Akses penyimpanan lintas penyewa	Tidak didukung. Gunakan shared access signature sebagai gantinya	ID klien federasi yang diatur pada database, digunakan dengan `IDENTITY = 'DATABASE FEDERATED CLIENT IDENTITY'`
Granularitas RBAC penyimpanan	Satu identitas untuk setiap database di server	Satu identitas per basis data
Ruang lingkup paparan	Setiap database di server memiliki akses yang sama	Terbatas pada satu database
Jenis identitas	Ditetapkan oleh sistem atau pengguna	Hanya yang ditugaskan kepada pengguna
Kunci master database diperlukan	No	No

Kedua jenis kredensial dapat hidup berdampingan pada server logis yang sama dan di dalam databasenya. Pilih kredensial yang paling sesuai dengan kebutuhan keamanan Anda.

Geo-replikasi dan failover

Anda menetapkan identitas ke database, sehingga setiap replika membawa penetapan identitasnya sendiri. Konfigurasikan geo-sekunder dengan cara yang sama seperti utama sebelum Anda melakukan failover:

Tetapkan identitas terkelola yang ditetapkan pengguna yang sama yang digunakan oleh database utama ke database sekunder.
Berikan identitas tersebut akses penyimpanan yang sama seperti yang dijelaskan pada Langkah 3: Berikan akses identitas ke penyimpanan.
Untuk akses lintas tenant, atur identitas klien Federated yang sama pada database sekunder.

Ketika Anda mengonfigurasi kedua replika dengan cara ini, kueri yang menggunakan kredensial berlingkup basis data akan tetap berfungsi setelah failover. Persyaratan ini cocok dengan kunci yang dikelola pelanggan di tingkat basis data, yang juga membutuhkan identitas pada setiap replika.

Konfigurasi yang sama berlaku untuk geo-replikasi aktif dan grup failover.

Limitations

Azure SQL Database saja. Azure SQL Managed Instance, SQL Server, dan Azure Synapse Analytics tidak mendukung identitas kredensial ini.
Hanya untuk autentikasi outbound. Fitur ini tidak mengubah cara pengguna dan aplikasi melakukan otentikasi ke database.
Tidak didukung dalam database master. Buat kredensial di database pengguna.
Hanya identitas terkelola yang ditetapkan pengguna. Identitas terkelola yang diberikan sistem terikat pada server logis, sehingga tidak dapat bertindak sebagai identitas tingkat basis data.
Satu identitas terkelola yang ditetapkan pengguna per database.
Pratinjau ini hanya mencakup virtualisasi data: CREATE EXTERNAL TABLE dan OPENROWSET dengan DATA_SOURCE. Fitur keluar lainnya, seperti sp_invoke_external_rest_endpoint, tidak termasuk dalam cakupan.

Troubleshoot

Membuat kredensial dengan cakupan database tidak mengonfirmasi bahwa identitas database dapat mendapatkan token atau mengakses penyimpanan. Kesalahan muncul kemudian, saat Anda membuat sumber data eksternal atau menjalankan kueri yang menggunakan kredensial.

Identitas database tidak dikonfigurasi (kesalahan 15858)

Anda dapat membuat kredensial dengan IDENTITY = 'DATABASE MANAGED IDENTITY' sebelum Anda menetapkan identitas terkelola yang ditugaskan pengguna ke database. Jika sebuah query kemudian menggunakan kredensial dan database tidak memiliki identitas yang dapat digunakan untuk mendapatkan token, query gagal dengan error 15858:

Cannot obtain a Microsoft Entra ID token to access storage. Error message: 'Azure SQL Server or Database identity is not configured. Please follow the steps in "Assign a Microsoft Entra managed identity to your Azure SQL" (https://aka.ms/SQLDBMSI)'.

Tetapkan identitas terkelola yang ditugaskan pengguna ke database, seperti yang dijelaskan pada Langkah 2, berikan akses ke akun penyimpanan, lalu coba ulang kueri. Menetapkan identitas hanya pada server logis tidak mengonfigurasi identitas tingkat basis data. Jika penugasan basis data sudah ada dan kesalahan tetap terjadi, hubungi Microsoft Support untuk menyelidiki provisioning identitas basis data.

Note

Trace flag 4675 dan langkah hapus dan buat ulang di Pencadangan dan pemulihan ke URL menggunakan identitas terkelola berlaku untuk SQL Server di Azure VM. Hal tersebut tidak berlaku untuk identitas terkelola tingkat database di Azure SQL Database.

Kredensial tidak dapat ditemukan atau direferensikan (kesalahan 46516)

Saat Anda membuat sumber data eksternal, Azure SQL Database memeriksa apakah kredensial tersebut ada di database saat ini dan Anda memiliki izin untuk merujuknya. Jika salah satu pemeriksaan gagal, Anda mendapatkan error 46516:

The specified credential cannot be found or the user does not have permission to perform this action.

Buat kredensial di database yang berisi sumber data eksternal, periksa nama kredensial, dan pastikan Anda memiliki izin untuk mereferensikan kredensial tersebut.

Akuisisi token gagal (kesalahan 15858)

Ketika database tidak dapat mendapatkan token Microsoft Entra dan penyedia token mengembalikan alasan, kesalahan 15858 mencakup alasan tersebut:

Cannot obtain a Microsoft Entra ID token to access storage. Error message: '<details>'.

Gunakan pesan kesalahan bersarang untuk mengetahui mengapa permintaan token gagal. Untuk akses lintas tenant, periksa aplikasi, persetujuan admin di tenant penyimpanan, dan kredensial identitas federasi, seperti yang dijelaskan dalam Konfigurasikan aplikasi untuk mempercayai identitas terkelola.

Untuk membaca data eksternal, identitas juga membutuhkan peran data storage. Untuk akses dengan tenant yang sama, berikan Storage Blob Data Reader pada kontainer atau akun penyimpanan ke identitas terkelola yang ditetapkan pengguna milik database. Untuk akses lintas tenant, berikan kepada service principal aplikasi di tenant penyimpanan. Untuk informasi selengkapnya, lihat Menetapkan peran Azure untuk akses ke data blob.

File tidak ada atau tidak dapat diakses (kesalahan 4860)

Ketika file hilang atau tidak dapat dibaca, Anda mendapatkan kesalahan 4860:

Cannot bulk load. The file "<path>" does not exist or you don't have file access rights. See https://go.microsoft.com/fwlink/?LinkId=2374938 for more information.

Periksa bahwa file ada di lokasi yang dikonfigurasi. Kemudian periksa apakah identitas yang digunakan oleh permintaan dapat mengaksesnya, melalui peran data penyimpanan atau, untuk ADLS Gen2, daftar kontrol akses (ACL) pada jalur.

Akses jaringan diblokir (kesalahan 42121 dan 16539)

Ketika server logis terkait dengan perimeter keamanan jaringan yang tidak mengizinkan lalu lintas keluar ke akun penyimpanan, Anda mendapatkan error 42121:

The operation could not be completed because attempts to connect were denied by the configured Network Security Perimeter.

Tambahkan aturan akses keluar untuk nama host akun penyimpanan ke profil perimeter, atau kaitkan akun penyimpanan dengan perimeter yang sama. Untuk informasi lebih lanjut, lihat Network security perimeter untuk Azure SQL Database.

Ketika jaringan keluar dibatasi pada server logis dan akun penyimpanan tidak ada dalam aturan firewall keluar server, Anda mendapatkan kesalahan 16539:

Operation failed since the external data source '<external-data-source>' has underlying storage account that is not in the list of Outbound Firewall Rules on the server. Please add this storage account to the list of Outbound Firewall Rules on your server and retry the operation.

Tambahkan aturan firewall keluar untuk nama host penyimpanan yang tepat di lokasi sumber data eksternal. Untuk informasi lebih lanjut, lihat Aturan firewall Outbound untuk Azure SQL Database dan Azure Synapse Analytics.

Konfigurasi lintas tenant hilang atau salah (kesalahan 16561 dan 16562)

Kueri lintas tenant dapat gagal dengan salah satu kesalahan ini, atau dengan kesalahan 4860:

External table '<table-name>' is not accessible because content of directory cannot be listed.

External table '<table-name>' is not accessible because location does not exist or it is used by another process.

Kesalahan ini berarti kueri tidak dapat mencapai file-file tersebut. Identitas mungkin tidak memiliki peran penyimpanan yang diperlukan, akses jaringan mungkin diblokir, lokasi penyimpanan mungkin tidak dapat di-resolve, atau token mungkin untuk tenant yang salah. Untuk memperbaikinya:

Berikan peran data penyimpanan yang sesuai.
Izinkan akses jaringan ke akun penyimpanan.
Sertakan kontainer di lokasi sumber data eksternal.
Gunakan DATABASE FEDERATED CLIENT IDENTITY, dan atur Federated Client ID pada database, seperti yang dijelaskan pada Langkah 4.
Konfirmasi bahwa subjek kredensial identitas terfederasi harus sama persis dengan ID Objek (principal) identitas yang dikelola.

Kueri gagal setelah failover

Jika kueri gagal dengan kesalahan token atau otorisasi setelah failover, primary baru mungkin tidak memiliki identitas terkelola yang ditetapkan pengguna sama seperti yang digunakan primary asli. Atau identitas tersebut mungkin tidak memiliki penugasan peran di akun penyimpanan. Tetapkan identitas yang sama untuk kedua replika dan berikan identitas tersebut akses ke penyimpanan, seperti yang dijelaskan dalam Geo-replikasi dan failover.

Tanya jawab umum

Apakah kredensial tingkat server dan basis data dapat hidup berdampingan pada server yang sama?

Ya, di server logis yang sama dan di database yang sama. Nilai setiap kredensial IDENTITY menentukan identitas mana yang digunakan oleh kueri: MANAGED IDENTITY menggunakan identitas server, dan DATABASE MANAGED IDENTITY menggunakan identitas database.

Bisakah saya menggunakan identitas terkelola yang ditetapkan oleh sistem?

No. Identitas terkelola yang ditetapkan sistem milik server logis, jadi Anda tidak dapat membatasinya ke satu basis data saja. Gunakan identitas terkelola yang ditetapkan pengguna.

Tingkat layanan dan wilayah mana yang mendukung pratinjau ini?

Semua tingkat layanan Azure SQL Database di semua wilayah Azure.

Apakah saya perlu kunci master database?

No. Baik DATABASE MANAGED IDENTITY maupun DATABASE FEDERATED CLIENT IDENTITY tidak menggunakan secret, jadi tidak diperlukan kunci utama.

Apakah fitur ini bekerja dengan sp_invoke_external_rest_endpoint?

Tidak di pratinjau ini. Pratinjau mencakup virtualisasi data.

Saran dan Komentar

Apakah halaman ini membantu?

Terakhir diperbarui pada 2026-10-30