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

2025-05-20

Azure Key Vault 仮想マシン (VM) 拡張機能は、Azure キーコンテナーに格納されている証明書を自動更新できるようにします。この拡張機能では、キーコンテナーに格納されている確認済みの証明書のリストが監視されます。変更が検出されると、拡張によって取得され、対応する証明書がインストールされます。この記事では、Windows 用の Key Vault VM 拡張機能でサポートされているプラットフォーム、構成、デプロイオプションについて詳しく説明します。

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

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

サポートされている証明書

Key Vault VM 拡張機能では、次の証明書コンテンツタイプがサポートされています。

PKCS #12
PEM

注

Key Vault VM 拡張機能は、すべての証明書を Windows 証明書ストア、または VM 拡張機能設定の certificateStoreLocation プロパティで指定された場所にダウンロードします。

特徴

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

ダウンロードした証明書に ACL アクセス許可を追加する
証明書ストアの証明書ごとの構成を可能にする
秘密キーをエクスポートする
IIS 証明書の再バインドのサポート

前提条件

Windows 用の Key Vault VM 拡張機能を使用する際の次の前提条件を確認します。

証明書を含む Azure Key Vault インスタンス。詳細については、Azure portal を使用したキーコンテナーの作成に関する記事を参照してください。
マネージド ID が割り当てられた VM。
Key Vault Secrets User ロールは、VM と Azure Virtual Machine Scale Sets マネージド ID のKey Vault スコープレベルで割り当てる必要があります。このロールでは、証明書のシークレットの部分を取得できます。詳細については、次の記事を参照してください。

Virtual Machine Scale Sets には、次の identity 構成が含まれている必要があります。

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

Key Vault VM 拡張機能には、次の authenticationSettings 構成が含まれている必要があります。

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

注

古いアクセスポリシーのアクセス許可モデルを使用して、VM とVirtual Machine Scale Sets へのアクセス権を付与することもできます。このメソッドには、シークレットに対する get および list アクセス許可を持つポリシーが必要です。詳細については、キーコンテナーへのアクセスポリシーの割り当てに関するページを参照してください。

拡張機能のスキーマ

次の JSON は、Key Vault VM 拡張機能のスキーマを示しています。スキーマ実装オプションを検討する前に、次の重要な注意事項を確認してください。

拡張機能では、設定を保護する必要がありません。すべての設定が公開情報と見なされます。
確認済みの証明書の URL は、https://myVaultName.vault.azure.net/secrets/myCertName の形式である必要があります。

/secrets のパスでは秘密キーを含む完全な証明書が返されますが、/certificates のパスでは返されないため、この形式が推奨されます。証明書の詳細については、「Azure Key Vault のキー、シークレット、証明書の概要」を参照してください。
authenticationSettings プロパティは、任意のユーザー割り当て ID を使用する VM の場合にのみ必須です。

このプロパティが、Key Vault への認証に使用する ID を指定します。 VM 拡張機能が複数の ID を使用することに関する問題を回避するために、システム割り当て ID でこのプロパティを定義します。

{
   "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:  "00001111-aaaa-2222-bbbb-3333cccc4444">
         }
      }
   }
}

プロパティ値

JSON スキーマには、次のプロパティが含まれています。

名前	値/例	データ型
`apiVersion`	2022-08-01	date
`publisher`	Microsoft.Azure.KeyVault	ひも
`type`	KeyVaultForWindows	ひも
`typeHandlerVersion`	"3.0"	ひも
`pollingIntervalInS`	"3600"	ひも
`linkOnRenewal` (省略可)	ほんとう	ブーリアン
`requireInitialSync` (省略可)	偽り	ブーリアン
`observedCertificates`	[{...}, {...}]	文字列配列
`observedCertificates/url`	"https://myvault.vault.azure.net/secrets/mycertificate"	ひも
`observedCertificates/certificateStoreName`	私の	ひも
`observedCertificates/certificateStoreLocation`	LocalMachine または CurrentUser (大文字と小文字を区別する)	ひも
`observedCertificates/keyExportable` (省略可)	偽り	ブーリアン
`observedCertificates/accounts` (省略可)	["ネットワークサービス"、"ローカルサービス"]	文字列配列
`msiEndpoint`	"http://169.254.169.254/metadata/identity/oauth2/token"	ひも
`msiClientId`	00001111-aaaa-2222-bbbb-3333cccc4444	ひも

テンプレートのデプロイ

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

キーコンテナー拡張機能の JSON 構成は、VM または Virtual Machine Scale Sets のテンプレート内で入れ子にされています。 VM リソース拡張機能の場合、構成は "resources": [] 仮想マシンオブジェクトの下で入れ子になります。 Virtual Machine Scale Sets インスタンス拡張機能の場合、構成は "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: "00001111-aaaa-2222-bbbb-3333cccc4444">
         }
      }
   }
}

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

Key Vault VM 拡張機能を有効にすることで、拡張機能の依存関係の順序付けをサポートできます。既定では、ポーリングが開始されるとすぐに、Key Vault VM 拡張機能により正常な開始が報告されます。ただし、正常な開始を報告するように拡張機能を構成できるのは、拡張機能がすべての証明書をダウンロードしてインストールした後だけです。

すべての証明書のインストールを必要とする他の拡張機能を開始前に使用する場合は、Key Vault VM 拡張機能で拡張機能の依存関係の順序付けを有効にすることができます。この機能を使用すると、他の拡張機能で Key Vault VM 拡張機能への依存関係を宣言できます。

この機能を使用すると、依存するすべての証明書がインストールされるまで、他の拡張機能の開始を防ぐことができます。この機能が有効になっている場合、Key Vault VM 拡張機能は、バックアップ期間が長くなれば、証明書のダウンロードとインストールを最大 25 回再試行し、その間は移行中の状態を維持します。再試行が使い果たされた場合、拡張機能は エラー 状態を報告します。すべての証明書が正常にインストールされると、Key Vault VM 拡張機能によって正常な開始が報告されます。

Key Vault VM 拡張機能で拡張機能の依存関係の順序付け機能を有効にするには、secretsManagementSettings プロパティを設定します。

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

拡張機能間の依存関係を設定する方法については、「仮想マシンスケールセット内の拡張機能のプロビジョニングをシーケンス処理する」を参照してください。

重要

拡張機能の依存関係の順序付け機能は、システム割り当て ID を作成し、その ID を使用して Key Vault アクセスポリシーを更新する ARM テンプレートには対応していません。このシナリオでこの機能を使用しようとすると、すべての拡張機能が開始されるまで Key Vault アクセスポリシーを更新できないため、デッドロックが発生します。その代わりに、"単一ユーザー割り当て MSI ID" を使用し、その ID でキーコンテナーに事前 ACL を設定してからデプロイします。

Azure PowerShell でのデプロイ

Azure Key Vault VM 拡張機能は、Azure PowerShell を使用してデプロイできます。 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":  "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 "3.0" -ResourceGroupName <ResourceGroupName> -Location <Location> -VMName <VMName> -Name $extName -Publisher $extPublisher -Type $extType -SettingString $settings

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

Azure CLI でのデプロイ

Azure Key Vault VM 拡張機能は、Azure CLI を使用してデプロイできます。 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":  "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"

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"

問題のトラブルシューティング

デプロイの問題のトラブルシューティング方法に関する推奨事項を次にいくつか示します。

よく寄せられる質問を確認する

確認済み証明書の数に制限はありますか?

いいえ。 Key Vault VM 拡張機能には、確認済み証明書の数に制限はありません (observedCertificates)。

アカウントが指定されていない場合の既定のアクセス許可は何ですか?

既定では、管理者と SYSTEM にはフルコントロールが付与されています。

証明書キーが CAPI1 であるか CNG であるかをどのように判断すればよいですか?

拡張機能は、PFXImportCertStore API の既定の動作によって異なります。規定では、証明書の Provider Name 属性が CAPI1 と一致する場合は、CAPI1 API を使用して証明書がインポートされます。それ以外の場合、証明書は CNG API を使用してインポートされます。

拡張機能は証明書の自動再バインドをサポートしていますか?

はい。Azure Key Vault VM 拡張機能では、証明書の自動再バインドがサポートされています。 Key Vault VM 拡張機能では、linkOnRenewal プロパティが true に設定されているとき、証明書の更新時に S チャネルバインドがサポートされます。

IIS の場合、IIS で証明書更新の自動再バインドを有効にすることで自動再バインドを構成できます。 Azure Key Vault VM 拡張機能では、SAN が一致する証明書がインストールされると、証明書ライフサイクル通知が生成されます。 IIS は、このイベントを使用して証明書を自動再バインドします。詳細については、「IIS での証明書の再バインド」を参照してください。

拡張機能の状態表示

Azure portal で、あるいは 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 拡張機能サービスの構成とバイナリ。

Windows での証明書のインストール

Windows 用 Key Vault VM 拡張機能は、Windows 証明書ストアに証明書をインストールします。 Key Vault から証明書をダウンロードすると、拡張機能は次のようになります。

中間証明書の数に関係なく、すべての中間証明書とリーフ証明書をインストールします。ルート証明書はインストールされません。拡張機能にはルートインストールの実行が許可されていないためです。ルート証明書がシステムで信頼されていることを確認するのは、サービス所有者の責任です。
- リーフ証明書は、指定された証明書ストア (certificateStoreName) と場所 (certificateStoreLocation) にインストールされます
- 中間 CA 証明書が中間証明機関ストアにインストールされている
指定した証明書ストア (certificateStoreName) と場所 (certificateStoreLocation) に証明書を配置します
構成で指定された accounts に基づいて、秘密キーに適切なアクセス許可を適用します
証明書の更新時に IIS などのアプリケーションの証明書バインドが自動的に更新されるように、 linkOnRenewal プロパティ (有効な場合) を設定します

既定の証明書ストア

指定しない場合、証明書は既定で次の場所にインストールされます。

ストア名: MY (個人用)
店舗所在地: LocalMachine

証明書のアクセス制御

既定では、管理者と SYSTEM は、インストールされている証明書に対するフルコントロールのアクセス許可を受け取ります。証明書構成の accounts 配列を使用してアクセスをカスタマイズできます。

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

これにより、指定したアカウントへの読み取りアクセスが許可され、それらの ID で実行されているアプリケーションで証明書を使用できるようになります。

証明書の更新

Key Vault で証明書が更新されると、拡張機能は自動的に次のようになります。

新しい証明書バージョンをダウンロードします
構成済みの証明書ストアにインストールします
有効になっている場合は、 linkOnRenewal 機能を使用して既存のバインドを維持します

証明書のライフサイクルの管理

証明書ライフサイクル通知をサポートする IIS などのアプリケーションでは、サブジェクトの別名 (SAN) に一致する証明書がインストールされると、拡張機能によってイベントが生成され、サービスを中断することなく自動再バインドが可能になります。

サポートを受ける

デプロイの問題の解決に役立つその他のオプションを次に示します。

支援が必要な場合は、Q&A および Stack Overflow のフォーラムで Azure エキスパートに問い合わせてください。
サイトに回答が見つからない場合は、質問を投稿して、Microsoft またはコミュニティの他のメンバーからの回答を得られます。
Microsoft サポートにお問い合わせいただくこともできます。 Azure サポートの使用方法の詳細については、Azure サポートに関する FAQ を参照してください。

次の方法で共有

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

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

サポートされている証明書

特徴

前提条件

拡張機能のスキーマ

プロパティ値

テンプレートのデプロイ

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

Azure PowerShell でのデプロイ

VM でデプロイする

Virtual Machine Scale Sets インスタンスでデプロイする

Azure CLI でのデプロイ

VM でデプロイする

Virtual Machine Scale Sets インスタンスでデプロイする

問題のトラブルシューティング

よく寄せられる質問を確認する

確認済み証明書の数に制限はありますか?

アカウントが指定されていない場合の既定のアクセス許可は何ですか?

証明書キーが CAPI1 であるか CNG であるかをどのように判断すればよいですか?

拡張機能は証明書の自動再バインドをサポートしていますか?

拡張機能の状態表示

ログと構成を確認する

Windows での証明書のインストール

既定の証明書ストア

証明書のアクセス制御

証明書の更新

証明書のライフサイクルの管理

サポートを受ける

フィードバック

その他のリソース

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