Ekstensi komputer virtual Vault Kunci untuk Windows

Ekstensi komputer virtual Key Vault menyediakan refresh otomatis untuk sertifikat yang disimpan di brankas kunci Azure. Secara khusus, ekstensi memantau daftar sertifikat yang diamati yang disimpan dalam brankas kunci, dan setelah mendeteksi perubahan, mengambil, dan menginstal sertifikat yang sesuai. Dokumen ini merinci opsi platform, konfigurasi, dan penyebaran yang didukung untuk ekstensi VM Vault Kunci untuk Windows.

Sistem operasi

Ekstensi Key Vault VM mendukung Windows versi di bawah ini:

  • Server Windows 2019
  • Server Windows 2016
  • Windows Server 2012

Ekstensi Key Vault VM juga didukung pada VM lokal kustom yang diunggah dan dikonversi menjadi gambar khusus untuk digunakan di Azure menggunakan penginstalan core Windows Server 2019.

Catatan

Ekstensi VM Key Vault mengunduh sertifikat di lokasi default atau ke lokasi yang disediakan oleh properti "certStoreLocation" di pengaturan Ekstensi VM. Saat ini, ekstensi VM KV memberikan akses ke kunci pribadi sertifikat hanya ke akun admin sistem lokal. Selain itu, saat ini tidak mungkin untuk menentukan lokasi penyimpanan sertifikat per sertifikat. Tim ekstensi VM sedang mengerjakan solusi untuk menutup celah fitur ini.

Jenis konten sertifikat yang didukung

  • PKCS #12
  • PEM

Prasyarat

"identity": {
  "type": "UserAssigned",
  "userAssignedIdentities": {
    "[parameters('userAssignedIdentityResourceId')]": {}
  }
}
  • Ekstensi AKV harus memiliki pengaturan ini:
"authenticationSettings": {
  "msiEndpoint": "[parameters('userAssignedIdentityEndpoint')]",
  "msiClientId": "[reference(parameters('userAssignedIdentityResourceId'), variables('msiApiVersion')).clientId]"
}

Skema ekstensi

JSON berikut menunjukkan skema untuk ekstensi Key Vault VM. Ekstensi ini tidak memerlukan pengaturan yang dilindungi - semua pengaturannya dianggap sebagai informasi publik. Ekstensi ini memerlukan daftar sertifikat yang dipantau, frekuensi polling, dan penyimpanan sertifikat tujuan. Khususnya:

    {
      "type": "Microsoft.Compute/virtualMachines/extensions",
      "name": "KVVMExtensionForWindows",
      "apiVersion": "2019-07-01",
      "location": "<location>",
      "dependsOn": [
          "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
      ],
      "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForWindows",
      "typeHandlerVersion": "1.0",
      "autoUpgradeMinorVersion": true,
      "settings": {
        "secretsManagementSettings": {
          "pollingIntervalInS": <string specifying polling interval in seconds, e.g: "3600">,
          "certificateStoreName": <certificate store name, e.g.: "MY">,
          "linkOnRenewal": <Only Windows. This feature ensures s-channel binding when certificate renews, without necessitating a re-deployment.  e.g.: false>,
          "certificateStoreLocation": <certificate store location, currently it works locally only e.g.: "LocalMachine">,
          "requireInitialSync": <initial synchronization of certificates e..g: true>,
          "observedCertificates": <list of KeyVault URIs representing monitored certificates, e.g.: "https://myvault.vault.azure.net/secrets/mycertificate"
        },
        "authenticationSettings": {
          "msiEndpoint":  <Required when msiClientId is provided. MSI endpoint e.g. for most Azure VMs: "http://169.254.169.254/metadata/identity">,
          "msiClientId":  <Required when VM has any user assigned identities. MSI identity e.g.: "c7373ae5-91c2-4165-8ab6-7381d6e75619".>
        }
       }
      }
    }

Catatan

URL sertifikat yang Anda amati harus berupa formulir https://myVaultName.vault.azure.net/secrets/myCertName.

