Mengonfigurasi kunci yang dikelola pelanggan di berbagai penyewa

Artikel ini menjelaskan skenario lintas penyewa tempat penyedia layanan menghosting Pencarian Azure AI di penyewa mereka sendiri dan mengaktifkan enkripsi kunci yang dikelola pelanggan (CMK) menggunakan aplikasi Microsoft Entra multipenyewa.

Dalam konfigurasi ini, pelanggan menggunakan Azure Key Vault di penyewa mereka sendiri untuk mengelola kunci enkripsi mereka. Penyedia layanan tidak memiliki akses ke kunci ini.

Prasyarat

• Tenant A: Tenant dengan izin yang diperlukan untuk membuat layanan Pencarian Azure AI dan objek terkait (indeks, daftar sinonim, indexer, data source, vectorizer, kumpulan keterampilan). Dukungan untuk kunci yang dikelola pelanggan (CMK) memerlukan tingkat harga Dasar atau yang lebih tinggi.

• Konfigurasikan layanan pencarian untuk akses berbasis peran (disarankan untuk keamanan yang ditingkatkan, tidak diperlukan).

• Tenant B: Tenant pelanggan yang terpisah dengan Azure Key Vault dan izin yang diperlukan pada tenant tersebut:

  • Key Vault Contributor: Peran ini diperlukan jika Anda perlu membuat key vault baru.
  • Izin untuk mendaftarkan aplikasi di Microsoft Entra ID: Untuk menginstal aplikasi multitenan yang dikonfigurasi oleh penyedia layanan untuk CMK lintas penyewa, Anda harus memiliki izin untuk membuat pendaftaran aplikasi di Microsoft Entra ID. Ini biasanya memerlukan peran Pengembang Aplikasi atau peran administratif yang lebih tinggi, seperti Administrator Aplikasi atau Administrator Global.
  • Key Vault Crypto Officer: Peran ini diperlukan untuk menambahkan kunci baru ke key vault.
  • Key Vault Crypto Service Encryption User: Peran ini harus ditetapkan kepada prinsipal layanan yang dibuat untuk aplikasi multitenan yang diinstal agar prinsipal layanan tersebut dapat mengakses kunci yang dikelola pelanggan di Key Vault. Anda harus memiliki izin Administrator Akses Pengguna untuk melakukan ini. Anda dapat melihat GUID prinsipal layanan (juga dikenal sebagai ID Objek) di bawah: Enterprise applications\<installed multitenant application>\Manage\Properties\Object ID.

• Azure Key Vault juga harus konfigurasi untuk akses berbasis peran.

• Azure CLI untuk mengirim permintaan.

Pilih pendekatan autentikasi

Anda dapat mengonfigurasi aplikasi Microsoft Entra multipenyewa untuk menggunakan kunci yang dikelola pelanggan dalam skenario lintas penyewa dengan menggunakan salah satu pendekatan berikut:

1. Dukungan identitas gabungan (pratinjau, disarankan): Mengonfigurasi kredensial identitas federasi (FIC) Microsoft Entra dengan identitas terkelola yang ditetapkan pengguna (UAMI). Pendekatan ini menggunakan token identitas terkelola dan menukarnya dengan token akses, menghilangkan kebutuhan akan rahasia berumur panjang dan selaras dengan prinsip federasi identitas beban kerja. Pendekatan ini memerlukan properti pratinjau federatedIdentityClientId , yang diperkenalkan dalam versi 2026-05-01-previewAPI .

2. Rahasia klien: Mengonfigurasi rahasia klien menggunakan accessCredentials properti . Pendekatan ini kurang aman dan memerlukan pengelolaan tambahan untuk merotasi dan melindungi secret tersebut.

Membuat aplikasi Microsoft Entra multipenyewa di penyewa A

Gunakan Azure CLI untuk mengirim permintaan. Tenant milik penyedia layanan yang berisi Pencarian Azure AI akan disebut sebagai tenant A.

1. Dapatkan ID penyewa: az account show --query tenantId --output tsv

2. Pastikan Anda masuk ke tenant A: az login --tenant \<tenant-A-id\>

3. Buat pendaftaran aplikasi: az ad app create --display-name cross-tenant-auth --sign-in-audience AzureADMultipleOrgs

4. Simpan output ID aplikasi dari langkah ini.

Gunakan dukungan identitas gabungan (pratinjau)

Untuk menggunakan identitas terfederasi guna mendukung skenario CMK lintas-tenant:

1. Penyedia layanan mengonfigurasi layanan Pencarian AI di penyewa mereka (Penyewa A). Untuk panduan tentang cara melakukannya, lihat Buat Layanan Pencarian (di portal Azure) atau gunakan perintah az search service create di Azure CLI.

2. Penyedia layanan membuat registrasi aplikasi Microsoft Entra multitenan. Untuk panduan tentang cara melakukannya, lihat Cara mendaftarkan aplikasi di Microsoft Entra ID, atau gunakan perintah Azure CLI: az ad app create. Rekam ID Aplikasi (klien) setelah Anda menyelesaikan pendaftaran aplikasi.

3. Penyedia layanan menyiapkan identitas terkelola yang ditetapkan pengguna. Untuk panduan tentang cara melakukannya, lihat Kelola identitas terkelola yang ditetapkan pengguna menggunakan portal Azure atau Kelola identitas terkelola yang ditetapkan pengguna menggunakan Azure CLI.

4. Penyedia layanan mengonfigurasi identitas terkelola yang ditetapkan pengguna sebagai kredensial identitas federasi pada aplikasi. Untuk panduan tentang cara melakukannya, lihat Mengonfigurasi aplikasi untuk mempercayai penyedia identitas eksternal.

5. Setelah penyedia layanan membagikan ID aplikasi multitenant, pelanggan memberikan aplikasi penyedia layanan akses ke Key Vault di tenant mereka (Tenant B). Untuk menginstal aplikasi di tenant B, prinsipal layanan harus dibuat dengan ID aplikasi multitenant. Untuk membuat perwakilan layanan, buat URL admin-consent dan berikan persetujuan di seluruh tenant, atau gunakan perintah az ad sp di Azure CLI.

6. Jika pelanggan belum memiliki brankas kunci untuk digunakan, lihat Mulai Cepat - Membuat Azure Key Vault dengan portal Azure atau Mulai Cepat - Membuat Azure Key Vault dengan Azure CLI. Key Vault memerlukan model izin yang diatur ke "kontrol akses berbasis peran Azure (RBAC)", dengan aplikasi multitenant penyedia layanan diberi izin dengan menugaskan peran Pengguna Enkripsi Layanan Kripto Key Vault. Pelanggan kemudian dapat membuat kunci enkripsi. Untuk panduan tentang cara melakukannya, lihat Memberikan izin kepada aplikasi untuk mengakses brankas kunci Azure menggunakan Azure RBAC.

Setelah langkah-langkah ini selesai, penyedia layanan sekarang memiliki:

• ID aplikasi dari aplikasi multipenyewa yang diinstal di penyewa pelanggan dan telah diberikan akses ke kunci yang dikelola oleh pelanggan.

• Identitas terkelola yang dikonfigurasi sebagai kredensial federasi pada aplikasi multitenan.

• Lokasi kunci di brankas kunci pelanggan.

Dengan ketiga parameter ini, penyedia layanan sekarang dapat membuat objek Pencarian Azure AI di Tenant A yang dapat dienkripsi dengan kunci yang dikelola pelanggan yang disimpan di Tenant B. Untuk panduan tentang cara mengonfigurasi kunci yang dikelola pelanggan pada objek pencarian baru, lihat Konfigurasi kunci yang dikelola pelanggan untuk data terenkripsi Pencarian Azure AI.

Memvalidasi konfigurasi CMK lintas penyewa identitas federasi

Setelah Anda mengonfigurasi aplikasi Microsoft Entra multipenyewa dan menyambungkannya ke Key Vault pelanggan, verifikasi penyiapan dengan membuat objek pengujian di layanan pencarian Anda (penyewa A). Contoh ini membuat indeks untuk mengonfirmasi bahwa layanan pencarian dapat mengakses kunci yang dikelola pelanggan menggunakan autentikasi identitas federasi.

1. Lihat Konfigurasi kunci yang dikelola pelanggan untuk data terenkripsi Pencarian Azure AI untuk panduan tentang cara membuat layanan pencarian dan objek indeks baru dengan kunci yang dikelola pelanggan.

2. Setelah objek indeks dibuat, Anda harus mengisi hal berikut:

   • keyVaultUri: Alamat URI dari pelanggan.
   • keyVaultKeyName: Nama kunci dari pelanggan.
   • keyVaultKeyVersion: Versi kunci milik pelanggan.
   • userAssignedIdentity: <subscription-id> dan <resource-group> dari tenant Anda, dan <identity-name> adalah nama identitas terkelola yang ditetapkan pengguna.
   • federatedIdentityClientId: Nilai properti ini, <application-client-id>, akan menjadi ID aplikasi (klien) multitenan.

   {
     "name": "cross-tenant-cmk-test",
     "fields": [
       {
         "name": "id",
         "type": "Edm.String",
         "key": true
       }
     ],
     "encryptionKey": {
       "keyVaultUri": "https://<key-vault-name>.vault.azure.net/",
       "keyVaultKeyName": "<key-name>",
       "keyVaultKeyVersion": "<key-version>",
       "identity": {
         "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
         "userAssignedIdentity": "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>",
         "federatedIdentityClientId": "<application-client-id>"
       }
     }
   }
   

3. Verifikasi indeks dengan mengirimkan permintaan GET: GET https://<search-service>.search.windows.net/indexes/cross-tenant-cmk-test?api-version=2026-08-01-preview

Jika permintaan berhasil, konfigurasi CMK lintas penyewa berfungsi sebagaimana mestinya.

Jika pembuatan indeks gagal dengan kesalahan akses kunci, verifikasi bahwa:

• Identitas terkelola yang ditetapkan pengguna dikonfigurasi dengan benar
• Kredensial identitas federasi diatur pada aplikasi
• Kebijakan akses Key Vault atau penetapan peran RBAC sudah benar

Gunakan rahasia klien (jika menggunakan identitas federasi bukan opsi)

Jika identitas federasi bukan opsi, Anda dapat menambahkan rahasia klien ke aplikasi multipenyewa untuk mendukung skenario CMK lintas penyewa:

1. Untuk menambahkan rahasia klien ke aplikasi multipenyewa di penyewa A, jalankan perintah berikut:

   az ad app credential reset --id <multitenant-app-id>

2. Simpan output kata sandi dari langkah ini. Output kata kunci merupakan input yang diperlukan untuk menyiapkan CMK di Pencarian Azure AI.

3. Untuk menentukan kapan rahasia klien kedaluwarsa, Anda dapat menentukan parameter tanggal akhir ke perintah ini.

   az ad app credential reset --id <multitenant-app-id> --end-date <end-date>

   Parameter tanggal akhir menerima tanggal dalam format ISO 8601. Misalnya: az ad app credential reset --id <multitenant-app-id> --end-date 2026-12-31.

Buat prinsipal layanan di penyewa B untuk aplikasi multipenyewa

Kami merujuk ke penyewa yang berisi Azure Key Vault sebagai penyewa B. Di penyewa B, buat perwakilan layanan untuk aplikasi multipenyewa di penyewa A.

1. Masuk ke tenant B:

   az login --tenant <tenant-B-id>

2. Buat service principal menggunakan output ID aplikasi multitenant dari langkah pertama.

   az ad sp create --id <multitenant-app-id>

   Prinsipal layanan ini adalah instans dari aplikasi multipenyewa di penyewa A. Peran yang ditetapkan ke prinsipal layanan ini di penyewa B juga ditetapkan ke aplikasi multipenyewa di penyewa A.

3. Verifikasi tautan antara penyewa A dan B dengan meninjau "appOwnerOrganizationId" dalam perintah berikut:

   az ad sp show --id <multitenant-app-id>

   Perintah ini menampilkan detail service principal dalam format JSON. Cari bidang "appOwnerOrganizationId" dalam output untuk mengonfirmasi bahwa ID penyewa A cocok.

4. Simpan ID objek perwakilan layanan (dari kolom "id") pada langkah ini. ID objek adalah input yang diperlukan untuk menyiapkan CMK di Pencarian Azure AI.

5. Dapatkan ID sumber daya untuk Azure Key Vault:

   az keyvault show --name <key-vault-name> --query id --output tsv

6. Tetapkan peran Pengguna Enkripsi Layanan Kripto Key Vault pada brankas kunci di penyewa B ke perwakilan layanan baru.

   az role assignment create --assignee <service-principal-object-id> --role "Key Vault Crypto Service Encryption User" --scope <key-vault-resource-id>

   Contoh penugasan ini mungkin terlihat seperti ini:

   az role assignment create --assignee 00001111-aaaa-2222-bbbb-3333cccc4444 --role "Key Vault Crypto Service Encryption User" --scope /subscriptions/87654321-4321-4321-4321-210987654321/resourceGroups/myKeyVaultRG/providers/Microsoft.KeyVault/vaults/myCompanyKeyVault

Memvalidasi konfigurasi CMK lintas penyewa rahasia klien

Setelah Anda mengonfigurasi aplikasi Microsoft Entra multipenyewa dan menyambungkannya ke Key Vault pelanggan, verifikasi penyiapan dengan membuat objek pengujian di layanan pencarian Anda (penyewa A). Contoh ini membuat indeks untuk mengonfirmasi bahwa layanan pencarian dapat mengakses kunci yang dikelola pelanggan menggunakan rahasia klien.

1. Lihat Konfigurasi kunci yang dikelola pelanggan untuk data terenkripsi Pencarian Azure AI untuk panduan tentang cara membuat layanan pencarian dan objek indeks baru dengan kunci yang dikelola pelanggan.

2. Anda dapat menggunakan portal Azure untuk menambahkan indeks dan menyediakan JSON ini, atau menggunakan klien REST untuk mengirim permintaan />

   • keyVaultUri: Alamat URI dari pelanggan.
   • keyVaultKeyName: Nama kunci dari pelanggan.
   • keyVaultKeyVersion: Versi kunci milik pelanggan.
   • accessCredentials applicationId: adalah sesuatu seperti 00001111-aaaa-2222-bbbb-3333cccc4444, dan applicationSecret adalah nilai yang baru saja Anda buat.

{
  "name": "cross-tenant-cmk-test",
  "fields": [
        {
            "name": "id",
            "type": "Edm.String",
            "key": true
        }
      ],
 "encryptionKey": {
        "keyVaultUri": "https://<key-vault-name>.vault.azure.net/",
        "keyVaultKeyName": "<key-name>",
        "keyVaultKeyVersion": "<key-version>",
    "accessCredentials": {
      "applicationId": "<application-client-id>",
      "applicationSecret": "<application-client-secret>"
    }
  }
}

Pastikan indeks berhasil dibuat:

GET https://<search-service>.search.windows.net/indexes/cross-tenant-cmk-test?api-version=2026-04-01

Untuk informasi selengkapnya tentang cara memutar atau mengelola kunci, lihat Mengonfigurasi kunci yang dikelola pelanggan untuk enkripsi data.