適用於 Windows 的 Azure Key Vault 虛擬機器擴充功能

Azure Key Vault 虛擬機 （VM） 擴充功能提供自動重新整理儲存在 Azure 金鑰保存庫中的憑證。 此擴充功能會監視儲存於金鑰保存庫的觀察憑證清單。 當它偵測到變更時，擴充功能會擷取並安裝對應的憑證。 本文說明適用於 Windows 的 金鑰保存庫 VM 擴充功能支援的平臺、組態和部署選項。

作業系統

金鑰保存庫 VM 擴充功能支援 Windows Server 2022 與 Windows Server 2025，適用於 AMD64 與 ARM64。 在 Windows Server 2025 中，私鑰會儲存在 KeyGuard 中。

支援的憑證

金鑰保存庫 VM 擴充功能支援下列憑證內容類型：

• PKCS #12
• PEM

特徵

適用於 Windows 的 金鑰保存庫 VM 擴充功能 4.x 版：

• 若在 Windows Server 2025 上運行且 KeyGuard 正常運作，則會將私鑰安裝到 KeyGuard 中。
• 安裝每個憑證的兩個最新版本。
• 在安裝任何包含 TLS 伺服器驗證擴充金鑰使用方式 (EKU) 的憑證前，執行憑證鏈結驗證，包括同時帶有其他 EKU (例如用戶端驗證) 的憑證。 鏈驗證錯誤會導致擴充配置失敗。 沒有伺服器認證 EKU 的憑證，以及自簽憑證（主體與發行者相同）則不受此檢查。
• 將該機器上所有源自同一個 金鑰保存庫 憑證物件的憑證串連到該憑證的最新版本。
• 支援選擇性每個憑證驗證覆寫，讓個別觀察到的憑證可使用與擴充功能預設值不同的受控身分識別向 金鑰保存庫 進行驗證。 欲了解更多資訊，請參閱 擴充架構。

從 3.0 升級

如果你是從 3.0 更新，以下功能會被更改或移除：

• pollingIntervalInS 現今限制在5至60分鐘之間。 預設情況下，該擴充功能每小時輪詢一次。
• linkOnRenewal 已被移除。 連結總是會發生。
• keyExportable 已被移除。 私鑰已無法匯出。
• requireInitialSync 已被移除。 只有當擴充功能安裝了所有已設定的憑證時，才會回報成功。
• 你已經無法設定特定版本的憑證了。
• 該擴充功能現在總是透過 Cryptography API： Next Generation （CNG） 而非 CAPI 來儲存私鑰。

先決條件

檢閱下列使用適用於 Windows 的 金鑰保存庫 VM 擴充功能的必要條件：

• 具有憑證的 Azure Key Vault 實例。 如需詳細資訊，請參閱 使用 Azure 入口網站建立金鑰保存庫。

• 具有指派 受控識別的 VM。

• 將金鑰保存庫範圍層級的金鑰保存庫秘密使用者角色，指派給 VM 或 Azure 虛擬機器擴展集的受控身分識別。 此角色會擷取憑證的私密部分。 如需詳細資訊，請參閱下列文章：

  • Azure Key Vault 中的驗證
  • 搭配 Azure Key Vault 使用 Azure RBAC 秘密、密鑰和憑證許可權
  • 金鑰保存庫 範圍的角色指派

• 使用下列 identity 組態設定虛擬機器擴展集：

  "identity": {
      "type": "UserAssigned",
      "userAssignedIdentities": {
         "[parameters('userAssignedIdentityResourceId')]": {}
      }
  }
  

• 請以以下authenticationSettings設定配置 金鑰保存庫 VM 擴充功能：

  "authenticationSettings": {
      "msiEndpoint": "[parameters('userAssignedIdentityEndpoint')]",
      "msiClientId": "[reference(parameters('userAssignedIdentityResourceId'), variables('msiApiVersion')).clientId]"
  }
  

擴展架構

下列 JSON 顯示金鑰保存庫 VM 擴充功能的結構描述。 在考慮架構實作選項之前，請先檢閱下列重要注意事項。

