다음을 통해 공유

Windows용 Azure Key Vault 가상 머신 확장

  • 아티클

Azure Key Vault VM(가상 머신) 확장은 Azure 키 자격 증명 모음에 저장된 인증서의 자동 새로 고침을 제공합니다. 확장은 Key Vault에 저장되어 있는 관찰된 인증서 목록을 모니터링합니다. 변경 사항을 감지하면 확장이 검색을 하고 해당 인증서를 설치합니다. 이 문서에서는 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 설치를 사용하여 Azure에서 사용할 수 있도록 VM을 업로드하고 특수 이미지로 변환해야 합니다.

지원되는 인증서

Key Vault VM 확장은 다음 인증서 콘텐츠 형식을 지원합니다.

  • PKCS #12
  • PEM

참고 항목

Key Vault VM 확장은 모든 인증서를 Windows 인증서 저장소 또는 VM 확장 설정의 certificateStoreLocation 속성에 지정된 위치로 다운로드합니다.

버전 3.0 이상에서 업데이트

Windows용 Key Vault VM 확장 버전 3.0은 다음 기능에 대한 지원을 추가합니다.

  • 다운로드한 인증서에 ACL 권한 추가
  • 인증서당 인증서 저장소 구성 사용
  • 프라이빗 키 내보내기
  • IIS 인증서 다시 바인딩 지원

필수 조건

Windows용 Key Vault VM 확장을 사용하기 위한 다음 필수 구성 요소를 검토합니다.

  • 인증서가 있는 Azure Key Vault 인스턴스. 자세한 내용은 Azure Portal을 사용하여 키 자격 증명 모음 만들기를 참조하세요.

  • 할당된 관리 ID가 있는 VM.

  • 키 자격 증명 모음 비밀 사용자 역할은 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에 대한 액세스를 제공할 수도 있습니다. 이 메서드에는 비밀에 대한 가져오기 및 나열 권한이 있는 정책이 필요합니다. 자세한 내용은 Key Vault 액세스 정책 할당을 참조하세요.

확장 스키마

다음 JSON은 Key Vault VM 확장에 대한 스키마를 보여 줍니다. 스키마 구현 옵션을 고려하기 전에 다음 중요한 정보를 검토하세요.

  • 확장 프로그램에는 보호된 설정이 필요하지 않습니다. 모든 설정은 공용 정보로 간주됩니다.

  • 관찰된 인증서 URL은 https://myVaultName.vault.azure.net/secrets/myCertName 형식이어야 합니다.

    /secrets 경로가 프라이빗 키를 포함한 전체 인증서를 반환하지만 /certificates 경로는 그렇지 않기 때문에 이 형식이 기본 설정됩니다. 인증서에 대한 자세한 내용은 Azure Key Vault 키, 비밀 및 인증서 개요를 참조하세요.

  • authenticationSettings 속성은 사용자 할당 ID가 있는 VM에 필요합니다.

    이 속성은 Key Vault에 대한 인증에 사용할 ID를 지정합니다. 여러 ID가 있는 VM 확장의 문제를 방지하려면 시스템 할당 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 날짜
publisher Microsoft.Azure.KeyVault string
type KeyVaultForWindows string
typeHandlerVersion "3.0" string
pollingIntervalInS "3600" string
linkOnRenewal(선택 사항) true 부울 값
requireInitialSync(선택 사항) false 부울 값
observedCertificates [{...}, {...}] 문자열 배열
observedCertificates/url "https://myvault.vault.azure.net/secrets/mycertificate" string
observedCertificates/certificateStoreName MY string
observedCertificates/certificateStoreLocation LocalMachine 또는 CurrentUser(대/소문자 구분) string
observedCertificates/keyExportable(선택 사항) false 부울 값
observedCertificates/accounts(선택 사항) ["Network Service", "Local Service"] 문자열 배열
msiEndpoint "http://169.254.169.254/metadata/identity/oauth2/token" string
msiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619 문자열

템플릿 배포

ARM(Azure Resource Manager) 템플릿을 사용하여 Azure VM 확장을 배포할 수 있습니다. 배포 후에 인증서를 새로 고칠 필요가 있는 하나 이상의 가상 머신을 배포하는 경우 템플릿을 사용하는 것이 좋습니다. 확장은 개별 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,
   ...
}

확장 간에 종속성을 설정하는 방법에 대한 자세한 내용은 Virtual Machine Scale Sets 시퀀스 확장 프로비저닝을 참조하세요.

Important

확장 종속성 순서 지정 기능은 시스템 할당 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).

계정이 지정되지 않은 경우 기본 사용 권한은 무엇인가요?

기본적으로 관리자와 시스템은 모든 권한을 받습니다.

인증서 키가 CAPI1 또는 CNG인지 어떻게 확인합니까?

확장은 PFXImportCertStore API의 기본 동작을 사용합니다. 기본적으로 인증서에 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를 참조하세요.