Windows için Azure Key Vault sanal makine uzantısı

  • Makale

Azure Key Vault sanal makinesi (VM) uzantısı, Bir Azure anahtar kasasında depolanan sertifikaların otomatik olarak yenilenmesini sağlar. Uzantı, anahtar kasalarında depolanan gözlemlenen sertifikaların listesini izler. Bir değişiklik algıladığında uzantı ilgili sertifikaları alır ve yükler. Bu makalede, Windows için Key Vault VM uzantısı için desteklenen platformlar, yapılandırmalar ve dağıtım seçenekleri açıklanmaktadır.

İşletim sistemleri

Key Vault VM uzantısı aşağıdaki Windows sürümlerini destekler:

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

Key Vault VM uzantısı özel bir yerel VM'de de desteklenir. VM, Windows Server 2019 çekirdek yüklemesi kullanılarak Azure'da kullanılmak üzere karşıya yüklenip özel bir görüntüye dönüştürülmelidir.

Desteklenen sertifikalar

Key Vault VM uzantısı aşağıdaki sertifika içerik türlerini destekler:

  • PKCS #12
  • PEM

Not

Key Vault VM uzantısı tüm sertifikaları Windows sertifika deposuna veya VM uzantısı ayarlarında özelliğinde certificateStoreLocation belirtilen konuma indirir.

Sürüm 3.0+ güncelleştirmeleri

Windows için Key Vault VM uzantısının 3.0 sürümü aşağıdaki özellikler için destek ekler:

  • İndirilen sertifikalara ACL izinleri ekleme
  • Sertifika başına Sertifika Deposu yapılandırmasını etkinleştirme
  • Özel anahtarları dışarı aktarma
  • IIS Sertifika Yeniden Bağlama desteği

Önkoşullar

Windows için Key Vault VM uzantısını kullanmak için aşağıdaki önkoşulları gözden geçirin:

  • Sertifikaya sahip bir Azure Key Vault örneği. Daha fazla bilgi için bkz . Azure portalını kullanarak anahtar kasası oluşturma.

  • Atanmış yönetilen kimliğe sahip bir VM.

  • Key Vault Gizli Dizileri Kullanıcı rolü, VM'ler ve Azure Sanal Makine Ölçek Kümeleri yönetilen kimliği için Key Vault kapsam düzeyinde atanmalıdır. Bu rol, sertifikanın gizli dizi bölümünü alır. Daha fazla bilgi için aşağıdaki makaleleri inceleyin:

  • Sanal Makine Ölçek Kümeleri aşağıdaki identity yapılandırmaya sahip olmalıdır:

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

  • Key Vault VM uzantısı aşağıdaki authenticationSettings yapılandırmaya sahip olmalıdır:

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

Not

Eski erişim ilkesi izin modeli, VM'lere ve Sanal Makine Ölçek Kümeleri erişim sağlamak için de kullanılabilir. Bu yöntem, gizli diziler üzerinde alma ve listeleme izinlerine sahip ilke gerektirir. Daha fazla bilgi için bkz . Key Vault erişim ilkesi atama.

Uzantı şeması

Aşağıdaki JSON, Key Vault VM uzantısının şemasını gösterir. Şema uygulama seçeneklerini dikkate almadan önce aşağıdaki önemli notları gözden geçirin.

  • Uzantı korumalı ayarlar gerektirmez. Tüm ayarlar genel bilgiler olarak kabul edilir.

  • Gözlemlenen sertifika URL'leri biçiminde https://myVaultName.vault.azure.net/secrets/myCertNameolmalıdır.

    Yol, özel anahtar da dahil olmak üzere tam sertifikayı döndürdüğünden, ancak /certificates yol döndürmediğinden bu form tercih edilir/secrets. Sertifikalar hakkında daha fazla bilgi için bkz . Azure Key Vault anahtarları, gizli diziler ve sertifikalara genel bakış.

  • özelliği, kullanıcı tarafından atanan kimliklere sahip VM'ler için gereklidir.authenticationSettings

    Bu özellik, Key Vault kimlik doğrulaması için kullanılacak kimliği belirtir. Birden çok kimlik içeren bir VM uzantısıyla ilgili sorunları önlemek için bu özelliği sistem tarafından atanan kimlikle tanımlayın.

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

Özellik değerleri

JSON şeması aşağıdaki özellikleri içerir.

