Windows용 Azure Key Vault 가상 머신 확장

Azure Key Vault VM(가상 머신) 확장은 Azure Key Vault에 저장된 인증서의 자동 새로 고침을 제공합니다. 확장은 키 보관소에 저장된 관찰된 인증서 목록을 모니터링합니다. 변경 내용이 감지되면 확장은 해당 인증서를 검색하고 설치합니다. 이 문서에서는 Windows용 Key Vault VM 확장에 대해 지원되는 플랫폼, 구성 및 배포 옵션에 대해 설명합니다.

운영 체제

Key Vault VM 확장은 Windows Server 2019 이상을 지원합니다. Key Vault VM 확장은 사용자 지정 로컬 VM에서도 지원됩니다. Windows Server 2019 코어 설치를 사용하여 Azure에서 사용하기 위해 VM을 업로드하고 특수 이미지로 변환해야 합니다.

지원되는 인증서

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

• PKCS #12
• PEM

기능

Windows 버전 3.0용 Key Vault VM 확장은 다음을 지원합니다.

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

필수 조건

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

• 인증서가 있는 Azure Key Vault 인스턴스입니다. 자세한 내용은 Azure 포털을 사용하여 키 자격 증명 모음을 만드는 방법을 참조하세요.

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

• Key Vault 비밀 사용자 역할은 VM 및 Azure Virtual Machine Scale Sets 관리 ID에 대한 Key Vault 범위 수준에서 할당되어야 합니다. 이 역할은 인증서의 비밀 부분을 검색합니다. 자세한 내용은 다음 문서를 참조하세요.

  • Azure Key Vault의 인증
  • Azure Key Vault에서 Azure RBAC 비밀, 키 및 인증서 권한 사용
  • 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]"
  }
  

확장 스키마

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

속성 값

JSON 스키마에는 다음 속성이 포함됩니다.

템플릿 배포

ARM(Azure Resource Manager) 템플릿을 사용하여 Azure VM 확장을 배포할 수 있습니다. 배포 후에 인증서를 새로 고칠 필요가 있는 하나 이상의 가상 머신을 배포하는 경우 템플릿을 사용하는 것이 좋습니다. 확장은 개별 VM 또는 Virtual Machine Scale Sets 인스턴스에 배포할 수 있습니다. 스키마와 구성은 두 템플릿 형식 모두에 공통적으로 적용됩니다.

키 자격 증명 모음 확장에 대한 JSON 구성은 VM 또는 가상 머신 스케일 세트 템플릿 내에 중첩되어 있습니다. 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,
   ...
}

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

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의 기본 동작을 사용합니다. 기본적으로 인증서에 CAPI1과 일치하는 공급자 이름 특성이 있는 경우 CAPI1 API를 사용하여 인증서를 가져옵니다. 그렇지 않으면 CNG API를 사용하여 인증서를 가져옵니다.

확장에서 인증서 자동 바인딩을 지원하나요?

예, Azure Key Vault VM 확장은 인증서 자동 바인딩을 지원합니다. Key Vault VM 확장은 속성이 true로 설정된 경우 인증서 갱신 시 S 채널 바인딩을 linkOnRenewal 지원합니다.

IIS의 경우 IIS에서 인증서 갱신의 자동 다시 바인딩을 사용하도록 설정하여 자동 바인딩을 구성할 수 있습니다. 일치하는 SAN이 있는 인증서가 설치될 때 Azure Key Vault VM 확장은 인증서 수명 주기 알림을 생성합니다. IIS는 이 이벤트를 사용하여 인증서를 자동으로 다시 바인딩합니다. 자세한 내용은 IIS의 Certifcate Rebind를 참조하세요.

확장 상태 보기

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에 로컬로만 존재합니다. 문제 해결에 도움이 되도록 로그 세부 정보를 검토합니다.

Windows에서 인증서 설치

Windows용 Key Vault VM 확장은 Windows 인증서 저장소에 인증서를 설치합니다. Key Vault에서 인증서를 다운로드하면 확장은 다음과 같습니다.

1. 있는 중간 인증서 수에 관계없이 모든 중간 및 리프 인증서를 설치합니다. 루트 인증서는 루트 설치를 수행할 권한이 없으므로 설치되지 않습니다. 루트 인증서가 시스템에서 신뢰할 수 있도록 하는 것은 서비스 소유자의 책임입니다.
   • 리프 인증서는 지정된 인증서 저장소() 및 위치(certificateStoreName)에certificateStoreLocation 설치됩니다.
   • 중간 CA 인증서는 중간 인증 기관 저장소에 설치됩니다.
2. 지정된 인증서 저장소() 및 위치(certificateStoreName)에 인증서를certificateStoreLocation 배치합니다.
3. 구성에 지정된 사항에 따라 프라이빗 키에 accounts 적절한 권한을 적용합니다.
4. 인증서를 linkOnRenewal 갱신할 때 IIS와 같은 애플리케이션의 인증서 바인딩이 자동으로 업데이트되도록 속성(사용하도록 설정된 경우)을 설정합니다.

기본 인증서 저장소

지정하지 않으면 인증서는 기본적으로 다음 위치에 설치됩니다.

• 스토어 이름: MY(개인)
• 저장소 위치: LocalMachine

인증서 액세스 제어

기본적으로 관리자와 SYSTEM은 설치된 인증서에 대한 모든 권한을 받습니다. 인증서 구성에서 배열을 accounts 사용하여 액세스를 사용자 지정할 수 있습니다.

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

이렇게 하면 지정된 계정에 대한 읽기 액세스 권한이 부여되므로 해당 ID에서 실행되는 애플리케이션에서 인증서를 사용할 수 있습니다.

인증서 갱신

Key Vault에서 인증서가 갱신되면 확장이 자동으로 다음을 수행합니다.

1. 새 인증서 버전을 다운로드합니다.
2. 구성된 인증서 저장소에 설치합니다.
3. 사용하도록 설정된 경우 linkOnRenewal 기능을 통해 기존 바인딩을 유지 관리합니다.

인증서 수명 주기 관리

인증서 수명 주기 알림을 지원하는 IIS와 같은 애플리케이션의 경우 확장은 일치하는 SAN(주체 대체 이름)이 있는 인증서가 설치될 때 이벤트를 생성하여 서비스 중단 없이 자동 다시 바인딩을 허용합니다.

지원 받기

배포 문제를 해결하는 데 도움이 되는 몇 가지 다른 옵션은 다음과 같습니다.

• 도움이 필요하면 Q&A 및 Stack Overflow 포럼에서 Azure 전문가에게 문의하세요.

• 사이트에서 답변을 찾을 수 없는 경우 Microsoft 또는 커뮤니티의 다른 구성원의 입력에 대한 질문을 게시할 수 있습니다.

• Microsoft 지원에 문의할 수도 있습니다. Azure 지원 사용에 대한 자세한 내용은 Azure 지원 FAQ를 참조하세요.