• 延伸模組不需要受保護的設定。 所有設定皆為公開資訊。

• 觀察到的憑證網址必須使用格式 https://myVaultName.vault.azure.net/secrets/myCertName。

  此表單是因為 /secrets 路徑會回傳完整憑證，包括私鑰，但 /certificates 路徑本身不會。 如需憑證的詳細資訊，請參閱 Azure Key Vault 密鑰、秘密和憑證概觀。 你無法指定證書的特定版本。

• URL 主機必須是已認可的 Azure Key Vault 主機。

• 具有任何authenticationSettings的 VM 的屬性是必需的。

  此屬性會指定要用於向 金鑰保存庫 進行驗證的身分識別。 請以系統指派的身份定義此屬性，以避免多重身份的虛擬機擴充功能出現問題。

{
   "type": "Microsoft.Compute/virtualMachines/extensions",
   "name": "KVVMExtensionForWindows",
   "apiVersion": "2025-04-01",
   "location": "<location>",
   "dependsOn": [
      "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
   ],
   "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForWindows",
      "typeHandlerVersion": "4.0",
      "autoUpgradeMinorVersion": true,
      "enableAutomaticUpgrade": true,
      "settings": {
         "secretsManagementSettings": {
             "observedCertificates": <An array of Key Vault 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">,
                    "accounts": <Example: ["Local Service"]>,
                    "authenticationOverride": <Optional. Overrides authenticationSettings for this certificate only, so it can authenticate with a different managed identity. Example: {"msiClientId": "11112222-bbbb-3333-cccc-4444dddd5555"}>
                },
                {
                    "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:  "00001111-aaaa-2222-bbbb-3333cccc4444">
         }
      }
   }
}

屬性值

此 JSON 結構描述包含下列屬性。

範本部署

使用 Azure Resource Manager （ARM） 範本部署 Azure VM 擴展。 當你部署一個或多個需要在部署後更新憑證的虛擬機器時，範本是理想的選擇。 你可以將擴充套件部署到個別虛擬機或 虛擬機器擴展集 實例上。 結構描述與組態對於這兩種範本類型都是通用的。

金鑰保存庫擴充功能的 JSON 設定會巢狀於 VM 或虛擬機器擴展集範本內。 針對 VM 資源擴充功能，設定會巢狀於 "resources": [] 虛擬機器物件底下。 針對虛擬機器擴展集執行個體擴充功能，設定會巢狀於 "virtualMachineProfile":"extensionProfile":{"extensions" :[] 物件底下。

下列 JSON 代碼段提供 金鑰保存庫 VM 擴充功能的 ARM 範本部署範例設定。

{
   "type": "Microsoft.Compute/virtualMachines/extensions",
   "name": "KeyVaultForWindows",
   "apiVersion": "2025-04-01",
   "location": "<location>",
   "dependsOn": [
      "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
   ],
   "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForWindows",
      "typeHandlerVersion": "4.0",
      "autoUpgradeMinorVersion": true,
      "enableAutomaticUpgrade": true,
      "settings": {
         "secretsManagementSettings": {
             "observedCertificates": <An array of Key Vault 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">,
                    "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: "00001111-aaaa-2222-bbbb-3333cccc4444">
         }
      }
   }
}

擴充套件自動升級

金鑰保存庫 VM 擴充功能支援 Azure 中虛擬機器與擴展套件的自動升級。 當你在上述範例中將 autoUpgradeMinorVersion 和 enableAutomaticUpgrade 屬性設為 true 時，Azure 會自動將延伸模組維持在最新狀態。

擴充功能相依性排序

金鑰保存庫 VM 擴充套件支援擴充套件相依排序。 擴充套件在下載並安裝所有憑證後會回報成功啟動。

如果你使用其他需要安裝憑證才能啟動的擴充功能，你可以使用擴充套件依賴排序來宣告對 金鑰保存庫 VM 擴充功能的依賴。