Veri Akışı Adı Değer/Örnek Veri türü
apiVersion 2022-08-01 tarih
publisher Microsoft.Azure.KeyVault Dize
type KeyVaultForWindows Dize
typeHandlerVersion "3.0" Dize
pollingIntervalInS "3600" Dize
linkOnRenewal (isteğe bağlı) true boolean
requireInitialSync (isteğe bağlı) yanlış boolean
observedCertificates [{...}, {...}] dize dizisi
observedCertificates/url "https://myvault.vault.azure.net/secrets/mycertificate" Dize
observedCertificates/certificateStoreName MY Dize
observedCertificates/certificateStoreLocation LocalMachine veya CurrentUser (büyük/küçük harfe duyarlı) Dize
observedCertificates/keyExportable (isteğe bağlı) yanlış boolean
observedCertificates/accounts (isteğe bağlı) ["Ağ Hizmeti", "Yerel Hizmet"] dize dizisi
msiEndpoint "http://169.254.169.254/metadata/identity/oauth2/token" Dize
msiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619 Dize

Şablon dağıtımı

Azure VM uzantıları Azure Resource Manager (ARM) şablonlarıyla dağıtılabilir. Şablonlar, sertifikaların dağıtım sonrası yenilenmesini gerektiren bir veya daha fazla sanal makine dağıtılırken idealdir. Uzantı tek tek VM'lere veya Sanal Makine Ölçek Kümeleri örneklerine dağıtılabilir. Şema ve yapılandırma her iki şablon türü için de ortaktır.