Ini karena jalur /secrets menampilkan sertifikat lengkap, termasuk kunci privat, sementara jalur /certificates tidak. Informasi selengkapnya tentang sertifikat dapat ditemukan di sini: Sertifikat Key Vault

Penting

Properti 'authenticationSettings' diperlukan untuk VM dengan identitas yang ditetapkan pengguna. Bahkan jika Anda ingin menggunakan identitas yang ditetapkan sistem, ini masih diperlukan; jika tidak, ekstensi VM tidak akan tahu identitas mana yang akan digunakan. Tanpa bagian ini, VM dengan identitas yang ditetapkan pengguna akan mengakibatkan ekstensi Key Vault gagal dan tidak dapat mengunduh sertifikat. Properti ini menentukan identitas yang akan digunakan untuk autentikasi ke Key Vault.

Penting

Jika Anda menentukan 'msiClientId', maka properti 'msiEndpoint' diperlukan. Biasanya nilai harus diatur ke http://169.254.169.254/metadata/identity/oauth2/token.

Nilai properti

Nama Nilai / Contoh Jenis Data
apiVersion 2019-07-01 tanggal
penerbit Microsoft.Azure.KeyVault string
jenis KeyVaultForWindows string
typeHandlerVersion 1.0 int
pollingIntervalInS 3600 string
certificateStoreName MY string
linkOnRenewal salah boolean
certificateStoreLocation LocalMachine atau CurrentUser (peka huruf besar/kecil) string
requireInitialSync benar boolean
observedCertificates ["https://myvault.vault.azure.net/secrets/mycertificate", "https://myvault.vault.azure.net/secrets/mycertificate2"] array string
msiEndpoint http://169.254.169.254/metadata/identity string
msiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619 string

Penyebaran templat

Ekstensi Azure VM dapat disebarkan dengan templat Azure Resource Manager. Templat sangat ideal saat menyebarkan satu atau beberapa komputer virtual yang memerlukan refresh pascapenyebaran sertifikat. Ekstensi dapat digunakan ke VM individu atau kumpulan skala komputer virtual. Skema dan konfigurasi umum untuk kedua jenis templat.

Konfigurasi JSON untuk ekstensi komputer virtual harus ditumpuk di dalam fragmen sumber daya komputer virtual templat, khususnya objek "resources": [] untuk templat komputer virtual dan dalam kasus skala komputer virtual yang diatur di bawah objek "virtualMachineProfile":"extensionProfile":{"extensions" :[].

Catatan

Ekstensi VM akan mengharuskan sistem atau identitas yang dikelola pengguna ditetapkan untuk mengautentikasi ke Key Vault. Lihat Cara mengautentikasi ke Key Vault dan menetapkan kebijakan akses Key Vault.

    {
      "type": "Microsoft.Compute/virtualMachines/extensions",
      "name": "KeyVaultForWindows",
      "apiVersion": "2019-07-01",
      "location": "<location>",
      "dependsOn": [
          "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
      ],
      "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForWindows",
      "typeHandlerVersion": "1.0",
      "autoUpgradeMinorVersion": true,
      "settings": {
        "secretsManagementSettings": {
          "pollingIntervalInS": <string specifying polling interval in seconds, e.g: "3600">,
          "certificateStoreName": <certificate store name, e.g.: "MY">,
          "certificateStoreLocation": <certificate store location, currently it works locally only e.g.: "LocalMachine">,
          "observedCertificates": <list of KeyVault URIs representing monitored certificates, e.g.: ["https://myvault.vault.azure.net/secrets/mycertificate", "https://myvault.vault.azure.net/secrets/mycertificate2"]>
        }      
      }
      }
    }

Pemesanan Dependensi Ekstensi

