Mengonfigurasi kunci yang dikelola pelanggan untuk akun Azure Cosmos Anda dengan Azure Key Vault

BERLAKU UNTUK: SQL API Cassandra API Gremlin API Table API Azure Cosmos DB API for MongoDB

Data yang disimpan di akun Azure Cosmos Anda dienkripsi secara otomatis dan tanpa masalah dengan kunci yang dikelola oleh Microsoft (kunci yang dikelola layanan). Secara opsional, Anda dapat memilih untuk menambahkan lapisan kedua pada enkripsi dengan kunci yang Anda kelola (kunci yang dikelola pelanggan atau CMK).

Layers of encryption around customer data

Anda harus menyimpan kunci yang dikelola pelanggan di Azure Key Vault dan menyediakan kunci untuk setiap akun Azure Cosmos yang diaktifkan dengan kunci yang dikelola pelanggan. Kunci ini digunakan untuk mengenkripsi semua data yang tersimpan di akun tersebut.

Catatan

Saat ini, kunci yang dikelola pelanggan hanya tersedia untuk akun Azure Cosmos baru. Anda harus mengonfigurasinya selama pembuatan akun.

Mendaftarkan penyedia sumber daya Azure Cosmos DB untuk langganan Azure Anda

  1. Masuk ke portal Microsoft Azure, masuk ke langganan Azure Anda, dan pilih Penyedia sumber daya pada tab Pengaturan:

    Resource providers entry from the left menu

  2. Cari penyedia sumber daya Microsoft.DocumentDB. Pastikan bahwa penyedia sumber daya sudah ditandai sebagai terdaftar. Jika tidak, pilih penyedia sumber daya dan pilih Daftar:

    Registering the Microsoft.DocumentDB resource provider

Mengonfigurasi instans Azure Key Vault Anda

Penting

Instans Azure Key Vault Anda harus dapat diakses melalui akses jaringan publik atau mengizinkan layanan Microsoft tepercaya untuk melewati firewallnya. Instans yang dapat diakses secara eksklusif melalui titik akhir privat tidak dapat digunakan untuk menghosting kunci yang dikelola pelanggan.

Menggunakan kunci yang dikelola pelanggan dengan Azure Cosmos DB mengharuskan Anda untuk mengatur dua properti pada instans Azure Key Vault yang anda rencanakan untuk digunakan guna menghosting kunci enkripsi Anda: Penghapusan Sementara dan Perlindungan Penghapusan Menyeluruh.

Jika Anda membuat instans Azure Key Vault baru, aktifkan properti ini selama pembuatan:

Enabling soft delete and purge protection for a new Azure Key Vault instance

Jika Anda menggunakan instans Azure Key Vault yang sudah ada, Anda dapat memverifikasi bahwa properti ini diaktifkan dengan melihat bagian Properti di portal Microsoft Azure. Jika salah satu properti ini tidak diaktifkan, lihat bagian "Mengaktifkan penghapusan sementara" dan "Mengaktifkan Perlindungan Pembersihan Menyeluruh" di salah satu artikel berikut ini:

Menambahkan kebijakan akses ke instans Azure Key Vault Anda

  1. Dari portal Microsoft Azure, buka instans Azure Key Vault yang Anda rencanakan untuk digunakan guna menghosting kunci enkripsi Anda. Pilih Kebijakan Akses dari menu sebelah kiri:

    Access policies from the left menu

  2. Pilih + Tambahkan Kebijakan Akses.

  3. Pada drop-down Izin kunci, pilih izin Dapatkan, Buka Bungkus Kunci, dan Bungkus izin:

    Selecting the right permissions

  4. Pada Pilih prinsipal, pilih Tidak ada yang dipilih.

  5. Cari prinsipal Azure Cosmos DB dan pilih (untuk memudahkan ditemukan, Anda juga dapat mencari berdasarkan ID aplikasi: a232010e-820c-4083-83bb-3ace5fc29d0b untuk wilayah Azure mana pun kecuali wilayah Azure Government tempat ID aplikasi berada 57506a73-e302-42a9-b869-6f12d9ec29e9). Jika prinsipal Azure Cosmos DB tidak ada dalam daftar, Anda mungkin perlu mendaftarkan ulang penyedia sumber daya Microsoft.DocumentDB seperti yang dijelaskan di bagian Daftarkan penyedia sumber daya di artikel ini.

    Catatan

    Ini mendaftarkan identitas pihak pertama Azure Cosmos DB dalam kebijakan akses Azure Key Vault Anda. Untuk mengganti identitas pihak pertama ini dengan identitas terkelola akun Azure Cosmos DB Anda, lihat Menggunakan identitas terkelola dalam kebijakan akses Azure Key Vault.

  6. Pilih opsi Pilih di bagian bawah.

    Select the Azure Cosmos DB principal

  7. Pilih Tambahkan untuk menambahkan kebijakan akses baru.

  8. Pilih Simpan pada instans Key Vault untuk menyimpan semua perubahan.

Membuat kunci di Azure Key Vault

  1. Dari portal Microsoft Azure, buka instans Azure Key Vault yang Anda rencanakan untuk digunakan guna menghosting kunci enkripsi Anda. Lalu, pilih Kunci dari menu sebelah kiri:

    Keys entry from the left menu

  2. Pilih Hasilkan/Impor, berikan nama untuk kunci baru, dan pilih ukuran kunci RSA. Minimal 3072 direkomendasikan untuk keamanan terbaik. Kemudian pilih Buat:

    Create a new key

  3. Setelah kunci dibuat, pilih kunci yang baru dibuat lalu versi saat ini.

  4. Salin Pengidentifikasi Kunci dari kunci tersebut, kecuali bagian setelah garis miring terakhir:

    Copying the key's key identifier

Membuat akun Azure Cosmos baru

Menggunakan Portal Microsoft Azure

Saat Anda membuat akun Azure Cosmos DB baru dari portal Microsoft Azure, pilih Kunci yang dikelola pelanggan di langkah Enkripsi. Di bidang URI Kunci, tempelkan pengidentifikasi URI/dari kunci Azure Key Vault yang Anda salin dari langkah sebelumnya:

Setting CMK parameters in the Azure portal

Menggunakan Azure PowerShell

Saat Anda membuat akun Azure Cosmos DB baru dengan PowerShell:

  • Berikan URI kunci Azure Key Vault yang disalin sebelumnya pada properti keyVaultKeyUri di PropertyObject.

  • Gunakan 2019-12-12 atau yang lebih baru sebagai versi API.

Penting

Anda harus mengatur properti locations secara eksplisit agar akun berhasil dibuat dengan kunci yang dikelola pelanggan.

$resourceGroupName = "myResourceGroup"
$accountLocation = "West US 2"
$accountName = "mycosmosaccount"

$failoverLocations = @(
    @{ "locationName"="West US 2"; "failoverPriority"=0 }
)

$CosmosDBProperties = @{
    "databaseAccountOfferType"="Standard";
    "locations"=$failoverLocations;
    "keyVaultKeyUri" = "https://<my-vault>.vault.azure.net/keys/<my-key>";
}

New-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2019-12-12" -ResourceGroupName $resourceGroupName `
    -Location $accountLocation -Name $accountName -PropertyObject $CosmosDBProperties

Setelah akun dibuat, Anda dapat memverifikasi bahwa kunci yang dikelola pelanggan telah diaktifkan dengan mengambil URI kunci Azure Key Vault:

Get-AzResource -ResourceGroupName $resourceGroupName -Name $accountName `
    -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    | Select-Object -ExpandProperty Properties `
    | Select-Object -ExpandProperty keyVaultKeyUri

Menggunakan Templat Azure Resource Manager

Saat Anda membuat akun Azure Cosmos baru melalui templat Azure Resource Manager:

  • Berikan URI kunci Azure Key Vault yang Anda salin sebelumnya pada properti keyVaultKeyUri di objek properti.

  • Gunakan 2019-12-12 atau yang lebih baru sebagai versi API.

Penting

