Windows 用の Key Vault 仮想マシン拡張機能

[アーティクル]
09/29/2022

Key Vault VM 拡張機能では、Azure キーコンテナーに保存されている証明書の自動更新が行われます。この拡張機能は、具体的には、Key Vault に保存されている観察対象の証明書の一覧を監視し、変更の検出時に取得し、対応する証明書をインストールします。このドキュメントでは、Windows 用の Key Vault VM 拡張機能でサポートされているプラットフォーム、構成、デプロイオプションについて詳しく説明します。

オペレーティングシステム

Key Vault VM 拡張機能では、以下のバージョンの Windows がサポートされています。

Windows Server 2019
Windows Server 2016
Windows Server 2012

Key Vault VM 拡張機能は、Azure で使用するために、Windows Server 2019 Core インストールを使用してアップロードされ、特殊化されたイメージに変換されたカスタムローカル VM でもサポートされています。

注意

Key Vault VM 拡張機能は、Windows 証明書ストア内のすべての証明書を、VM 拡張機能設定の "certificateStoreLocation" プロパティによって指定された場所にダウンロードします。現在、KV VM 拡張機能は、ローカルシステム管理者アカウントにのみ証明書のプライベートキーへのアクセスを許可します。また、現在、証明書ごとに証明書ストアの場所を定義することはできません。 VM 拡張機能チームは、この機能のギャップを埋めるための解決策に取り組んでいます。

サポートされている証明書の内容の種類

PKCS #12
PEM

前提条件

証明書を持つ Key Vault インスタンス。 Key Vault の作成に関するページを参照してください
VM にはマネージド ID が割り当てられている必要があります
Key Vault アクセスポリシーは、シークレットの get および list アクセス許可を使用して、VM/VMSS マネージド ID が証明書の秘密の部分を取得できるように設定する必要があります。 Key Vault に対して認証を行う方法に関するページと「Key Vault アクセスポリシーを割り当てる」を参照してください。
Virtual Machine Scale Sets には、次の ID 設定が必要です。

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

AKV 拡張機能には、次の設定が必要です。

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

拡張機能のスキーマ

次の JSON は、Key Vault VM 拡張機能のスキーマを示しています。この拡張機能では、保護された設定は必要ありません。そのすべての設定はパブリック情報と見なされます。この拡張機能には、監視対象の証明書、ポーリング頻度、および宛先の証明書ストアの一覧が必要です。具体的な内容は次のとおりです。

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

注意

確認された証明書の URL は、https://myVaultName.vault.azure.net/secrets/myCertName の形式である必要があります。

これは、/secrets のパスでは秘密キーを含む完全な証明書が返されるのに対し、/certificates のパスでは返されないためです。証明書について詳しくは、次の記事をご覧ください: 「Key Vault 証明書」

重要

"authenticationSettings" プロパティは、ユーザー割り当て ID を使用する VM の場合にのみ必須です。システム割り当て ID を使用する場合でも、これは引き続き必要です。それ以外の場合、VM 拡張機能は使用する ID を認識しません。このセクションがないと、ユーザー割り当て ID を持つ VM によって、Key Vault拡張機能が失敗し、証明書をダウンロードできなくなります。 Key Vault への認証に使用する ID を指定します。

重要

'msiClientId' を指定する場合は、'msiEndpoint' プロパティが必要です。通常、値は http://169.254.169.254/metadata/identity/oauth2/token に設定する必要があります。

プロパティ値

名前	値/例	データ型
apiVersion	2019-07-01	date
publisher	Microsoft.Azure.KeyVault	string
type	KeyVaultForWindows	string
typeHandlerVersion	1.0	INT
pollingIntervalInS	3600	string
certificateStoreName	MY	string
linkOnRenewal	false	boolean
certificateStoreLocation	LocalMachine または CurrentUser (大文字と小文字を区別する)	string
requireInitialSync	true	boolean
observedCertificates	["https://myvault.vault.azure.net/secrets/mycertificate", "https://myvault.vault.azure.net/secrets/mycertificate2"]	文字列配列
msiEndpoint	http://169.254.169.254/metadata/identity	string
msiClientId	c7373ae5-91c2-4165-8ab6-7381d6e75619	string

テンプレートのデプロイ

Azure VM 拡張機能は、Azure Resource Manager テンプレートでデプロイできます。テンプレートは、デプロイ後の証明書の更新が必要な仮想マシンを 1 つ以上デプロイするときに最適です。拡張機能は、個々の VM または仮想マシンスケールセットにデプロイできます。スキーマと構成は、両方のテンプレートの種類に共通です。