Ekstensi Key Vault VM mendukung pemesanan ekstensi jika dikonfigurasi. Secara default, ekstensi melaporkan bahwa ekstensi telah berhasil dimulai segera setelah mulai melakukan polling. Namun, dapat dikonfigurasi untuk menunggu sampai berhasil mengunduh daftar lengkap sertifikat sebelum melaporkan awal yang sukses. Jika ekstensi lain bergantung pada penginstalan sertifikat lengkap sebelum dimulai, mengaktifkan pengaturan ini akan memungkinkan ekstensi tersebut untuk mendeklarasikan dependensi pada ekstensi Key Vault. Langkah ini akan mencegah ekstensi tersebut dimulai sampai semua sertifikat yang diandalkan telah diinstal. Ekstensi akan mencoba kembali unduhan awal tanpa batas waktu dan tetap dalam status Transitioning.

Untuk mengaktifkannya, atur hal berikut ini:

"secretsManagementSettings": {
    "requireInitialSync": true,
    ...
}

Catatan

Menggunakan fitur ini tidak kompatibel dengan templat ARM yang membuat identitas yang ditetapkan sistem dan memperbarui kebijakan akses Key Vault dengan identitas tersebut. Melakukan tindakan tersebut akan mengakibatkan kebuntuan karena kebijakan akses vault tidak dapat diperbarui sampai semua ekstensi telah dimulai. Sebagai gantinya, gunakan identitas MSI tunggal yang ditetapkan pengguna dan pra-ACL vault Anda dengan identitas tersebut sebelum menyebarkan.

Penyebaran Azure PowerShell

Peringatan

Klien PowerShell sering menambahkan \ ke " dalam settings.json, yang menyebabkan akvvm_service gagal dengan kesalahan [CertificateManagementConfiguration] Failed to parse the configuration settings with:not an object.. Karakter \ dan " akan terlihat di portal, di Ekstensi pada bagian Pengaturan. Untuk menghindari hal ini, inisialisasi $settings sebagai PowerShell HashTable:

$settings = @{
    "secretsManagementSettings" = @{ 
        "pollingIntervalInS"       = "<pollingInterval>"; 
        "certificateStoreName"     = "<certStoreName>"; 
        "certificateStoreLocation" = "<certStoreLoc>"; 
        "observedCertificates"     = @("<observedCert1>", "<observedCert2>") } }

