Ekstensi komputer virtual Azure Key Vault untuk Windows
Ekstensi komputer virtual (VM) Azure Key Vault menyediakan refresh otomatis sertifikat yang disimpan di brankas kunci Azure. Ekstensi memantau daftar sertifikat yang diamati yang disimpan dalam brankas kunci. Saat mendeteksi perubahan, ekstensi mengambil dan menginstal sertifikat yang sesuai. Artikel ini menjelaskan platform, konfigurasi, dan opsi penyebaran yang didukung untuk ekstensi VM Key Vault untuk Windows.
Sistem operasi
Ekstensi VM Key Vault mendukung versi Windows berikut:
- Windows Server 2022
- Server Windows 2019
- Server Windows 2016
- Windows Server 2012
Ekstensi VM Key Vault juga didukung pada VM lokal kustom. VM harus diunggah dan dikonversi menjadi gambar khusus untuk digunakan di Azure dengan menggunakan penginstalan inti Windows Server 2019.
Sertifikat yang didukung
Ekstensi VM Key Vault mendukung jenis konten sertifikat berikut:
- PKCS #12
- PEM
Catatan
Ekstensi VM Key Vault mengunduh semua sertifikat ke penyimpanan sertifikat Windows atau ke lokasi yang ditentukan dalam certificateStoreLocation
properti di pengaturan ekstensi VM.
Pembaruan di Versi 3.0+
Ekstensi VM Key Vault versi 3.0 untuk Windows menambahkan dukungan untuk fitur-fitur berikut:
- Menambahkan izin ACL ke sertifikat yang diunduh
- Mengaktifkan konfigurasi Penyimpanan Sertifikat per sertifikat
- Mengekspor kunci privat
- Dukungan IIS Certificate Rebind
Prasyarat
Tinjau prasyarat berikut untuk menggunakan ekstensi VM Key Vault untuk Windows:
Instans Azure Key Vault dengan sertifikat. Untuk informasi selengkapnya, lihat Membuat brankas kunci dengan menggunakan portal Azure.
VM dengan identitas terkelola yang ditetapkan.
Peran Pengguna Rahasia Key Vault harus ditetapkan pada tingkat cakupan Key Vault untuk VM dan identitas terkelola Azure Virtual Machine Scale Sets. Peran ini mengambil bagian rahasia dari sertifikat. Untuk informasi lebih lanjut, baca artikel berikut:
Virtual Machine Scale Sets harus memiliki konfigurasi berikut
identity
:"identity": { "type": "UserAssigned", "userAssignedIdentities": { "[parameters('userAssignedIdentityResourceId')]": {} } }
Ekstensi VM Key Vault harus memiliki konfigurasi berikut
authenticationSettings
:"authenticationSettings": { "msiEndpoint": "[parameters('userAssignedIdentityEndpoint')]", "msiClientId": "[reference(parameters('userAssignedIdentityResourceId'), variables('msiApiVersion')).clientId]" }
Catatan
Model izin kebijakan akses lama juga dapat digunakan untuk menyediakan akses ke VM dan Virtual Machine Scale Sets. Metode ini memerlukan kebijakan dengan izin dapatkan dan daftar pada rahasia. Untuk informasi selengkapnya, lihat Menetapkan kebijakan akses Key Vault.
Skema ekstensi
JSON berikut menunjukkan skema untuk ekstensi Key Vault VM. Sebelum Anda mempertimbangkan opsi implementasi skema, tinjau catatan penting berikut.
Ekstensi tidak memerlukan pengaturan yang dilindungi. Semua pengaturan dianggap sebagai informasi publik.
URL sertifikat yang diamati harus dalam bentuk
https://myVaultName.vault.azure.net/secrets/myCertName
.Formulir ini lebih disukai karena
/secrets
jalur mengembalikan sertifikat lengkap, termasuk kunci privat, tetapi/certificates
jalurnya tidak. Untuk informasi selengkapnya tentang sertifikat, lihat Gambaran umum kunci, rahasia, dan sertifikat Azure Key Vault.Properti
authenticationSettings
diperlukan untuk VM dengan identitas yang ditetapkan pengguna.Properti ini menentukan identitas yang akan digunakan untuk autentikasi ke Key Vault. Tentukan properti ini dengan identitas yang ditetapkan sistem untuk menghindari masalah dengan ekstensi VM dengan beberapa identitas.
{
"type": "Microsoft.Compute/virtualMachines/extensions",
"name": "KVVMExtensionForWindows",
"apiVersion": "2022-08-01",
"location": "<location>",
"dependsOn": [
"[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
],
"properties": {
"publisher": "Microsoft.Azure.KeyVault",
"type": "KeyVaultForWindows",
"typeHandlerVersion": "3.0",
"autoUpgradeMinorVersion": true,
"settings": {
"secretsManagementSettings": {
"pollingIntervalInS": <A string that specifies the polling interval in seconds. Example: "3600">,
"linkOnRenewal": <Windows only. Ensures s-channel binding when the certificate renews without necessitating redeployment. Example: true>,
"requireInitialSync": <Initial synchronization of certificates. Example: true>,
"observedCertificates": <An array of KeyVault URIs that represent monitored certificates, including certificate store location and ACL permission to certificate private key. Example:
[
{
"url": <A Key Vault URI to the secret portion of the certificate. Example: "https://myvault.vault.azure.net/secrets/mycertificate1">,
"certificateStoreName": <The certificate store name. Example: "MY">,
"certificateStoreLocation": <The certificate store location, which currently works locally only. Example: "LocalMachine">,
"accounts": <Optional. An array of preferred accounts with read access to certificate private keys. Administrators and SYSTEM get Full Control by default. Example: ["Network Service", "Local Service"]>
},
{
"url": <Example: "https://myvault.vault.azure.net/secrets/mycertificate2">,
"certificateStoreName": <Example: "MY">,
"certificateStoreLocation": <Example: "CurrentUser">,
"keyExportable": <Optional. Lets the private key be exportable. Example: "false">,
"accounts": <Example: ["Local Service"]>
}
]>
},
"authenticationSettings": {
"msiEndpoint": <Required when the msiClientId property is used. Specifies the MSI endpoint. Example for most Azure VMs: "http://169.254.169.254/metadata/identity/oauth2/token">,
"msiClientId": <Required when the VM has any user assigned identities. Specifies the MSI identity. Example: "c7373ae5-91c2-4165-8ab6-7381d6e75619">
}
}
}
}
Nilai properti
Skema JSON mencakup properti berikut.
Nama | Nilai/Contoh | Jenis Data |
---|---|---|
apiVersion |
01-08-2022 | date |
publisher |
Microsoft.Azure.KeyVault | string |
type |
KeyVaultForWindows | string |
typeHandlerVersion |
"3.0" | string |
pollingIntervalInS |
"3600" | string |
linkOnRenewal (opsional) |
benar | Boolean |
requireInitialSync (opsional) |
salah | Boolean |
observedCertificates |
[{...}, {...}] | array string |
observedCertificates/url |
"https://myvault.vault.azure.net/secrets/mycertificate" | string |
observedCertificates/certificateStoreName |
MY | string |
observedCertificates/certificateStoreLocation |
LocalMachine atau CurrentUser (peka huruf besar/kecil) | string |
observedCertificates/keyExportable (opsional) |
salah | Boolean |
observedCertificates/accounts (opsional) |
["Layanan Jaringan", "Layanan Lokal"] | array string |
msiEndpoint |
"http://169.254.169.254/metadata/identity/oauth2/token" | string |
msiClientId |
c7373ae5-91c2-4165-8ab6-7381d6e75619 | string |
Penyebaran templat
Ekstensi Azure VM dapat disebarkan dengan templat Azure Resource Manager (ARM). Templat sangat ideal saat menyebarkan satu atau beberapa komputer virtual yang memerlukan refresh pascapenyebaran sertifikat. Ekstensi dapat disebarkan ke masing-masing VM atau instans Virtual Machine Scale Sets. Skema dan konfigurasi umum untuk kedua jenis templat.
Konfigurasi JSON untuk ekstensi brankas kunci disarangkan di dalam templat VM atau Virtual Machine Scale Sets. Untuk ekstensi sumber daya VM, konfigurasi disarangkan di "resources": []
bawah objek komputer virtual. Untuk ekstensi instans Virtual Machine Scale Sets, konfigurasi disarangkan di "virtualMachineProfile":"extensionProfile":{"extensions" :[]
bawah objek .
Cuplikan JSON berikut menyediakan pengaturan contoh untuk penyebaran templat ARM ekstensi VM Key Vault.
{
"type": "Microsoft.Compute/virtualMachines/extensions",
"name": "KeyVaultForWindows",
"apiVersion": "2022-08-01",
"location": "<location>",
"dependsOn": [
"[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
],
"properties": {
"publisher": "Microsoft.Azure.KeyVault",
"type": "KeyVaultForWindows",
"typeHandlerVersion": "3.0",
"autoUpgradeMinorVersion": true,
"settings": {
"secretsManagementSettings": {
"pollingIntervalInS": <A string that specifies the polling interval in seconds. Example: "3600">,
"linkOnRenewal": <Windows only. Ensures s-channel binding when the certificate renews without necessitating redeployment. Example: true>,
"observedCertificates": <An array of KeyVault URIs that represent monitored certificates, including certificate store location and ACL permission to certificate private key. Example:
[
{
"url": <A Key Vault URI to the secret portion of the certificate. Example: "https://myvault.vault.azure.net/secrets/mycertificate1">,
"certificateStoreName": <The certificate store name. Example: "MY">,
"certificateStoreLocation": <The certificate store location, which currently works locally only. Example: "LocalMachine">,
"accounts": <Optional. An array of preferred accounts with read access to certificate private keys. Administrators and SYSTEM get Full Control by default. Example: ["Network Service", "Local Service"]>
},
{
"url": <Example: "https://myvault.vault.azure.net/secrets/mycertificate2">,
"certificateStoreName": <Example: "MY">,
"certificateStoreLocation": <Example: "CurrentUser">,
"keyExportable": <Optional. Lets the private key be exportable. Example: "false">,
"accounts": <Example: ["Local Service"]>
},
{
"url": <Example: "https://myvault.vault.azure.net/secrets/mycertificate3">,
"certificateStoreName": <Example: "TrustedPeople">,
"certificateStoreLocation": <Example: "LocalMachine">
}
]>
},
"authenticationSettings": {
"msiEndpoint": <Required when the msiClientId property is used. Specifies the MSI endpoint. Example for most Azure VMs: "http://169.254.169.254/metadata/identity/oauth2/token">,
"msiClientId": <Required when the VM has any user assigned identities. Specifies the MSI identity. Example: "c7373ae5-91c2-4165-8ab6-7381d6e75619">
}
}
}
}
Pengurutan dependensi ekstensi
Anda dapat mengaktifkan ekstensi VM Key Vault untuk mendukung pemesanan dependensi ekstensi. Secara default, ekstensi VM Key Vault melaporkan keberhasilan mulai segera setelah polling dimulai. Namun, Anda dapat mengonfigurasi ekstensi untuk melaporkan keberhasilan mulai hanya setelah ekstensi mengunduh dan menginstal semua sertifikat.
Jika Anda menggunakan ekstensi lain yang memerlukan penginstalan semua sertifikat sebelum dimulai, Anda dapat mengaktifkan urutan dependensi ekstensi di ekstensi VM Key Vault. Fitur ini memungkinkan ekstensi lain untuk mendeklarasikan dependensi pada ekstensi VM Key Vault.
Anda dapat menggunakan fitur ini untuk mencegah ekstensi lain dimulai hingga semua sertifikat dependen diinstal. Ketika fitur diaktifkan, ekstensi VM Key Vault mencoba kembali mengunduh dan menginstal sertifikat tanpa batas waktu dan tetap dalam status Transisi , hingga semua sertifikat berhasil diinstal. Setelah semua sertifikat ada, ekstensi VM Key Vault melaporkan awal yang berhasil.
Untuk mengaktifkan fitur pengurutan dependensi ekstensi di ekstensi VM Key Vault, atur secretsManagementSettings
properti :
"secretsManagementSettings": {
"requireInitialSync": true,
...
}
Untuk informasi selengkapnya tentang cara menyiapkan dependensi antar ekstensi, lihat Provisi ekstensi urutan di Virtual Machine Scale Sets.
Penting
Fitur pemesanan dependensi ekstensi tidak kompatibel dengan templat ARM yang membuat identitas yang ditetapkan sistem dan memperbarui kebijakan akses Key Vault dengan identitas tersebut. Jika Anda mencoba menggunakan fitur dalam skenario ini, kebuntuan terjadi karena kebijakan akses Key Vault tidak dapat diperbarui sampai setelah semua ekstensi dimulai. Sebagai gantinya, gunakan identitas MSI yang ditetapkan pengguna tunggal dan pra-ACL brankas kunci Anda dengan identitas tersebut sebelum Anda menyebarkan.
Penyebaran Azure PowerShell
Ekstensi VM Azure Key Vault dapat disebarkan dengan Azure PowerShell. Simpan pengaturan ekstensi VM Key Vault ke file JSON (settings.json).
Cuplikan JSON berikut menyediakan pengaturan contoh untuk menyebarkan ekstensi VM Key Vault dengan PowerShell.
{
"secretsManagementSettings": {
"pollingIntervalInS": "3600",
"linkOnRenewal": true,
"observedCertificates":
[
{
"url": "https://<examplekv>.vault.azure.net/secrets/certificate1",
"certificateStoreName": "MY",
"certificateStoreLocation": "LocalMachine",
"accounts": [
"Network Service"
]
},
{
"url": "https://<examplekv>.vault.azure.net/secrets/certificate2",
"certificateStoreName": "MY",
"certificateStoreLocation": "LocalMachine",
"keyExportable": true,
"accounts": [
"Network Service",
"Local Service"
]
}
]},
"authenticationSettings": {
"msiEndpoint": "http://169.254.169.254/metadata/identity/oauth2/token",
"msiClientId": "c7373ae5-91c2-4165-8ab6-7381d6e75619"
}
}
Menyebarkan pada VM
# Build settings
$settings = (get-content -raw ".\settings.json")
$extName = "KeyVaultForWindows"
$extPublisher = "Microsoft.Azure.KeyVault"
$extType = "KeyVaultForWindows"
# Start the deployment
Set-AzVmExtension -TypeHandlerVersion "3.0" -ResourceGroupName <ResourceGroupName> -Location <Location> -VMName <VMName> -Name $extName -Publisher $extPublisher -Type $extType -SettingString $settings
Menyebarkan pada instans Virtual Machine Scale Sets
# Build settings
$settings = ".\settings.json"
$extName = "KeyVaultForWindows"
$extPublisher = "Microsoft.Azure.KeyVault"
$extType = "KeyVaultForWindows"
# Add extension to Virtual Machine Scale Sets
$vmss = Get-AzVmss -ResourceGroupName <ResourceGroupName> -VMScaleSetName <VmssName>
Add-AzVmssExtension -VirtualMachineScaleSet $vmss -Name $extName -Publisher $extPublisher -Type $extType -TypeHandlerVersion "3.0" -Setting $settings
# Start the deployment
Update-AzVmss -ResourceGroupName <ResourceGroupName> -VMScaleSetName <VmssName> -VirtualMachineScaleSet $vmss
Penyebaran Azure CLI
Ekstensi VM Azure Key Vault dapat disebarkan dengan menggunakan Azure CLI. Simpan pengaturan ekstensi VM Key Vault ke file JSON (settings.json).
Cuplikan JSON berikut menyediakan pengaturan contoh untuk menyebarkan ekstensi VM Key Vault dengan Azure CLI.
{
"secretsManagementSettings": {
"pollingIntervalInS": "3600",
"linkOnRenewal": true,
"observedCertificates": [
{
"url": "https://<examplekv>.vault.azure.net/secrets/certificate1",
"certificateStoreName": "MY",
"certificateStoreLocation": "LocalMachine",
"accounts": [
"Network Service"
]
},
{
"url": "https://<examplekv>.vault.azure.net/secrets/certificate2",
"certificateStoreName": "MY",
"certificateStoreLocation": "LocalMachine",
"keyExportable": true,
"accounts": [
"Network Service",
"Local Service"
]
}
]
},
"authenticationSettings": {
"msiEndpoint": "http://169.254.169.254/metadata/identity/oauth2/token",
"msiClientId": "c7373ae5-91c2-4165-8ab6-7381d6e75619"
}
}
Menyebarkan pada VM
# Start the deployment
az vm extension set --name "KeyVaultForWindows" `
--publisher Microsoft.Azure.KeyVault `
--resource-group "<resourcegroup>" `
--vm-name "<vmName>" `
--settings "@settings.json"
Menyebarkan pada instans Virtual Machine Scale Sets
# Start the deployment
az vmss extension set --name "KeyVaultForWindows" `
--publisher Microsoft.Azure.KeyVault `
--resource-group "<resourcegroup>" `
--vmss-name "<vmssName>" `
--settings "@settings.json"
Pemecahan masalah
Berikut adalah beberapa saran tentang cara memecahkan masalah penyebaran.
Periksa tanya jawab umum
Apakah ada batasan jumlah sertifikat yang diamati?
Tidak. Ekstensi VM Key Vault tidak membatasi jumlah sertifikat yang diamati (observedCertificates
).
Apa izin default ketika tidak ada akun yang ditentukan?
Secara default, Administrator dan SISTEM menerima Kontrol Penuh.
Bagaimana Anda menentukan apakah kunci sertifikat adalah CAPI1 atau CNG?
Ekstensi ini bergantung pada perilaku default PFXImportCertStore API. Secara default, jika sertifikat memiliki atribut Nama Penyedia yang cocok dengan CAPI1, maka sertifikat diimpor dengan menggunakan API CAPI1. Jika tidak, sertifikat diimpor dengan menggunakan API CNG.
Apakah ekstensi mendukung pengikatan ulang otomatis sertifikat?
Ya, ekstensi VM Azure Key Vault mendukung pengikatan ulang otomatis sertifikat. Ekstensi VM Key Vault mendukung pengikatan saluran S pada perpanjangan sertifikat saat linkOnRenewal
properti diatur ke true.
Untuk IIS, Anda dapat mengonfigurasi pengikatan ulang otomatis dengan mengaktifkan pengikatan ulang otomatis perpanjangan sertifikat di IIS. Ekstensi VM Azure Key Vault menghasilkan Pemberitahuan Siklus Hidup Sertifikat saat sertifikat dengan SAN yang cocok diinstal. IIS menggunakan kejadian ini untuk mengikat ulang sertifikat secara otomatis. Untuk informasi selengkapnya, lihat Mensertifikasi Pengikatan Ulang di IIS
Menampilkan status ekstensi
Periksa status penyebaran ekstensi Anda di portal Azure, atau dengan menggunakan PowerShell atau Azure CLI.
Untuk melihat status penyebaran ekstensi untuk VM tertentu, jalankan perintah berikut.
Azure PowerShell:
Get-AzVMExtension -ResourceGroupName <myResourceGroup> -VMName <myVM> -Name <myExtensionName>
Azure CLI:
az vm get-instance-view --resource-group <myResourceGroup> --name <myVM> --query "instanceView.extensions"
Meninjau log dan konfigurasi
Log ekstensi VM Key Vault hanya ada secara lokal di VM. Tinjau detail log untuk membantu pemecahan masalah.
File log | Deskripsi |
---|---|
C:\WindowsAzure\Logs\WaAppAgent.log' | Memperlihatkan kapan pembaruan terjadi pada ekstensi. |
C:\WindowsAzure\Logs\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<versi terbaru>\ | Memperlihatkan status pengunduhan sertifikat. Lokasi unduhan selalu merupakan 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 VM Key Vault. |
Dapatkan dukungan
Berikut adalah beberapa opsi lain untuk membantu Anda mengatasi masalah penyebaran:
Untuk bantuan, hubungi pakar Azure di forum Tanya Jawab umum dan Stack Overflow.
Jika Anda tidak menemukan jawaban di situs, Anda dapat memposting pertanyaan untuk input dari Microsoft atau anggota komunitas lainnya.
Anda juga dapat Menghubungi Dukungan Microsoft. Untuk informasi mengenai penggunaan dukungan Azure, baca Tanya Jawab Umum dukungan Azure.