Anahtar kasası uzantısının JSON yapılandırması VM veya Sanal Makine Ölçek Kümeleri şablonunun içine yerleştirilmiştir. Bir VM kaynak uzantısı için yapılandırma, sanal makine nesnesinin "resources": [] altında iç içe yerleştirilmiştir. Sanal Makine Ölçek Kümeleri örnek uzantısı için yapılandırma nesnenin "virtualMachineProfile":"extensionProfile":{"extensions" :[] altına iç içe yerleştirilmiştir.

Aşağıdaki JSON kod parçacıkları, Key Vault VM uzantısının ARM şablonu dağıtımı için örnek ayarlar sağlar.

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

Uzantı bağımlılığı sıralama

Uzantı bağımlılık sıralamasını desteklemek için Key Vault VM uzantısını etkinleştirebilirsiniz. Varsayılan olarak, Key Vault VM uzantısı yoklama başlar başlamaz başarılı bir başlangıç bildirir. Ancak, uzantıyı başarılı bir başlangıcı yalnızca uzantı tüm sertifikaları indirip yükledikten sonra bildirecek şekilde yapılandırabilirsiniz.

Başlamadan önce tüm sertifikaların yüklenmesini gerektiren diğer uzantıları kullanırsanız, Key Vault VM uzantısında uzantı bağımlılığı sıralamasını etkinleştirebilirsiniz. Bu özellik, diğer uzantıların Key Vault VM uzantısına bağımlılık bildirmesine olanak tanır.

Tüm bağımlı sertifikalar yüklenene kadar diğer uzantıların başlatılmasını önlemek için bu özelliği kullanabilirsiniz. Özellik etkinleştirildiğinde, Key Vault VM uzantısı sertifikaların indirilip yüklenmesini süresiz olarak yeniden dener ve tüm sertifikalar başarıyla yüklenene kadar Geçiş durumunda kalır. Tüm sertifikalar mevcut olduktan sonra Key Vault VM uzantısı başarılı bir başlangıç bildirir.

Key Vault VM uzantısında uzantı bağımlılığı sıralama özelliğini etkinleştirmek için özelliğini ayarlayın secretsManagementSettings :

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

Uzantılar arasında bağımlılıkları ayarlama hakkında daha fazla bilgi için bkz. Sanal Makine Ölçek Kümeleri'de sıralı uzantı sağlama.

Önemli

Uzantı bağımlılığı sıralama özelliği, sistem tarafından atanan bir kimlik oluşturan ve key vault erişim ilkesini bu kimlikle güncelleştiren arm şablonuyla uyumlu değildir. Bu senaryoda bu özelliği kullanmaya çalışırsanız, Key Vault erişim ilkesi tüm uzantılar başlayana kadar güncelleştirilemediğinden bir kilitlenme oluşur. Bunun yerine, tek kullanıcı tarafından atanan bir MSI kimliği kullanın ve dağıtmadan önce anahtar kasalarınızı bu kimlikle önceden ACL'ye ekleyin.

Azure PowerShell dağıtımı

Azure Key Vault VM uzantısı Azure PowerShell ile dağıtılabilir. Key Vault VM uzantısı ayarlarını bir JSON dosyasına (settings.json) kaydedin.

Aşağıdaki JSON kod parçacıkları, PowerShell ile Key Vault VM uzantısını dağıtmak için örnek ayarlar sağlar.

{   
   "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'de dağıtma

# 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

Sanal Makine Ölçek Kümeleri örneğinde dağıtma

# 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 dağıtımı

Azure Key Vault VM uzantısı, Azure CLI kullanılarak dağıtılabilir. Key Vault VM uzantısı ayarlarını bir JSON dosyasına (settings.json) kaydedin.

Aşağıdaki JSON kod parçacıkları, Azure CLI ile Key Vault VM uzantısını dağıtmak için örnek ayarlar sağlar.

   {   
        "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'de dağıtma

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

Sanal Makine Ölçek Kümeleri örneğinde dağıtma

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

Sorunları giderme

Dağıtım sorunlarını gidermeye yönelik bazı öneriler aşağıdadır.

Sık sorulan soruları denetleme

Gözlemlenen sertifika sayısıyla ilgili bir sınır var mı?

Hayır Key Vault VM uzantısı gözlemlenen sertifika sayısını (observedCertificates) sınırlamaz.

Hesap belirtilmediğinde varsayılan izin nedir?

Varsayılan olarak, Yöneticiler ve SYSTEM Tam Denetim alır.

Sertifika anahtarının CAPI1 mi yoksa CNG mi olduğunu nasıl belirlersiniz?

Uzantı, PFXImportCertStore API'sinin varsayılan davranışına dayanır. Varsayılan olarak, sertifikanın CAPI1 ile eşleşen bir Sağlayıcı Adı özniteliği varsa, sertifika CAPI1 API'leri kullanılarak içeri aktarılır. Aksi takdirde, sertifika CNG API'leri kullanılarak içeri aktarılır.

Uzantı sertifika otomatik olarak yeniden bağlamayı destekliyor mu?

Evet, Azure Key Vault VM uzantısı sertifika otomatik yeniden bağlamayı destekler. Key Vault VM uzantısı, özellik true olarak ayarlandığında sertifika yenilemesinde S kanalı bağlamasını linkOnRenewal destekler.

IIS için, IIS'de sertifika yenilemelerinin otomatik olarak yeniden bağlamasını etkinleştirerek otomatik yeniden bağlamayı yapılandırabilirsiniz. Azure Key Vault VM uzantısı, eşleşen san içeren bir sertifika yüklendiğinde Sertifika Yaşam Döngüsü Bildirimleri oluşturur. IIS, sertifikayı otomatik olarak yeniden bağlamak için bu olayı kullanır. Daha fazla bilgi için bkz . IIS'de Certifcate Rebind

Uzantı durumunu görüntüleme

Azure portalında veya PowerShell veya Azure CLI kullanarak uzantı dağıtımınızın durumunu denetleyin.

Belirli bir VM'nin uzantılarının dağıtım durumunu görmek için aşağıdaki komutları çalıştırın.

  • Azure PowerShell:

    Get-AzVMExtension -ResourceGroupName <myResourceGroup> -VMName <myVM> -Name <myExtensionName>

  • The Azure CLI:

    az vm get-instance-view --resource-group <myResourceGroup> --name <myVM> --query "instanceView.extensions"

Günlükleri ve yapılandırmayı gözden geçirme

Key Vault VM uzantısı günlükleri yalnızca VM'de yerel olarak bulunur. Sorun gidermeye yardımcı olması için günlük ayrıntılarını gözden geçirin.

Günlük dosyası Açıklama
C:\WindowsAzure\Logs\WaAppAgent.log' Uzantıda güncelleştirmelerin ne zaman gerçekleştiğini gösterir.
C:\WindowsAzure\Logs\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<en son sürüm>\ Sertifika indirme durumunu gösterir. İndirme konumu her zaman Windows bilgisayarın MY mağazasıdır (certlm.msc).
C:\Packages\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<en son sürüm>\RuntimeSettings\ Key Vault VM Uzantısı hizmet günlükleri, akvvm_service hizmetinin durumunu gösterir.
C:\Packages\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<en son sürüm>\Status\ Key Vault VM Uzantısı hizmeti için yapılandırma ve ikili dosyalar.

Destek alın

Dağıtım sorunlarını çözmenize yardımcı olacak diğer bazı seçenekler şunlardır:

  • Yardım için Soru-Cevap ve Stack Overflow forumlarında Azure uzmanlarına başvurun.

  • Sitede bir yanıt bulamazsanız Microsoft'tan veya topluluğun diğer üyelerinden gelen girişler için bir soru gönderebilirsiniz.

  • ayrıca İletişim Microsoft Desteği. Azure desteği kullanma hakkında bilgi için Azure desteği SSS bölümünü okuyun.