Anda harus mengatur properti locations secara eksplisit agar akun berhasil dibuat dengan kunci yang dikelola pelanggan.

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "accountName": {
            "type": "string"
        },
        "location": {
            "type": "string"
        },
        "keyVaultKeyUri": {
            "type": "string"
        }
    },
    "resources": 
    [
        {
            "type": "Microsoft.DocumentDB/databaseAccounts",
            "name": "[parameters('accountName')]",
            "apiVersion": "2019-12-12",
            "kind": "GlobalDocumentDB",
            "location": "[parameters('location')]",
            "properties": {
                "locations": [ 
                    {
                        "locationName": "[parameters('location')]",
                        "failoverPriority": 0,
                        "isZoneRedundant": false
                    }
                ],
                "databaseAccountOfferType": "Standard",
                "keyVaultKeyUri": "[parameters('keyVaultKeyUri')]"
            }
        }
    ]
}

Menyebarkan templat dengan skrip PowerShell berikut:

$resourceGroupName = "myResourceGroup"
$accountName = "mycosmosaccount"
$accountLocation = "West US 2"
$keyVaultKeyUri = "https://<my-vault>.vault.azure.net/keys/<my-key>"

New-AzResourceGroupDeployment `
    -ResourceGroupName $resourceGroupName `
    -TemplateFile "deploy.json" `
    -accountName $accountName `
    -location $accountLocation `
    -keyVaultKeyUri $keyVaultKeyUri

Menggunakan Azure CLI

Saat Anda membuat akun Azure Cosmos baru melalui Azure CLI, lewati URI kunci Azure Key Vault yang Anda salin sebelumnya pada parameter --key-uri.

resourceGroupName='myResourceGroup'
accountName='mycosmosaccount'
keyVaultKeyUri = 'https://<my-vault>.vault.azure.net/keys/<my-key>'

az cosmosdb create \
    -n $accountName \
    -g $resourceGroupName \
    --locations regionName='West US 2' failoverPriority=0 isZoneRedundant=False \
    --key-uri $keyVaultKeyUri

Setelah akun dibuat, Anda dapat memverifikasi bahwa kunci yang dikelola pelanggan telah diaktifkan dengan mengambil URI kunci Azure Key Vault:

az cosmosdb show \
    -n $accountName \
    -g $resourceGroupName \
    --query keyVaultKeyUri

Menggunakan identitas terkelola dalam kebijakan akses Azure Key Vault

Kebijakan akses ini memastikan bahwa kunci enkripsi Anda dapat diakses oleh akun Azure Cosmos DB Anda. Ini dilakukan dengan memberikan akses ke identitas Azure Active Directory (AD) tertentu. Dua jenis identitas didukung:

  • Identitas pihak pertama Azure Cosmos DB dapat digunakan untuk memberikan akses ke layanan Azure Cosmos DB.
  • Identitas terkelola akun Azure Cosmos DB Anda dapat digunakan untuk memberikan akses ke akun Anda secara khusus.

Untuk menggunakan identitas terkelola yang ditetapkan sistem

Karena identitas terkelola yang ditetapkan sistem hanya dapat diambil setelah pembuatan akun Anda, Anda masih harus membuat akun Anda terlebih dahulu menggunakan identitas pihak pertama, seperti yang dijelaskan di atas. Kemudian:

  1. Jika ini tidak dilakukan selama pembuatan akun, aktifkan identitas terkelola yang ditetapkan sistem di akun Anda dan salin principalId yang ditetapkan.

  2. Tambahkan kebijakan akses baru ke akun Azure Key Vault Anda, seperti yang dijelaskan di atas, tetapi menggunakan principalId yang sudah Anda salin pada langkah sebelumnya alih-alih identitas pihak pertama Azure Cosmos DB.

  3. Perbarui akun Azure Cosmos DB Anda untuk menentukan bahwa Anda ingin menggunakan identitas terkelola yang ditetapkan sistem saat mengakses kunci enkripsi Anda di Azure Key Vault. Anda bisa melakukan ini:

    • dengan menentukan properti ini di templat Azure Resource Manager akun Anda:
    {
        "type": " Microsoft.DocumentDB/databaseAccounts",
        "properties": {
            "defaultIdentity": "SystemAssignedIdentity",
            // ...
        },
        // ...
    }
    
    • dengan memperbarui akun Anda dengan Azure CLI:
        resourceGroupName='myResourceGroup'
        accountName='mycosmosaccount'
    
        az cosmosdb update --resource-group $resourceGroupName --name $accountName --default-identity "SystemAssignedIdentity"
    
  4. Secara opsional, Anda kemudian dapat menghapus identitas pihak pertama Azure Cosmos DB dari kebijakan akses Azure Key Vault Anda.

Untuk menggunakan identitas terkelola yang ditetapkan pengguna

  1. Saat membuat kebijakan akses baru di akun Azure Key Vault Anda seperti yang dijelaskan di atas, gunakan Object ID identitas terkelola yang ingin Anda gunakan alih-alih identitas pihak pertama Azure Cosmos DB.

  2. Saat membuat akun Azure Cosmos DB, Anda harus mengaktifkan identitas terkelola yang ditetapkan pengguna dan menentukan bahwa Anda ingin menggunakan identitas ini saat mengakses kunci enkripsi Anda di Azure Key Vault. Anda bisa melakukan ini:

    • dalam templat Azure Resource Manager:
    {
        "type": "Microsoft.DocumentDB/databaseAccounts",
        "identity": {
            "type": "UserAssigned",
            "userAssignedIdentities": {
                "<identity-resource-id>": {}
            }
        },
        // ...
        "properties": {
            "defaultIdentity": "UserAssignedIdentity=<identity-resource-id>"
            "keyVaultKeyUri": "<key-vault-key-uri>"
            // ...
        }
    }
    
    • dengan Azure CLI:
    resourceGroupName='myResourceGroup'
    accountName='mycosmosaccount'
    keyVaultKeyUri = 'https://<my-vault>.vault.azure.net/keys/<my-key>'
    
    az cosmosdb create \
        -n $accountName \
        -g $resourceGroupName \
        --key-uri $keyVaultKeyUri
        --assign-identity <identity-resource-id>
        --default-identity "UserAssignedIdentity=<identity-resource-id>"  
    

Gunakan CMK dengan pencadangan berkala

Anda dapat membuat akun cadangan berkala dengan menggunakan Azure CLI atau templat Azure Resource Manager.

Saat ini, hanya identitas terkelola yang ditetapkan pengguna yang didukung untuk membuat akun cadangan berkala.

Untuk membuat akun pencadangan berkala dengan menggunakan Azure CLI

resourceGroupName='myResourceGroup'
accountName='mycosmosaccount'
keyVaultKeyUri = 'https://<my-vault>.vault.azure.net/keys/<my-key>'

az cosmosdb create \
    -n $accountName \
    -g $resourceGroupName \
    --key-uri $keyVaultKeyUri \
    --locations regionName=<Location> \
    --assign-identity <identity-resource-id> \
    --default-identity "UserAssignedIdentity=<identity-resource-id>" \
    --backup-policy-type Continuous 

Untuk membuat akun pencadangan berkala dengan menggunakan templat Azure Resource Manager

Saat Anda membuat akun Azure Cosmos baru melalui templat Azure Resource Manager:

  • Berikan URI kunci Azure Key Vault yang Anda salin sebelumnya pada properti keyVaultKeyUri di objek properti.
  • Gunakan 2021-11-15 atau yang lebih baru sebagai versi API.

Penting

Anda harus mengatur properti locations secara eksplisit agar akun berhasil dibuat dengan kunci yang dikelola pelanggan seperti yang ditunjukkan pada contoh sebelumnya.

 {
    "type": "Microsoft.DocumentDB/databaseAccounts",
    "identity": {
        "type": "UserAssigned",
        "backupPolicy": {"type": "Continuous"},
        "userAssignedIdentities": {
            "<identity-resource-id>": {}
        }
    },
    // ...
    "properties": {
        "defaultIdentity": "UserAssignedIdentity=<identity-resource-id>"
        "keyVaultKeyUri": "<key-vault-key-uri>"
        // ...
    }
}

Kunci yang dikelola pelanggan dan enkripsi ganda

Saat menggunakan kunci yang dikelola pelanggan, data yang Anda simpan di akun Azure Cosmos DB Anda akan dienkripsi dua kali:

  • Setelah melalui enkripsi default dilakukan dengan kunci yang dikelola Microsoft.
  • Setelah melalui enkripsi tambahan dilakukan dengan kunci yang dikelola pelanggan.

Perhatikan bahwa ini hanya berlaku untuk penyimpanan transaksional utama Azure Cosmos DB. Beberapa fitur melibatkan replikasi internal data Anda ke penyimpanan tingkat kedua di mana enkripsi ganda tidak disediakan, bahkan saat menggunakan kunci yang dikelola pelanggan. Fitur ini mencakup:

Rotasi kunci

Merotasi kunci yang dikelola pelanggan yang digunakan oleh akun Azure Cosmos Anda dapat dilakukan dengan dua cara.

  • Buat versi baru kunci yang saat ini digunakan dari Azure Key Vault:

    Create a new key version

  • Tukar kunci yang saat ini digunakan dengan yang sama sekali berbeda dengan memperbarui URI kunci pada akun Anda. Dari portal Microsoft Azure, buka akun Azure Cosmos Anda dan pilih Enkripsi Data dari menu kiri:

    The Data Encryption menu entry

    Kemudian, ganti URI Kunci dengan kunci baru yang ingin Anda gunakan dan pilih Simpan:

    Update the key URI

    Berikut cara mencapai hasil yang sama di PowerShell:

    $resourceGroupName = "myResourceGroup"
    $accountName = "mycosmosaccount"
    $newKeyUri = "https://<my-vault>.vault.azure.net/keys/<my-new-key>"
    
    $account = Get-AzResource -ResourceGroupName $resourceGroupName -Name $accountName `
        -ResourceType "Microsoft.DocumentDb/databaseAccounts"
    
    $account.Properties.keyVaultKeyUri = $newKeyUri
    
    $account | Set-AzResource -Force
    

Kunci atau versi kunci sebelumnya dapat dinonaktifkan setelah log audit Azure Key Vault tidak lagi menampilkan aktivitas dari Azure Cosmos DB pada kunci atau versi kunci tersebut. Tidak ada lagi aktivitas yang akan dilakukan pada versi kunci atau kunci sebelumnya setelah 24 jam rotasi kunci.

Penanganan kesalahan

Saat menggunakan kunci yang dikelola pelanggan (CMK) di Azure Cosmos DB, jika ada kesalahan, Azure Cosmos DB mengembalikan detail kesalahan bersama dengan kode sub-status HTTP dalam respons. Anda dapat menggunakan kode sub-status ini untuk men-debug akar penyebab masalah. Lihat artikel Kode Status HTTP untuk Azure Cosmos DB guna mendapatkan daftar kode sub-status HTTP yang didukung.

Tanya jawab umum

Apakah ada biaya tambahan untuk mengaktifkan kunci yang dikelola pelanggan?

Tidak, tidak ada biaya untuk mengaktifkan fitur ini.

Bagaimana kunci yang dikelola pelanggan memengaruhi perencanaan kapasitas?

Saat menggunakan kunci yang dikelola pelanggan, Unit Permintaan yang digunakan oleh operasi database Anda melihat peningkatan untuk mencerminkan pemrosesan tambahan yang diperlukan untuk melakukan enkripsi dan dekripsi data Anda. Ini dapat menyebabkan pemanfaatan yang sedikit lebih tinggi dari kapasitas yang Anda penyediaan. Gunakan tabel di bawah untuk panduan:

