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

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

作業系統

Key Vault VM 擴充功能支援下列版本的 Windows:

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

自訂本機 VM 也支援 Key Vault VM 擴充功能。 應該上傳 VM 並轉換成特殊化映像,以使用 Windows Server 2019 核心安裝在 Azure 中使用。

支援的憑證

Key Vault VM 擴充功能支援下列憑證內容類型:

  • PKCS #12
  • PEM

注意

Key Vault VM 擴充功能會將所有憑證下載至 Windows 憑證存放區或 VM 擴充功能設定中 certificateStoreLocation 屬性提供的位置。

3.0+ 版中的更新

適用於 Windows 的 Key Vault VM 擴充功能 3.0 版新增對下列功能的支援:

  • 將 ACL 權限新增至下載的憑證
  • 為每個憑證啟用憑證存放區設定
  • 匯出私密金鑰
  • IIS 憑證重新繫結支援

必要條件

請檢閱下列使用適用於 Windows 的 Key Vault VM 擴充功能的必要條件:

  • 具有憑證的 Azure Key Vault 執行個體。 如需詳細資訊,請參閱使用 Azure 入口網站來建立金鑰保存庫

  • VM 已獲指派受控識別

  • VM 和 Azure 虛擬機器擴展集受控識別之 Key Vault 範圍層級必須已獲指派 Key Vault 秘密使用者角色。 此角色會擷取秘密的憑證部分。 如需詳細資訊,請參閱下列文章:

  • 虛擬機器擴展集應該具有下列 identity 設定:

    "identity": {
       "type": "UserAssigned",
       "userAssignedIdentities": {
          "[parameters('userAssignedIdentityResourceId')]": {}
       }
    }
    
  • Key Vault VM 擴充功能應該具有下列 authenticationSettings 設定:

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

注意

舊的存取原則權限模型也可以用來提供 VM 和虛擬機器擴展集的存取權限。 此方法需要具有秘密的取得列出權限。 如需詳細資訊,請參閱指派 Key Vault 存取原則

擴充功能結構描述

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

  • 擴充功能不需要受保護的設定。 所有設定都會視為公開資訊。

  • 觀察到的憑證 URL 格式應該是 https://myVaultName.vault.azure.net/secrets/myCertName

    偏好此格式是因為 /secrets 路徑會傳回完整憑證,私密金鑰也包括在內,/certificates 路徑則不會。 如需憑證的詳細資訊,請參閱 Azure Key Vault 金鑰、祕密和憑證概觀

  • 具有任何使用者指派的身分識別的 VM,需要authenticationSettings 屬性。

    此屬性指定要用來驗證 Key Vault 的身分識別。 使用系統指派的身分識別來定義此屬性,以免發生具有多個身分識別的 VM 擴充功能問題。

{
   "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">
         }
      }
   }
}

屬性值

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

名稱 值/範例 資料類型
apiVersion 2022-08-01 date
publisher Microsoft.Azure.KeyVault string
type KeyVaultForWindows string
typeHandlerVersion "3.0" string
pollingIntervalInS "3600" string
linkOnRenewal (選用) true boolean
requireInitialSync (選用) false boolean
observedCertificates [{...}, {...}] 字串陣列
observedCertificates/url "https://myvault.vault.azure.net/secrets/mycertificate" string
observedCertificates/certificateStoreName MY string
observedCertificates/certificateStoreLocation LocalMachine 或 CurrentUser (區分大小寫) string
observedCertificates/keyExportable (選用) false boolean
observedCertificates/accounts (選用) ["Network Service", "Local Service"] 字串陣列
msiEndpoint "http://169.254.169.254/metadata/identity/oauth2/token" string
msiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619 string

範本部署

您可以使用 Azure Resource Manager (ARM) 範本部署 Azure VM 擴充功能。 部署一或多部需要部署後重新整理憑證的虛擬機器時,很適合使用範本。 此擴充功能可以部署到個別的 VM 或虛擬機器擴展集執行個體。 結構描述與組態對於這兩種範本類型都是通用的。

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

下列 JSON 程式碼片段提供 Key Vault VM 擴充功能的 ARM 範本部署範例設定。

{
   "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">
         }
      }
   }
}

擴充功能相依性排序

