次の方法で共有


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

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

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

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

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

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

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

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

  • PKCS #12
  • PEM

Note

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

バージョン 3.0+ の更新

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

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

前提条件

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

Note

古いアクセス ポリシーのアクセス許可モデルを使用して、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:  "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 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: "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,
   ...
}

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

重要

拡張機能の依存関係の順序付け機能は、システム割り当て 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":  "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

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

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 拡張機能サービスの構成とバイナリ。

サポートを受ける

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

  • 支援が必要な場合は、Q&A および Stack Overflow のフォーラムで Azure エキスパートに問い合わせてください。

  • サイトに回答が見つからない場合は、質問を投稿して、Microsoft またはコミュニティの他のメンバーからの回答を得られます。

  • Microsoft サポートにお問い合わせいただくこともできます。 Azure サポートの使用方法の詳細については、Azure サポートに関する FAQ を参照してください。