仮想マシン拡張機能の JSON の構成は、テンプレートの仮想マシンリソースのフラグメント内に入れ子にする必要があります (具体的には、仮想マシンテンプレートの場合は "resources": [] オブジェクト、仮想マシンスケールセットの場合は "virtualMachineProfile":"extensionProfile":{"extensions" :[] オブジェクト)。

注意

VM 拡張機能では、Key Vault に対する認証のために、システムまたはユーザーのマネージド ID が割り当てられている必要があります。 Key Vault に対して認証を行う方法と 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"]>
        }      
      }
      }
    }

拡張機能の依存関係の順序付け

Key Vault VM 拡張機能は、構成されている場合に拡張機能の順序付けをサポートします。既定では、拡張機能は、正常に起動したことを、ポーリングの開始直後に報告します。ただし、証明書の完全な一覧が正常にダウンロードされた後に、正常な起動を報告するように構成することができます。他の拡張機能が、起動する前に一連の証明書がすべてインストールされていることに依存している場合は、この設定を有効にすると、これらの拡張機能によって Key Vault 拡張機能に対する依存関係が宣言されるようになります。これにより、依存先であるすべての証明書がインストールされるまで、これらの拡張機能を起動できなくなります。拡張機能によって、最初のダウンロードが無期限に再試行され、Transitioning 状態のままとなります。

これを有効にするには、次のように設定します。

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

注意

システム割り当て ID を作成し、その ID を使用して Key Vault アクセスポリシーを更新する ARM テンプレートに対しては、この機能を使用することはできません。それを行うと、すべての拡張機能が起動するまでコンテナーのアクセスポリシーが更新されなくなり、デッドロックが発生することになります。そうではなく、"単一ユーザー割り当て MSI ID" を使用し、その ID でコンテナーに事前 ACL を設定してからデプロイする必要があります。

Azure PowerShell でのデプロイ

警告

多くの場合、PowerShell クライアントは settings.json で " に \ を追加します。この場合、akvvm_service が次のエラーで失敗します。[CertificateManagementConfiguration] Failed to parse the configuration settings with:not an object. ポータルの [拡張機能] の [設定] に余分な文字 \ と " が表示されています。これを回避するには、PowerShell HashTable として $settings を初期化します。

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

Azure PowerShell を使用すると、Key Vault VM 拡張機能を既存の仮想マシンまたは仮想マシンのスケールセットにデプロイすることができます。

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

仮想マシンスケールセットに拡張機能をデプロイするには:


    # 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

Azure CLI でのデプロイ

Azure CLI を使用すると、Key Vault VM 拡張機能を既存の仮想マシンまたは仮想マシンスケールセットにデプロイすることができます。

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> \"] }}'

仮想マシンスケールセットに拡張機能をデプロイするには:

      # 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> \"] }}'

次の制限/要件に注意してください。

Key Vault の制限:
- デプロイ時に存在している必要があります
- マネージド ID を使用して VM/VMSS ID に Key Vault アクセスポリシーが設定されている必要があります。 Key Vault に対して認証を行う方法に関するページと「Key Vault アクセスポリシーを割り当てる」を参照してください。

トラブルシューティングとサポート

よく寄せられる質問

設定できる observedCertificates の数に制限はありますか? いいえ。Key Vault VM 拡張機能には、observedCertificates の数に制限はありません。

トラブルシューティング

拡張機能のデプロイ状態に関するデータを取得するには、Azure Portal または Azure PowerShell を使用します。特定の VM での拡張機能のデプロイ状態を確認するには、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"

ログと構成

Key Vault VM 拡張機能のログは、VM 上のローカルにのみ存在し、トラブルシューティングの際に大変役に立ちます

場所	説明
C:\WindowsAzure\Logs\WaAppAgent.log	拡張機能の更新が発生した時間を示します。
C:\WindowsAzure\Logs\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows\<most recent version>\	証明書のダウンロードの状態を示します。ダウンロード場所は常に、Windows コンピューターの My ストア (certlm.msc) になります。
C:\Packages\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows\<most recent version>\RuntimeSettings\	Key Vault VM 拡張機能サービスのログには、akvvm_service サービスの状態が示されます。
C:\Packages\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows\<most recent version>\Status\	Key Vault VM 拡張機能サービスの構成とバイナリ。

サポート

この記事についてさらにヘルプが必要な場合は、いつでも MSDN の Azure フォーラムと Stack Overflow フォーラムで Azure エキスパートに問い合わせることができます。または、Azure サポートインシデントを送信できます。その場合は、Azure サポートのサイトに移動して、[サポートの要求] をクリックします。 Azure サポートの使用方法の詳細については、「 Microsoft Azure サポートに関する FAQ」を参照してください。