Mengonfigurasi kunci yang dikelola pelanggan (CMK) untuk enkripsi data saat tidak digunakan pada kluster Azure DocumentDB

Dalam artikel ini, Anda mempelajari cara mengonfigurasi kunci yang dikelola pelanggan (CMK) untuk enkripsi data tidak aktif di Azure DocumentDB. Langkah-langkah dalam panduan ini mengonfigurasi kluster Azure DocumentDB baru, kluster replika, atau kluster yang dipulihkan. Penyiapan CMK menggunakan kunci yang dikelola pelanggan yang disimpan di Azure Key Vault dan identitas terkelola yang ditetapkan pengguna.

Prasyarat

• Langganan Azure

  • Jika Anda tidak memiliki langganan Azure, buat akun gratis

• Gunakan lingkungan Bash di Azure Cloud Shell. Untuk informasi selengkapnya, lihat Mulai menggunakan Azure Cloud Shell.

  

• Jika Anda lebih suka menjalankan perintah referensi CLI secara lokal, instal Azure CLI. Jika Anda menjalankan Windows atau macOS, pertimbangkan untuk menjalankan Azure CLI dalam kontainer Docker. Untuk informasi lebih lanjut, lihat Cara menjalankan Azure CLI di kontainer Docker.

  • Jika Anda menggunakan instalasi lokal, masuk ke Azure CLI dengan menggunakan perintah az login. Untuk menyelesaikan proses autentikasi, ikuti langkah-langkah yang ditampilkan di terminal Anda. Untuk opsi masuk lainnya, lihat Mengautentikasi ke Azure menggunakan Azure CLI.

  • Saat diminta, instal ekstensi Azure CLI saat pertama kali digunakan. Untuk informasi selengkapnya tentang ekstensi, lihat Menggunakan dan mengelola ekstensi dengan Azure CLI.

  • Jalankan az version untuk menemukan versi dan pustaka dependen yang terinstal. Untuk meng-upgrade ke versi terbaru, jalankan az upgrade.

Menyiapkan identitas terkelola yang ditetapkan pengguna dan Azure Key Vault

Untuk mengonfigurasi enkripsi kunci yang dikelola pelanggan di kluster Azure DocumentDB for MonogDB, Anda memerlukan identitas terkelola yang ditetapkan pengguna, instans Azure Key Vault, dan izin yang dikonfigurasi dengan benar.

Penting

Identitas terkelola yang ditetapkan pengguna dan instans Azure Key Vault yang digunakan untuk mengonfigurasi CMK harus berada di wilayah Azure yang sama di mana kluster Azure DocumentDB dihosting dan semuanya termasuk dalam penyewa Microsoft yang sama.

Menggunakan portal Microsoft Azure:

1. Buat satu identitas terkelola yang ditetapkan pengguna di wilayah kluster, jika Anda belum memilikinya.

2. Buat satu Azure Key Vault di wilayah kluster, jika Anda belum memiliki satu penyimpanan kunci yang dibuat. Pastikan Anda memenuhi persyaratan. Selain itu, ikuti rekomendasi sebelum Anda mengonfigurasi penyimpanan kunci, dan sebelum Anda membuat kunci dan menetapkan izin yang diperlukan ke identitas terkelola yang ditetapkan pengguna.

3. Buat satu kunci di penyimpanan kunci Anda.

4. Berikan izin identitas terkelola yang ditetapkan pengguna ke instans Azure Key Vault seperti yang diuraikan dalam persyaratan.

Mengonfigurasi enkripsi data dengan kunci yang dikelola pelanggan selama provisi kluster

Portal

1. Pada saat penyediaan kluster Azure DocumentDB baru, kunci yang dikelola layanan atau pelanggan untuk enkripsi data kluster dikonfigurasi di tab Enkripsi. Pilih Kunci yang dikelola pelanggan untuk Enkripsi data.

   

2. Di bagian Identitas terkelola yang ditetapkan pengguna pilih Ubah identitas.

   

3. Dalam daftar identitas terkelola yang ditetapkan pengguna, pilih identitas yang Anda inginkan untuk digunakan kluster Anda untuk mengakses kunci enkripsi data yang disimpan di Azure Key Vault.

   

4. Pilih Tambahkan.

   

5. Di metode Pemilihan kunci, pilih Pilih kunci .

6. Di bagian Kunci , pilih Ubah kunci .

   

7. Di panel Pilih kunci pilih Azure Key Vault di Brankas kunci dan kunci enkripsi di Kunci, dan konfirmasikan pilihan Anda dengan memilih Pilih.

   

   Penting

   Instans Azure Key Vault yang dipilih harus berada di wilayah Azure yang sama tempat kluster Azure DocumentDB akan dihosting.

8. Konfirmasi identitas terkelola dan kunci enkripsi yang ditetapkan pengguna yang dipilih pada tab Enkripsi dan pilih Tinjau + buat untuk membuat kluster.

   

REST API

Anda dapat mengaktifkan enkripsi data dengan kunci enkripsi yang ditetapkan pengguna, saat menyediakan kluster baru, melalui az rest perintah.

1. Buat file JSON dengan konten berikut. Ganti tempat penampung yang dimulai dengan $ tanda dengan nilai aktual dan simpan file.

   {
       "identity": {
           "type": "UserAssigned",
           "userAssignedIdentities": {
             "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName": {}
           }
         },
     "location": "$regionName",
         "properties": {
           "administrator": {
             "userName": "$adminName",
             "password": "$complexPassword"
           },
           "serverVersion": "8.0",
           "storage": {
             "sizeGb": 32
           },
           "compute": {
             "tier": "M40"
           },
           "sharding": {
             "shardCount": 1
           },
           "highAvailability": {
             "targetMode": "ZoneRedundantPreferred"
           },
         "encryption": {
             "customerManagedKeyEncryption": {
               "keyEncryptionKeyIdentity": {
                 "identityType": "UserAssignedIdentity",
                 "userAssignedIdentityResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName"
               },
               "keyEncryptionKeyUrl": "$encryptionKeyUrl"
             }
           }
         }
   }
   

   Nota

   keyEncryptionKeyUrl harus berisi nama kunci tetapi tidak boleh berisi versi kunci tertentu.

2. Jalankan perintah Azure CLI berikut untuk melakukan panggilan REST API untuk membuat kluster Azure DocumentDB. Ganti tempat penampung di bagian variabel dan nama file untuk --body parameter di az rest baris perintah dengan nilai aktual.

   # Define your variables
   $randomIdentifier = (New-Guid).ToString().Substring(0,8)
   $subscriptionId="00000000-0000-0000-0000-000000000000"
   $resourceGroup="DocumentDB"
   $mongoClustersName="msdocscr$randomIdentifier"
   
   # Execute the az rest command to make REST API call
   az rest --method "PUT" --url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/mongoClusters/${mongoClustersName}?api-version=2025-09-01 --body  @jsonFileFromThePreviousStep.json
   

Memperbarui pengaturan enkripsi data pada kluster dengan CMK diaktifkan

Untuk kluster yang ada yang disebarkan dengan enkripsi data menggunakan kunci yang dikelola pelanggan, Anda dapat melakukan beberapa perubahan konfigurasi. Anda dapat mengubah brankas kunci tempat kunci enkripsi disimpan dan kunci enkripsi yang digunakan sebagai kunci yang dikelola pelanggan. Anda juga dapat mengubah identitas terkelola yang ditetapkan pengguna yang digunakan oleh layanan untuk mengakses kunci enkripsi yang disimpan di penyimpanan kunci.

Portal

1. Pada bilah sisi kluster, di bawah Pengaturan, pilih Enkripsi data.

2. Di bagian Identitas terkelola yang ditetapkan pengguna pilih Ubah identitas.

   

3. Dalam daftar identitas terkelola yang ditetapkan pengguna, pilih identitas yang Anda inginkan untuk digunakan kluster Anda untuk mengakses kunci enkripsi data yang disimpan di Azure Key Vault.

   

4. Pilih Tambahkan.

5. Di metode Pemilihan kunci, pilih Pilih kunci .

6. Di Kunci, pilih Ubah kunci.

   

7. Di panel Pilih kunci pilih Azure Key Vault di Brankas kunci dan kunci enkripsi di Kunci, dan konfirmasikan pilihan Anda dengan memilih Pilih.

   

   Penting

   Instans Azure Key Vault yang dipilih harus berada di wilayah Azure yang sama tempat kluster Azure DocumentDB dihosting.

8. Konfirmasi identitas terkelola dan kunci enkripsi yang ditetapkan pengguna yang dipilih pada halaman Enkripsi data dan pilih Simpan untuk mengonfirmasi pilihan Anda dan membuat kluster replika.

   

REST API

Anda dapat mengubah identitas terkelola dan kunci enkripsi yang ditetapkan pengguna untuk enkripsi data pada kluster yang ada melalui panggilan REST API.

1. Buat file JSON dengan konten berikut. Ganti tempat penampung yang dimulai dengan $ tanda dengan nilai aktual dan simpan file.

   {
       "identity": {
           "type": "UserAssigned",
           "userAssignedIdentities": {
             "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName": {}
           }
         },
     "location": "$regionName",
         "properties": {
           "encryption": {
             "customerManagedKeyEncryption": {
               "keyEncryptionKeyIdentity": {
                 "identityType": "UserAssignedIdentity",
                 "userAssignedIdentityResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName"
               },
               "keyEncryptionKeyUrl": "$encryptionKeyUrl"
             }
           }
         }
   }
   

   Nota

   keyEncryptionKeyUrl harus berisi nama kunci tetapi tidak boleh berisi versi kunci tertentu.

2. Jalankan perintah Azure CLI berikut untuk melakukan panggilan REST API untuk membuat kluster Azure DocumentDB. Ganti tempat penampung di bagian variabel dan nama file untuk --body parameter di az rest baris perintah dengan nilai aktual.

   # Define your variables
   $subscriptionId="00000000-0000-0000-0000-000000000000"
   $resourceGroup="resourceGroupName"
   $mongoClustersName="clusterName"
   
   # Execute the az rest command to make REST API call
   az rest --method "PUT" --url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/mongoClusters/${mongoClustersName}?api-version=2025-09-01 --body  @jsonFileFromThePreviousStep.json
   

Apakah Anda hanya ingin mengubah identitas terkelola yang ditetapkan pengguna yang digunakan untuk mengakses kunci, atau Anda hanya ingin mengubah kunci yang digunakan untuk enkripsi data, atau Anda ingin mengubah keduanya secara bersamaan, Anda harus menyediakan semua parameter yang tercantum dalam file JSON.

Jika kunci atau identitas terkelola yang ditetapkan pengguna yang ditentukan tidak ada, Anda akan mendapatkan kesalahan.

Identitas yang diteruskan sebagai parameter, jika ada dan valid, secara otomatis ditambahkan ke daftar identitas terkelola yang ditetapkan pengguna yang terkait dengan kluster Azure DocumentDB Anda. Ini tetap terjadi bahkan jika perintah nanti gagal dengan kesalahan lain.

Mengubah mode enkripsi data pada kluster yang ada

Satu-satunya titik di mana Anda dapat memutuskan apakah Anda ingin menggunakan kunci yang dikelola layanan atau kunci yang dikelola pelanggan (CMK) untuk enkripsi data, adalah pada waktu pembuatan kluster. Setelah membuat keputusan tersebut dan membuat kluster, Anda tidak dapat beralih di antara dua opsi. Untuk membuat salinan kluster Azure DocumentDB dengan opsi enkripsi yang berbeda, Anda dapat membuat kluster replika atau melakukan pemulihan kluster dan memilih mode enkripsi baru selama kluster replika atau pembuatan kluster yang dipulihkan.

Mengaktifkan atau menonaktifkan enkripsi data kunci yang dikelola pelanggan (CMK) selama pembuatan kluster replika

Ikuti langkah-langkah ini untuk membuat kluster replika dengan enkripsi data CMK atau SMK untuk mengaktifkan atau menonaktifkan CMK pada kluster replika.

Portal

1. Pada bilah sisi kluster, di bawah Pengaturan, pilih Distribusi global.

2. Pilih Tambahkan replika baca baru.

   

3. Berikan nama kluster replika di bidang Nama replika baca .

4. Pilih wilayah di Wilayah replika baca. Kluster replika dihosting di wilayah Azure yang dipilih.

   Nota

   Kluster replika selalu dibuat dalam langganan Azure dan grup sumber daya yang sama dengan kluster utama (baca-tulis).

   

5. Di bagian Enkripsi data , pilih kunci yang dikelola pelanggan untuk mengaktifkan CMK atau Kunci yang dikelola layanan untuk menonaktifkan CMK pada kluster replika.

   

6. Di bagian Identitas terkelola yang ditetapkan pengguna pilih Ubah identitas.

   

7. Dalam daftar identitas terkelola yang ditetapkan pengguna, pilih identitas yang Anda inginkan untuk digunakan kluster Anda untuk mengakses kunci enkripsi data yang disimpan di Azure Key Vault.

   

8. Pilih Tambahkan.

9. Di metode Pemilihan kunci, pilih Pilih kunci .

10. Di Kunci, pilih Ubah kunci.

    

11. Di panel Pilih kunci pilih Azure Key Vault di Brankas kunci dan kunci enkripsi di Kunci, dan konfirmasikan pilihan Anda dengan memilih Pilih.

    

12. Konfirmasi identitas terkelola dan kunci enkripsi yang ditetapkan pengguna yang dipilih di halaman Distribusi global dan pilih Simpan untuk mengonfirmasi pilihan Anda dan membuat kluster replika.

    

REST API

Untuk membuat kluster replika dengan CMK diaktifkan di wilayah yang sama, ikuti langkah-langkah ini.

1. Buat file JSON dengan konten berikut. Ganti tempat penampung yang dimulai dengan $ tanda dengan nilai aktual dan simpan file.

   {
           "identity": {
               "type": "UserAssigned",
               "userAssignedIdentities": {
                 "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName": {}
               }
             },
         "location": "$targetRegionName",
             "properties": {
             	"createMode": "GeoReplica",
                   "replicaParameters": {
                     "sourceResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/mongoClusters/$sourceClusterName",
                     "sourceLocation": "sourceRegionName"
                   },
                   "encryption": {
                     "customerManagedKeyEncryption": {
                       "keyEncryptionKeyIdentity": {
                         "identityType": "UserAssignedIdentity",
                         "userAssignedIdentityResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName"
                       },
                       "keyEncryptionKeyUrl": "$encryptionKeyUrl"
                     }
                   }
             }
       }
   

   Nota

   keyEncryptionKeyUrl harus berisi nama kunci tetapi tidak boleh berisi versi kunci tertentu.

2. Jalankan perintah Azure CLI berikut untuk melakukan panggilan REST API untuk membuat kluster Azure DocumentDB. Ganti tempat penampung di bagian variabel dan nama file untuk --body parameter di az rest baris perintah dengan nilai aktual.

   # Define your variables
   $subscriptionId="00000000-0000-0000-0000-000000000000"
   $resourceGroup="resourceGroupName"
   $mongoClustersName="clusterName"
   
   # Execute the az rest command to make REST API call
   az rest --method "PUT" --url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/mongoClusters/${mongoClustersName}?api-version=2025-09-01 --body  @jsonFileFromThePreviousStep.json
   

Mengaktifkan atau menonaktifkan enkripsi data kunci yang dikelola pelanggan (CMK) selama pemulihan kluster