您可以啟用 Key Vault VM 擴充功能,以支援擴充功能相依性排序。 根據預設,Key Vault VM 擴充功能會在輪詢開始時報告啟動成功。 不過,您可以設定擴充功能,只在擴充功能下載並安裝所有憑證之後,才報告成功的開始時間。

如果您在開始之前使用其他需要安裝所有憑證的擴充功能,您可以在 Key Vault VM 擴充功能中啟用擴充功能相依性排序。 這項功能可讓其他擴充功能宣告 Key Vault VM 擴充功能的相依性。

您可以使用這項功能來防止其他擴充功能開始,直到安裝所有相依憑證為止。 啟用此功能時,Key Vault VM 擴充功能會無限期地下載並安裝憑證,並維持轉換狀態,直到所有憑證都成功安裝為止。 所有憑證都存在之後,Key Vault VM 擴充功能會回報啟動成功。

若要在 Key Vault VM 擴充功能中啟用擴充功能相依性排序功能,請設定 secretsManagementSettings 屬性:

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

如需如何設定擴充功能之間相依性的詳細資訊,請參閱為虛擬機器擴展集中的擴充功能佈建排序

重要

擴充功能相依性排序功能與 ARM 範本不相容,該範本會建立系統指派的身分識別,並使用該身分識別更新 Key Vault 存取原則。 如果您嘗試使用此案例中的功能,就會發生死結,因為 Key Vault 存取原則必須等到所有擴充功能啟動後才能更新。 您應該改為使用單一使用者指派的 MSI 身分識別,並在部署之前使用該身分識別針對您的金鑰保存庫預先進行 ACL。

Azure PowerShell 部署

您可以使用 Azure PowerShell 來部署 Azure Key Vault VM 擴充功能。 將 Key Vault VM 擴充功能設定儲存至 JSON 檔案 (settings.json)。

下列 JSON 程式碼片段提供使用 PowerShell 部署 Key Vault VM 擴充功能的範例設定。

{   
   "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"
   }      
}

在 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

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

# 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 

Azure CLI 部署

您可以使用 Azure CLI 來部署 Azure Key Vault VM 擴充功能。 將 Key Vault VM 擴充功能設定儲存至 JSON 檔案 (settings.json)。

下列 JSON 程式碼片段提供使用 Azure CLI 部署 Key Vault VM 擴充功能的範例設定。

   {   
        "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"
        }      
     }

在 VM 上部署

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

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

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

針對問題進行疑難排解

以下是如何針對部署問題進行疑難排解的一些建議。

查看常見問題集

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

否。 Key Vault VM 擴充功能對於觀察到的憑證沒有數目上的限制 (observedCertificates)。

未指定帳戶時的預設權限為何?

根據預設,系統管理員和系統將獲得完全控制。

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

擴充功能依賴 PFXImportCertStore API 的預設行為。 根據預設,如果憑證具有與 CAPI1 相符的提供者名稱屬性,則會使用 CAPI1 API 匯入憑證。 否則,會使用 CNG API 匯入憑證。

擴充功能是否支援憑證自動重新繫結?

是,Azure Key Vault VM 擴充功能支援憑證自動重新繫結。 當 linkOnRenewal 屬性設定為 true 時,Key Vault VM 擴充功能支援憑證更新上的 S 通道繫結。

針對 IIS,您可以啟用 IIS 中憑證更新的自動重新繫結,以設定自動重新繫結。 安裝具有相符 SAN 的憑證時,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"
    

檢閱記錄和設定

Key Vault VM 擴充功能記錄只存在於 VM 本機上。 檢閱記錄詳細資料以協助進行疑難排解。

記錄檔 描述
C:\WindowsAzure\Logs\WaAppAgent.log` 顯示擴充功能的更新發生時機。
C:\WindowsAzure\Logs\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<最新版本>\ 顯示憑證下載的狀態。 下載位置一律是 Windows 電腦的 MY 存放區 (certlm.msc)。
C:\Packages\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<最新版本>\RuntimeSettings\ Key Vault VM 延伸模組服務記錄會顯示 akvvm_service 服務的狀態。
C:\Packages\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<最新版本>\Status\ Key Vault VM 擴充功能服務的設定和二進位檔。

取得支援

以下還有一些可協助您解決部署問題的其他選項: