Rozszerzenie maszyny wirtualnej usługi Azure Key Vault dla systemu Windows

  • Artykuł

Rozszerzenie maszyny wirtualnej usługi Azure Key Vault zapewnia automatyczne odświeżanie certyfikatów przechowywanych w magazynie kluczy platformy Azure. Rozszerzenie monitoruje listę obserwowanych certyfikatów przechowywanych w magazynach kluczy. Po wykryciu zmiany rozszerzenie pobiera i instaluje odpowiednie certyfikaty. W tym artykule opisano obsługiwane platformy, konfiguracje i opcje wdrażania rozszerzenia maszyny wirtualnej usługi Key Vault dla systemu Windows.

Systemy operacyjne

Rozszerzenie maszyny wirtualnej usługi Key Vault obsługuje następujące wersje systemu Windows:

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

Rozszerzenie maszyny wirtualnej usługi Key Vault jest również obsługiwane na niestandardowej lokalnej maszynie wirtualnej. Maszyna wirtualna powinna zostać przekazana i przekonwertowana na wyspecjalizowany obraz do użycia na platformie Azure przy użyciu instalacji podstawowej systemu Windows Server 2019.

Obsługiwane certyfikaty

Rozszerzenie maszyny wirtualnej usługi Key Vault obsługuje następujące typy zawartości certyfikatów:

  • PKCS #12
  • PEM

Uwaga

Rozszerzenie maszyny wirtualnej usługi Key Vault pobiera wszystkie certyfikaty do magazynu certyfikatów systemu Windows lub do lokalizacji określonej we właściwości w certificateStoreLocation ustawieniach rozszerzenia maszyny wirtualnej.

Aktualizacje w wersji 3.0 lub nowszej

Wersja 3.0 rozszerzenia maszyny wirtualnej usługi Key Vault dla systemu Windows dodaje obsługę następujących funkcji:

  • Dodawanie uprawnień listy ACL do pobranych certyfikatów
  • Włączanie konfiguracji magazynu certyfikatów na certyfikat
  • Eksportowanie kluczy prywatnych
  • Obsługa ponownego powiązania certyfikatów usług IIS

Wymagania wstępne

Zapoznaj się z następującymi wymaganiami wstępnymi dotyczącymi używania rozszerzenia maszyny wirtualnej usługi Key Vault dla systemu Windows:

Uwaga

Stary model uprawnień zasad dostępu może również służyć do zapewnienia dostępu do maszyn wirtualnych i zestawów skalowania maszyn wirtualnych. Ta metoda wymaga zasad z uprawnieniami pobierania i wyświetlania listy wpisów tajnych. Aby uzyskać więcej informacji, zobacz Przypisywanie zasad dostępu do usługi Key Vault.

Schemat rozszerzenia

Poniższy kod JSON przedstawia schemat rozszerzenia maszyny wirtualnej usługi Key Vault. Przed rozważenie opcji implementacji schematu zapoznaj się z następującymi ważnymi uwagami.

  • Rozszerzenie nie wymaga ustawień chronionych. Wszystkie ustawienia są uznawane za informacje publiczne.

  • Obserwowane adresy URL certyfikatów powinny mieć postać https://myVaultName.vault.azure.net/secrets/myCertName.

    Ten formularz jest preferowany, ponieważ /secrets ścieżka zwraca pełny certyfikat, w tym klucz prywatny, ale /certificates ścieżka nie. Aby uzyskać więcej informacji na temat certyfikatów, zobacz Omówienie kluczy, wpisów tajnych i certyfikatów usługi Azure Key Vault.

  • Właściwość jest wymaganaauthenticationSettings dla maszyn wirtualnych z dowolnymi tożsamościami przypisanymi przez użytkownika.

    Ta właściwość określa tożsamość, która ma być używana do uwierzytelniania w usłudze Key Vault. Zdefiniuj tę właściwość przy użyciu tożsamości przypisanej przez system, aby uniknąć problemów z rozszerzeniem maszyny wirtualnej z wieloma tożsamościami.

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

Wartości właściwości

Schemat JSON zawiera następujące właściwości.

Nazwisko Wartość/przykład Typ danych
apiVersion 2022-08-01 data
publisher Microsoft.Azure.KeyVault string
type KeyVaultForWindows string
typeHandlerVersion "3.0" string
pollingIntervalInS "3600" string
linkOnRenewal (opcjonalny) prawda boolean
requireInitialSync (opcjonalny) fałsz boolean
observedCertificates [{...}, {...}] tablica ciągów
observedCertificates/url "https://myvault.vault.azure.net/secrets/mycertificate" string
observedCertificates/certificateStoreName MY string
observedCertificates/certificateStoreLocation LocalMachine lub CurrentUser (uwzględniana wielkość liter) string
observedCertificates/keyExportable (opcjonalny) fałsz boolean
observedCertificates/accounts (opcjonalny) ["Usługa sieciowa", "Usługa lokalna"] tablica ciągów
msiEndpoint "http://169.254.169.254/metadata/identity/oauth2/token" string
msiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619 string

Wdrażanie na podstawie szablonu

Rozszerzenia maszyn wirtualnych platformy Azure można wdrażać za pomocą szablonów usługi Azure Resource Manager (ARM). Szablony są idealne podczas wdrażania co najmniej jednej maszyny wirtualnej, które wymagają po wdrożeniu odświeżania certyfikatów. Rozszerzenie można wdrożyć na poszczególnych maszynach wirtualnych lub wystąpieniach usługi Virtual Machine Scale Sets. Schemat i konfiguracja są wspólne dla obu typów szablonów.

Konfiguracja JSON rozszerzenia magazynu kluczy jest zagnieżdżona wewnątrz maszyny wirtualnej lub szablonu zestawów skalowania maszyn wirtualnych. W przypadku rozszerzenia zasobu maszyny wirtualnej konfiguracja jest zagnieżdżona pod obiektem "resources": [] maszyny wirtualnej. W przypadku rozszerzenia wystąpienia usługi Virtual Machine Scale Sets konfiguracja jest zagnieżdżona pod obiektem "virtualMachineProfile":"extensionProfile":{"extensions" :[] .

Poniższe fragmenty kodu JSON zawierają przykładowe ustawienia wdrożenia szablonu usługi ARM rozszerzenia maszyny wirtualnej usługi Key Vault.

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

Kolejność zależności rozszerzenia

Rozszerzenie maszyny wirtualnej usługi Key Vault umożliwia obsługę kolejności zależności rozszerzeń. Domyślnie rozszerzenie maszyny wirtualnej usługi Key Vault zgłasza pomyślne rozpoczęcie od razu po rozpoczęciu sondowania. Można jednak skonfigurować rozszerzenie w celu raportowania pomyślnego uruchomienia dopiero po pobraniu i zainstalowaniu wszystkich certyfikatów przez rozszerzenie.

Jeśli używasz innych rozszerzeń, które wymagają instalacji wszystkich certyfikatów przed rozpoczęciem, możesz włączyć kolejność zależności rozszerzenia w rozszerzeniu maszyny wirtualnej usługi Key Vault. Ta funkcja umożliwia innym rozszerzeń deklarowanie zależności od rozszerzenia maszyny wirtualnej usługi Key Vault.

Tej funkcji można użyć, aby zapobiec uruchamianiu innych rozszerzeń do momentu zainstalowania wszystkich certyfikatów zależnych. Po włączeniu tej funkcji rozszerzenie maszyny wirtualnej usługi Key Vault ponawia próbę pobierania i instalowania certyfikatów na czas nieokreślony i pozostaje w stanie Przejściowym , dopóki wszystkie certyfikaty nie zostaną pomyślnie zainstalowane. Po wystąpieniu wszystkich certyfikatów rozszerzenie maszyny wirtualnej usługi Key Vault zgłasza pomyślny start.

Aby włączyć funkcję porządkowania zależności rozszerzenia w rozszerzeniu maszyny wirtualnej usługi Key Vault, ustaw secretsManagementSettings właściwość:

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

Aby uzyskać więcej informacji na temat konfigurowania zależności między rozszerzeniami, zobacz Aprowizowanie rozszerzeń sekwencji w zestawach skalowania maszyn wirtualnych.

Ważne

Funkcja porządkowania zależności rozszerzenia nie jest zgodna z szablonem usługi ARM, który tworzy tożsamość przypisaną przez system i aktualizuje zasady dostępu usługi Key Vault przy użyciu tej tożsamości. Jeśli spróbujesz użyć funkcji w tym scenariuszu, występuje zakleszczenie, ponieważ zasady dostępu usługi Key Vault nie mogą być aktualizowane dopiero po uruchomieniu wszystkich rozszerzeń. Zamiast tego należy użyć tożsamości tożsamości usługi zarządzanej przypisanej przez jednego użytkownika i wstępnie listy ACL magazynów kluczy z tej tożsamości przed wdrożeniem.

Wdrażanie programu Azure PowerShell

Rozszerzenie maszyny wirtualnej usługi Azure Key Vault można wdrożyć za pomocą programu Azure PowerShell. Zapisz ustawienia rozszerzenia maszyny wirtualnej usługi Key Vault w pliku JSON (settings.json).

Poniższe fragmenty kodu JSON zawierają przykładowe ustawienia wdrażania rozszerzenia maszyny wirtualnej usługi Key Vault za pomocą programu PowerShell.

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

Wdrażanie na maszynie wirtualnej

# 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

Wdrażanie w wystąpieniu usługi 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

Wdrożenie za pomocą interfejsu wiersza polecenia platformy Azure

Rozszerzenie maszyny wirtualnej usługi Azure Key Vault można wdrożyć przy użyciu interfejsu wiersza polecenia platformy Azure. Zapisz ustawienia rozszerzenia maszyny wirtualnej usługi Key Vault w pliku JSON (settings.json).

Poniższe fragmenty kodu JSON zawierają przykładowe ustawienia wdrażania rozszerzenia maszyny wirtualnej usługi Key Vault przy użyciu interfejsu wiersza polecenia platformy Azure.

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

Wdrażanie na maszynie wirtualnej

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

Wdrażanie w wystąpieniu usługi 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"

Rozwiązywanie problemów

Poniżej przedstawiono kilka sugestii dotyczących rozwiązywania problemów z wdrażaniem.

Sprawdź często zadawane pytania

Czy istnieje limit liczby obserwowanych certyfikatów?

L.p. Rozszerzenie maszyny wirtualnej usługi Key Vault nie ogranicza liczby obserwowanych certyfikatów (observedCertificates).

Jakie jest domyślne uprawnienie, jeśli nie określono konta?

Domyślnie Administracja istratory i SYSTEM otrzymują pełną kontrolę.

Jak określić, czy klucz certyfikatu to CAPI1 czy CNG?

Rozszerzenie opiera się na domyślnym zachowaniu interfejsu API PFXImportCertStore. Domyślnie jeśli certyfikat ma atrybut Nazwa dostawcy, który jest zgodny z interfejsem CAPI1, certyfikat jest importowany przy użyciu interfejsów API CAPI1. W przeciwnym razie certyfikat jest importowany przy użyciu interfejsów API CNG.

Czy rozszerzenie obsługuje automatyczne łączenie certyfikatów?

Tak, rozszerzenie maszyny wirtualnej usługi Azure Key Vault obsługuje automatyczne łączenie certyfikatów. Rozszerzenie maszyny wirtualnej usługi Key Vault obsługuje powiązanie kanału S podczas odnawiania certyfikatu, gdy linkOnRenewal właściwość jest ustawiona na wartość true.

W przypadku usług IIS można skonfigurować automatyczne ponowne powiązanie, włączając automatyczne ponowne powiązanie odnawiania certyfikatów w usługach IIS. Rozszerzenie maszyny wirtualnej usługi Azure Key Vault generuje powiadomienia o cyklu życia certyfikatu po zainstalowaniu certyfikatu z pasującą siecią SAN. Usługi IIS używają tego zdarzenia do automatycznego powiązania certyfikatu. Aby uzyskać więcej informacji, zobacz Certifcate Rebind w usługach IIS

Wyświetlanie stanu rozszerzenia

Sprawdź stan wdrożenia rozszerzenia w witrynie Azure Portal lub przy użyciu programu PowerShell lub interfejsu wiersza polecenia platformy Azure.

Aby wyświetlić stan wdrożenia rozszerzeń dla danej maszyny wirtualnej, uruchom następujące polecenia.

  • Azure PowerShell:

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

  • Interfejs wiersza polecenia platformy Azure:

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

Przeglądanie dzienników i konfiguracji

Dzienniki rozszerzenia maszyny wirtualnej usługi Key Vault istnieją tylko lokalnie na maszynie wirtualnej. Przejrzyj szczegóły dziennika, aby uzyskać pomoc dotyczącą rozwiązywania problemów.

Plik dziennika opis
C:\WindowsAzure\Logs\WaAppAgent.log' Pokazuje, kiedy występują aktualizacje rozszerzenia.
C:\WindowsAzure\Logs\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<najnowsza wersja>\ Pokazuje stan pobierania certyfikatu. Lokalizacja pobierania to zawsze mój sklep (certlm.msc) komputera z systemem Windows.
C:\Packages\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<najnowsza wersja>\Runtime Ustawienia\ Dzienniki usługi rozszerzenia maszyny wirtualnej usługi Key Vault pokazują stan usługi akvvm_service.
C:\Packages\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<najnowsza wersja>\Status\ Konfiguracja i pliki binarne dla usługi rozszerzenia maszyny wirtualnej usługi Key Vault.

Uzyskaj pomoc techniczną

Poniżej przedstawiono kilka innych opcji, które ułatwiają rozwiązywanie problemów z wdrażaniem:

  • Aby uzyskać pomoc, skontaktuj się z ekspertami platformy Azure na forach Q&A i Stack Overflow.

  • Jeśli nie znajdziesz odpowiedzi w witrynie, możesz opublikować pytanie dotyczące danych wejściowych od firmy Microsoft lub innych członków społeczności.

  • Możesz również skontaktować się z pomoc techniczna firmy Microsoft. Aby uzyskać informacje na temat korzystania z pomoc techniczna platformy Azure, przeczytaj często zadawane pytania dotyczące pomoc techniczna platformy Azure.