Proses pemulihan membuat kluster baru dengan konfigurasi yang sama di wilayah, langganan, dan grup sumber daya Azure yang sama dengan yang aslinya. Ikuti langkah-langkah ini untuk membuat kluster yang dipulihkan dengan CMK atau SMK diaktifkan.

Portal

1. Pilih kluster Azure DocumentDB yang sudah ada.

2. Pada bilah sisi kluster, di bawah Pengaturan, pilih Pemulihan Titik Waktu.

3. Pilih tanggal dan berikan waktu (di zona waktu UTC) di bidang tanggal dan waktu.

   

4. Masukkan nama kluster di bidang Pulihkan nama kluster target .

   

5. Masukkan nama admin kluster untuk kluster yang dipulihkan di bidang Nama pengguna admin .

6. Masukkan kata sandi untuk peran admin di bidang Kata Sandi dan Konfirmasi kata sandi .

   

7. Di bagian Enkripsi data, pilih kunci yang dikelola pelanggan untuk mengaktifkan CMK. Jika Anda harus menonaktifkan CMK pada kluster yang dipulihkan, pilih Kunci yang dikelola layanan.

   

8. Di bagian Identitas terkelola yang ditetapkan pengguna pilih Ubah identitas.

   

9. Dalam daftar identitas terkelola yang ditetapkan pengguna, pilih identitas yang Anda inginkan untuk digunakan kluster Anda untuk mengakses kunci enkripsi data yang disimpan di Azure Key Vault.

   

10. Pilih Tambahkan.

11. Di metode Pemilihan kunci, pilih Pilih kunci .

12. Di Kunci, pilih Ubah kunci.

    

13. Di panel Pilih kunci pilih Azure Key Vault di Brankas kunci dan kunci enkripsi di Kunci, dan konfirmasikan pilihan Anda dengan memilih Pilih.

    

14. Pilih Kirim untuk memulai pemulihan kluster.

REST API

Untuk memulihkan kluster dengan CMK diaktifkan, ikuti langkah-langkah ini.

1. Buat file JSON dengan konten berikut. Ganti tempat penampung yang dimulai dengan $ tanda dengan nilai aktual dan simpan file.

   {
       "identity": {
           "type": "UserAssigned",
           "userAssignedIdentities": {
             "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName": {}
           }
         },
     "location": "$regionName",
         "properties": {
               "administrator": {
                 "userName": "$adminName"
               },
         	"createMode": "PointInTimeRestore",
               "restoreParameters": {
                 "pointInTimeUTC": "yyyy-mm-ddThh:mm:ssZ",
                 "sourceResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/mongoClusters/$restoredClusterName"
               },
               "encryption": {
                 "customerManagedKeyEncryption": {
                   "keyEncryptionKeyIdentity": {
                     "identityType": "UserAssignedIdentity",
                     "userAssignedIdentityResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName"
                   },
                   "keyEncryptionKeyUrl": "$encryptionKeyUrl"
                 }
               }
         }
   }
   

   Nota

   keyEncryptionKeyUrl harus berisi nama kunci tetapi tidak boleh berisi versi kunci tertentu.

2. Jalankan perintah Azure CLI berikut untuk melakukan panggilan REST API untuk membuat kluster Azure DocumentDB. Ganti tempat penampung di bagian variabel dan nama file untuk --body parameter di az rest baris perintah dengan nilai aktual.

   # Define your variables
   $subscriptionId="00000000-0000-0000-0000-000000000000"
   $resourceGroup="resourceGroupName"
   $mongoClustersName="clusterName"
   
   # Execute the az rest command to make REST API call
   az rest --method "PUT" --url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/mongoClusters/${mongoClustersName}?api-version=2025-09-01 --body  @jsonFileFromThePreviousStep.json
   

Setelah kluster yang dipulihkan dibuat, tinjau daftar tugas pasca-pemulihan.

Konten terkait

• Pelajari tentang enkripsi data tidak aktif di Azure DocumentDB
• Memecahkan masalah penyiapan CMK
• Lihat batasan CMK
• Memigrasikan data ke Azure DocumentDB