Jenis operasi Peningkatan Unit Permintaan
Point-read (mengambil item berdasarkan ID mereka) + 5% per operasi
Setiap operasi penulisan + 6% per operasi
Sekitar + 0,06 RU per properti yang diindeks
Kueri, umpan perubahan baca, atau umpan konflik + 15% per operasi

Data apa yang dienkripsi dengan kunci yang dikelola pelanggan?

Semua data yang disimpan di akun Azure Cosmos Anda dienkripsi dengan kunci yang dikelola pelanggan, kecuali untuk metadata berikut:

Apakah kunci yang dikelola pelanggan didukung untuk akun Azure Cosmos yang sudah ada?

Fitur ini sekarang hanya tersedia untuk akun baru.

Apakah mungkin untuk menggunakan kunci yang dikelola pelanggan bersama dengan penyimpanan analitik Azure Cosmos DB?

Ya, Azure Synapse Link hanya mendukung konfigurasi kunci yang dikelola pelanggan menggunakan identitas terkelola akun Azure Cosmos DB Anda. Anda harus menggunakan identitas terkelola akun Azure Cosmos DB Anda di kebijakan akses Azure Key Vault sebelum mengaktifkan Azure Synapse Link di akun Anda.

Apakah ada rencana untuk mendukung pemerincian yang lebih halus daripada kunci tingkat akun?

Tidak saat ini, tetapi kunci tingkat kontainer sedang dipertimbangkan.

Bagaimana cara mengetahui apakah kunci yang dikelola pelanggan diaktifkan di akun Azure Cosmos saya?

Dari portal Microsoft Azure, buka akun Azure Cosmos Anda dan perhatikan entri Enkripsi Data di menu kiri; jika entri ini ada, kunci yang dikelola pelanggan diaktifkan di akun Anda:

The Data Encryption menu entry

Anda juga dapat secara terprogram mengambil detail akun Azure Cosmos Anda dan mencari keberadaan properti keyVaultKeyUri. Lihat di atas untuk cara melakukannya di PowerShell dan menggunakan Azure CLI.

Bagaimana kunci yang dikelola pelanggan memengaruhi pencadangan berkala?

Azure Cosmos DB mengambil cadangan data reguler dan otomatis yang disimpan di akun Anda. Operasi ini mencadangkan data terenkripsi.

Kondisi berikut diperlukan untuk berhasil memulihkan cadangan berkala:

  • Kunci enkripsi yang Anda gunakan pada saat pencadangan diperlukan dan harus tersedia di Azure Key Vault. Ini berarti tidak ada pencabutan yang dilakukan dan versi kunci yang digunakan pada saat pencadangan masih diaktifkan.
  • Jika Anda menggunakan identitas terkelola yang ditetapkan sistem dalam kebijakan akses Azure Key Vault akun sumber, Anda harus memberikan akses sementara ke identitas pihak pertama Azure Cosmos DB dalam kebijakan akses tersebut seperti yang dijelaskan di sini sebelum memulihkan data Anda. Ini karena identitas terkelola yang ditetapkan sistem khusus untuk akun dan tidak dapat digunakan kembali di akun target. Setelah data sepenuhnya dipulihkan ke akun target, Anda dapat mengatur konfigurasi identitas yang diinginkan dan menghapus identitas pihak pertama dari kebijakan akses Key Vault.

Bagaimana kunci yang dikelola pelanggan memengaruhi pencadangan berkala?

Azure Cosmos DB memberi Anda opsi untuk mengonfigurasi pencadangan berkala di akun Anda. Dengan cadangan berkala, Anda dapat memulihkan data Anda ke titik waktu apa pun dalam 30 hari terakhir. Untuk menggunakan pencadangan berkala pada akun tempat kunci yang dikelola pelanggan diaktifkan, Anda harus menggunakan identitas terkelola yang ditetapkan pengguna dalam kebijakan akses Key Vault; identitas pihak pertama Azure Cosmos DB atau identitas terkelola yang ditetapkan sistem saat ini tidak didukung pada akun menggunakan pencadangan berkala.

Kondisi berikut diperlukan agar berhasil melakukan pemulihan titik waktu:

  • Kunci enkripsi yang Anda gunakan pada saat pencadangan diperlukan dan harus tersedia di Azure Key Vault. Ini berarti tidak ada pencabutan yang dilakukan dan versi kunci yang digunakan pada saat pencadangan masih diaktifkan.
  • Anda harus memastikan bahwa identitas terkelola yang ditetapkan pengguna yang awalnya digunakan pada akun sumber masih dinyatakan dalam kebijakan akses Key Vault.

Penting

Jika Anda mencabut kunci enkripsi sebelum menghapus akun Anda, cadangan akun Anda mungkin kehilangan data yang ditulis hingga 1 jam sebelum pencabutan dibuat.

Bagaimana cara mencabut kunci enkripsi?

Pencabutan kunci dilakukan dengan menonaktifkan versi terbaru kunci:

Disable a key's version

Atau, untuk mencabut semua kunci dari instans Azure Key Vault, Anda dapat menghapus kebijakan akses yang diberikan kepada prinsipal Azure Cosmos DB:

Deleting the access policy for the Azure Cosmos DB principal

Operasi apa yang tersedia setelah kunci yang dikelola pelanggan dicabut?

Satu-satunya operasi yang dimungkinkan ketika kunci enkripsi telah dicabut adalah penghapusan akun.

Langkah berikutnya