啟動時，金鑰保存庫虛擬機擴充功能會重複下載與安裝憑證最多 25 次，且回退時間逐漸增加，期間會維持在 Transitioning 狀態。 如果重試次數用盡，擴充功能會 回報錯誤狀態 。 成功安裝所有憑證之後，金鑰保存庫 VM 擴充功能會回報成功的啟動。

欲了解更多關於建立擴充套件間相依性的資訊，請參閱 虛擬機器擴展集 中的序列擴充配置。

Azure PowerShell 部署

使用 Azure PowerShell 部署 Azure Key Vault VM 擴充功能。 將 金鑰保存庫 VM 擴充功能設定儲存至 JSON 檔案 (settings.json)。

以下 JSON 片段提供了使用 PowerShell 部署 金鑰保存庫 VM 擴充功能的範例設定。

{
   "secretsManagementSettings": {
   "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",
          "accounts": [
             "Network Service",
             "Local Service"
          ]
      }
   ]},
   "authenticationSettings": {
      "msiEndpoint":  "http://169.254.169.254/metadata/identity/oauth2/token",
      "msiClientId":  "00001111-aaaa-2222-bbbb-3333cccc4444"
   }
}

在 VM 上部署

# Build settings
$settings = (get-content -raw ".\settings.json")
$extName =  "KeyVaultForWindows"
$extPublisher = "Microsoft.Azure.KeyVault"
$extType = "KeyVaultForWindows"

# Start the deployment
Set-AzVmExtension -TypeHandlerVersion "4.0" -ResourceGroupName <ResourceGroupName> -Location <Location> -VMName <VMName> -Name $extName -Publisher $extPublisher -Type $extType -SettingString $settings

在虛擬機器擴展集執行個體上部署

# 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 "4.0" -Setting $settings

# Start the deployment
Update-AzVmss -ResourceGroupName <ResourceGroupName> -VMScaleSetName <VmssName> -VirtualMachineScaleSet $vmss

Azure CLI 部署

使用 Azure CLI 部署 Azure Key Vault VM 擴充功能。 將 金鑰保存庫 VM 擴充功能設定儲存至 JSON 檔案 (settings.json)。

以下 JSON 片段提供了使用 Azure CLI 部署 金鑰保存庫 VM 擴充功能的範例設定。

   {
        "secretsManagementSettings": {
          "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",
                "accounts": [
                    "Network Service",
                    "Local Service"
                ]
            }
        ]
        },
          "authenticationSettings": {
          "msiEndpoint":  "http://169.254.169.254/metadata/identity/oauth2/token",
          "msiClientId":  "00001111-aaaa-2222-bbbb-3333cccc4444"
        }
     }

在 VM 上部署

# Start the deployment
az vm extension set --name "KeyVaultForWindows" `
 --publisher Microsoft.Azure.KeyVault `
 --resource-group "<resourcegroup>" `
 --vm-name "<vmName>" `
 --settings "@settings.json" `
 --version "4.0"

在虛擬機器擴展集執行個體上部署

# Start the deployment
az vmss extension set --name "KeyVaultForWindows" `
 --publisher Microsoft.Azure.KeyVault `
 --resource-group "<resourcegroup>" `
 --vmss-name "<vmssName>" `
 --settings "@settings.json" `
 --version "4.0"

az vm extension delete --name "KeyVaultForWindows" --resource-group "<resourcegroup>" --vm-name "<vmName>"

故障排除

利用這些建議來排查部署問題。

檢查常見問題

觀察到的憑證數目是否有限制？

否。 金鑰保存庫 VM 擴充功能不會限制觀察到的憑證數目（observedCertificates）。

未指定帳戶時的默認許可權為何？

根據預設，系統管理員和系統會收到完全控制。

如何判斷憑證金鑰是否為 CAPI1 或 CNG？

從 金鑰保存庫 VM 擴充 4.0 開始，該擴充套件透過使用 CNG 儲存所有憑證的私鑰。

延伸模組是否支持憑證自動重新系結？

是，Azure Key Vault VM 擴充功能支援憑證自動重新繫結。 金鑰保存庫 VM 擴充功能支援憑證續期時的 S-channel 綁定。