Azure PowerShell dapat digunakan untuk menggunakan ekstensi Key Vault VM ke komputer virtual atau kumpulan skala komputer virtual yang ada.

  • Untuk menyebarkan ekstensi pada VM:

        # Build settings
        $settings = '{"secretsManagementSettings": 
        { "pollingIntervalInS": "' + <pollingInterval> + 
        '", "certificateStoreName": "' + <certStoreName> + 
        '", "certificateStoreLocation": "' + <certStoreLoc> + 
        '", "observedCertificates": ["' + <observedCert1> + '","' + <observedCert2> + '"] } }'
        $extName =  "KeyVaultForWindows"
        $extPublisher = "Microsoft.Azure.KeyVault"
        $extType = "KeyVaultForWindows"
    
    
        # Start the deployment
        Set-AzVmExtension -TypeHandlerVersion "1.0" -ResourceGroupName <ResourceGroupName> -Location <Location> -VMName <VMName> -Name $extName -Publisher $extPublisher -Type $extType -SettingString $settings
    
    
  • Untuk menyebarkan ekstensi pada kumpulan skala komputer virtual:

    
        # Build settings
        $settings = '{"secretsManagementSettings": 
        { "pollingIntervalInS": "' + <pollingInterval> + 
        '", "certificateStoreName": "' + <certStoreName> + 
        '", "certificateStoreLocation": "' + <certStoreLoc> + 
        '", "observedCertificates": ["' + <observedCert1> + '","' + <observedCert2> + '"] } }'
        $extName = "KeyVaultForWindows"
        $extPublisher = "Microsoft.Azure.KeyVault"
        $extType = "KeyVaultForWindows"
    
        # Add Extension to VMSS
        $vmss = Get-AzVmss -ResourceGroupName <ResourceGroupName> -VMScaleSetName <VmssName>
        Add-AzVmssExtension -VirtualMachineScaleSet $vmss  -Name $extName -Publisher $extPublisher -Type $extType -TypeHandlerVersion "1.0" -Setting $settings
    
        # Start the deployment
        Update-AzVmss -ResourceGroupName <ResourceGroupName> -VMScaleSetName <VmssName> -VirtualMachineScaleSet $vmss 
    
    

Penyebaran Azure CLI

Azure CLI dapat digunakan untuk menyebarkan ekstensi Key Vault VM ke komputer virtual atau kumpulan skala komputer virtual yang ada.

  • Untuk menyebarkan ekstensi pada VM:

       # Start the deployment
         az vm extension set --name "KeyVaultForWindows" `
         --publisher Microsoft.Azure.KeyVault `
         --resource-group "<resourcegroup>" `
         --vm-name "<vmName>" `
         --settings '{\"secretsManagementSettings\": { \"pollingIntervalInS\": \"<pollingInterval>\", \"certificateStoreName\": \"<certStoreName>\", \"certificateStoreLocation\": \"<certStoreLoc>\", \"observedCertificates\": [\" <observedCert1> \", \" <observedCert2> \"] }}'
    
  • Untuk menyebarkan ekstensi pada kumpulan skala komputer virtual:

          # Start the deployment
          az vmss extension set --name "KeyVaultForWindows" `
           --publisher Microsoft.Azure.KeyVault `
           --resource-group "<resourcegroup>" `
           --vmss-name "<vmName>" `
           --settings '{\"secretsManagementSettings\": { \"pollingIntervalInS\": \"<pollingInterval>\", \"certificateStoreName\": \"<certStoreName>\", \"certificateStoreLocation\": \"<certStoreLoc>\", \"observedCertificates\": [\" <observedCert1> \", \" <observedCert2> \"] }}'
    

Harap diperhatikan tentang pembatasan/persyaratan berikut:

Pemecahan masalah dan dukungan

Pertanyaan Umum

  • Apakah ada batasan pada jumlah observedCertificates yang dapat Anda siapkan? Tidak, Ekstensi VM Key Vault tidak memiliki batasan pada jumlah observedCertificates.

Pecahkan masalah

Data tentang status penyebaran ekstensi dapat diambil dari portal Microsoft Azure dan menggunakan Azure PowerShell. Untuk melihat status penyebaran ekstensi untuk VM tertentu, jalankan perintah berikut menggunakan Azure PowerShell.

Azure PowerShell

Get-AzVMExtension -VMName <vmName> -ResourceGroupname <resource group name>

Azure CLI

 az vm get-instance-view --resource-group <resource group name> --name  <vmName> --query "instanceView.extensions"

Log dan konfigurasi

Log ekstensi mesin virtual Key Vault hanya ada secara lokal di mesin virtual dan paling informatif dalam hal pemecahan masalah

Lokasi Deskripsi
C:\WindowsAzure\Logs\WaAppAgent.log Memperlihatkan saat pembaruan ke ekstensi terjadi.
C:\WindowsAzure\Logs\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<versi terbaru>\ Memperlihatkan status pengunduhan sertifikat. Lokasi pengunduhan akan selalu menjadi toko MY komputer Windows (certlm.msc).
C:\Packages\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<versi terbaru>\RuntimeSettings\ Log layanan Key Vault VM Extension menunjukkan status layanan akvvm_service.
C:\Packages\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<versi terbaru>\Status\ Konfigurasi dan biner untuk layanan Ekstensi mesin virtual Key Vault.

Dukungan

Jika memerlukan bantuan lebih lanjut pada titik mana pun dalam artikel ini, Anda dapat menghubungi pakar Azure di Forum MSDN Azure dan Stack Overflow. Atau, Anda dapat mengajukan insiden dukungan Azure. Buka situs dukungan Azure dan pilih Dapatkan dukungan. Untuk mengetahui informasi tentang cara menggunakan Dukungan Azure, baca FAQ dukungan Microsoft Azure.