針對 IIS，您可以啟用 IIS 中憑證更新的自動重新繫結，以設定自動重新繫結。 Azure Key Vault VM 擴充功能在安裝與現有憑證相同的 金鑰保存庫 憑證物件的更新憑證時，會產生憑證生命週期通知。 IIS 會使用此事件自動重新系結憑證。 欲了解更多資訊，請參閱 IIS 中的憑證重新綁定。

檢視擴充功能狀態

在 Azure 入口網站中，或使用 PowerShell 或 Azure CLI 檢查擴充功能部署的狀態。

若要查看指定 VM 的擴充功能部署狀態，請執行下列命令。

• 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"
  

檢閱記錄和設定

金鑰保存庫 VM 擴充功能記錄只存在於 VM 本機上。 檢閱記錄詳細數據以協助進行疑難解答。

Windows 上的憑證安裝

適用於 Windows 的 金鑰保存庫 VM 擴充功能會將憑證安裝到 Windows 證書存儲中。 當擴充套件從 金鑰保存庫 下載憑證時，它會：

1. 安裝所有中繼憑證和分葉憑證，無論存在多少個中繼憑證。 這個擴充功能不會安裝根憑證，因為它沒有授權安裝。 確保根憑證在系統上是可信的。
   • 將葉子憑證安裝於指定的憑證儲存庫（certificateStoreName）與位置（certificateStoreLocation）。
   • 在中繼憑證授權機構存放區中安裝中繼 CA 憑證。
2. 將憑證放入指定的憑證儲存庫（certificateStoreName）與位置（certificateStoreLocation）。
3. 根據設定中指定的設定，對私鑰 accounts 套用適當的權限。
4. 設定 CERT_RENEWAL 該屬性，使得像 IIS 這類應用程式的憑證綁定在憑證續期時自動更新。 憑證會鏈結至源自相同 金鑰保存庫 憑證物件的最新版本，並以該憑證的 金鑰保存庫 祕密基底 URL 識別。 對應於不同 金鑰保存庫 憑證物件的憑證，彼此之間絕不會連結。

預設憑證存放區

預設情況下，擴充功能會在以下位置安裝憑證：

• 店名：MY（個人）。
• 店面位置：LocalMachine。

憑證存取控制

根據預設，系統管理員和 SYSTEM 會收到已安裝憑證的完整控制許可權。 你可以透過憑證 accounts 設定中的陣列來自訂存取權限：

"accounts": ["Network Service", "Local Service"]

此設定允許指定帳號讀取權限，允許以這些身份執行的應用程式使用憑證。

憑證更新

當在 金鑰保存庫 中重新更新憑證時，該擴充功能會自動執行：

1. 下載新的憑證版本。
2. 將憑證安裝到已設定的憑證儲存庫中。
3. 使用 CERT_RENEWAL 屬性保留現有的繫結。

管理憑證生命週期

對於支援憑證服務生命週期通知的 IIS 等應用程式，金鑰保存庫 VM 擴充功能在安裝與現有憑證相同的 金鑰保存庫 憑證物件（將新憑證連結至前一個憑證）的更新憑證時，會在 Windows 事件日誌中觸發事件 1001。 IIS 會訂閱此事件，以自動重新綁定更新的憑證而不中斷服務。 其他應用程式與團隊也可監聽事件 1001，以依需求處理憑證續期。 欲了解更多資訊，請參閱 憑證服務生命週期通知。

取得支援

Microsoft 僅支援 金鑰保存庫 VM 擴充的 3.0 及以後版本。 如果你使用的是版本 1.0，請先升級到最新版本再申請支援。

請使用以下其他選項來協助解決部署問題：

• 如需協助，請聯絡Microsoft Q&A中的Azure專家。

• 如果您在此網站上找不到答案，您可張貼問題以徵求 Microsoft 或社群其他成員的意見。

• 您也可以連絡 Microsoft 支援服務。 有關使用 Azure 支援 的資訊，請參見 如何建立Azure 支援請求。