ملحق الجهاز الظاهري ل Azure Key Vault لنظام التشغيل Windows

  • مقالة

يوفر ملحق الجهاز الظاهري ل Azure Key Vault (VM) تحديثا تلقائيا للشهادات المخزنة في مخزن مفاتيح Azure. يراقب الملحق قائمة بالشهادات التي تمت ملاحظتها المخزنة في خزائن المفاتيح. عندما يكتشف تغييرا، يسترد الملحق الشهادات المقابلة ويثبتها. توضح هذه المقالة الأنظمة الأساسية والتكوينات وخيارات النشر المدعومة لملحق Key Vault VM لنظام التشغيل Windows.

أنظمة التشغيل

يدعم ملحق Key Vault VM الإصدارات التالية من Windows:

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

يتم أيضا دعم ملحق Key Vault VM على جهاز ظاهري محلي مخصص. يجب تحميل الجهاز الظاهري وتحويله إلى صورة متخصصة للاستخدام في Azure باستخدام التثبيت الأساسي ل Windows Server 2019.

الشهادات المعتمدة

يدعم ملحق Key Vault VM أنواع محتوى الشهادة التالية:

  • PKCS #12
  • PEM

إشعار

يقوم ملحق Key Vault VM بتنزيل جميع الشهادات إلى مخزن شهادات Windows أو إلى الموقع المحدد في الخاصية certificateStoreLocation في إعدادات ملحق الجهاز الظاهري.

التحديثات في الإصدار 3.0+

يضيف الإصدار 3.0 من ملحق Key Vault VM لنظام التشغيل Windows دعما للميزات التالية:

  • إضافة أذونات ACL إلى الشهادات التي تم تنزيلها
  • تمكين تكوين مخزن الشهادات لكل شهادة
  • تصدير مفاتيح خاصة
  • دعم إعادة ربط شهادة IIS

المتطلبات الأساسية

راجع المتطلبات الأساسية التالية لاستخدام ملحق Key Vault VM لنظام التشغيل Windows:

إشعار

يمكن أيضا استخدام نموذج إذن نهج الوصول القديم لتوفير الوصول إلى الأجهزة الظاهرية ومجموعات مقياس الجهاز الظاهري. يتطلب هذا الأسلوب نهج مع الحصول على أذونات الحصول على البيانات السرية وإدراجها. لمزيد من المعلومات، راجع تعيين نهج وصول Key Vault.

مخطط الملحق

يعرض JSON التالي المخطط الخاص بملحق الجهاز الظاهري لـ Key Vault. قبل النظر في خيارات تنفيذ المخطط، راجع الملاحظات المهمة التالية.

  • لا يتطلب الملحق إعدادات محمية. تعتبر جميع الإعدادات معلومات عامة.

  • يجب أن تكون عناوين URL للشهادات التي تمت ملاحظتها من النموذج https://myVaultName.vault.azure.net/secrets/myCertName.

    يفضل هذا النموذج لأن /secrets المسار يرجع الشهادة الكاملة، بما في ذلك المفتاح الخاص، ولكن /certificates المسار لا يرجعها. لمزيد من المعلومات حول الشهادات، راجع نظرة عامة على مفاتيح Azure Key Vault والأسرار والشهادات.

  • الخاصية authenticationSettingsمطلوبة للأجهزة الظاهرية مع أي هويات معينة من قبل المستخدم.

    تحدد هذه الخاصية الهوية التي يجب استخدامها للمصادقة على Key Vault. حدد هذه الخاصية بهوية معينة من قبل النظام لتجنب المشكلات المتعلقة بملحق الجهاز الظاهري بهويات متعددة.

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

قيم Property

يتضمن مخطط JSON الخصائص التالية.

الاسم القيمة/المثال نوع البيانات
apiVersion 2022-08-01 date
publisher Microsoft.Azure.KeyVault سلسلة
type KeyVaultForWindows سلسلة
typeHandlerVersion "3.0" سلسلة
pollingIntervalInS "3600" سلسلة
linkOnRenewal (اختياري) صحيح boolean
requireInitialSync (اختياري) true boolean
observedCertificates [{...}, {...}] صفيف سلسلة
observedCertificates/url "https://myvault.vault.azure.net/secrets/mycertificate"؛ سلسلة
observedCertificates/certificateStoreName MY سلسلة
observedCertificates/certificateStoreLocation LocalMachine أو CurrentUser (حساس لحالة الأحرف) سلسلة
observedCertificates/keyExportable (اختياري) true boolean
observedCertificates/accounts (اختياري) ["خدمة الشبكة"، "الخدمة المحلية"] صفيف سلسلة
msiEndpoint "http://169.254.169.254/metadata/identity/oauth2/token"؛ سلسلة
msiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619 سلسلة

توزيع قالب

يمكن نشر ملحقات Azure VM باستخدام قوالب Azure Resource Manager (ARM). تعد القوالب مثالية عند توزيع جهاز ظاهري واحد أو أكثر يشترط تحديث الشهادات بعد التوزيع. يمكن نشر الملحق إلى أجهزة ظاهرية فردية أو مثيلات مجموعات مقياس الجهاز الظاهري. يشيع المخطط والتكوين في كلا النوعين من القوالب.

يتم تداخل تكوين JSON لملحق key vault داخل قالب VM أو Virtual Machine Scale Sets. بالنسبة لملحق مورد الجهاز الظاهري، يتم تداخل التكوين ضمن "resources": [] كائن الجهاز الظاهري. بالنسبة لملحق مثيل مجموعات مقياس الجهاز الظاهري، يتم تداخل التكوين ضمن "virtualMachineProfile":"extensionProfile":{"extensions" :[] الكائن .

توفر القصاصات البرمجية JSON التالية أمثلة لإعدادات نشر قالب ARM لملحق Key Vault VM.

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

لمزيد من المعلومات حول كيفية إعداد التبعيات بين الملحقات، راجع توفير ملحق التسلسل في مجموعات مقياس الجهاز الظاهري.

هام

لا تتوافق ميزة ترتيب تبعية الملحق مع قالب ARM الذي ينشئ هوية معينة من قبل النظام ويحدث نهج الوصول إلى Key Vault بهذه الهوية. إذا حاولت استخدام الميزة في هذا السيناريو، يحدث توقف تام لأن نهج الوصول إلى Key Vault لا يمكن تحديثه إلا بعد بدء جميع الملحقات. بدلا من ذلك، استخدم هوية MSI المعينة من قبل مستخدم واحد و ما قبل ACL خزائن المفاتيح الخاصة بك مع هذه الهوية قبل النشر.

توزيع Azure PowerShell

يمكن نشر ملحق Azure Key Vault VM باستخدام Azure PowerShell. حفظ إعدادات ملحق Key Vault VM إلى ملف JSON (settings.json).

توفر القصاصات البرمجية JSON التالية أمثلة لإعدادات نشر ملحق Key Vault VM مع 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"
   }      
}

النشر على جهاز ظاهري

# 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

النشر على مثيل مجموعات مقياس الجهاز الظاهري

# 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 التالية أمثلة لإعدادات لنشر ملحق Key Vault VM مع Azure CLI.

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

النشر على جهاز ظاهري

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

النشر على مثيل مجموعات مقياس الجهاز الظاهري

# 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).

ما هو الإذن الافتراضي عندما لا يتم تحديد حساب؟

بشكل افتراضي، يتلقى مسؤول istrators وSTEM التحكم الكامل.

كيف يمكنك تحديد ما إذا كان مفتاح الشهادة هو CAPI1 أو CNG؟

يعتمد الملحق على السلوك الافتراضي لواجهة برمجة تطبيقات PFXImportCertStore. بشكل افتراضي، إذا كانت الشهادة تحتوي على سمة اسم الموفر التي تتطابق مع CAPI1، فسيتم استيراد الشهادة باستخدام واجهات برمجة تطبيقات CAPI1. وإلا، يتم استيراد الشهادة باستخدام واجهات برمجة تطبيقات CNG.

هل يدعم الملحق إعادة ربط الشهادة تلقائيا؟

نعم، يدعم ملحق Azure Key Vault VM إعادة ربط الشهادة تلقائيا. يدعم ملحق Key Vault VM ربط قناة S عند تجديد الشهادة عند تعيين الخاصية linkOnRenewal إلى true.

بالنسبة إلى IIS، يمكنك تكوين إعادة ربط تلقائي عن طريق تمكين إعادة ربط تجديد الشهادة تلقائيا في IIS. ينشئ ملحق Azure Key Vault VM إعلامات دورة حياة الشهادة عند تثبيت شهادة مع SAN مطابقة. يستخدم IIS هذا الحدث لإعادة ربط الشهادة تلقائيا. لمزيد من المعلومات، راجع Certifcate Rebind في IIS

عرض حالة الملحق

تحقق من حالة نشر الملحق في مدخل Microsoft Azure، أو باستخدام PowerShell أو Azure CLI.

لمشاهدة حالة نشر الملحقات لجهاز ظاهري معين، قم بتشغيل الأوامر التالية.

  • 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 محليا فقط على الجهاز الظاهري. راجع تفاصيل السجل للمساعدة في استكشاف الأخطاء وإصلاحها.

ملف السجل ‏‏الوصف
C:\WindowsAzure\Logs\WaAppAgent.log' يظهر عند حدوث تحديثات للملحق.
C:\WindowsAzure\Logs\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<most recent version>\ يعرض حالة تنزيل الشهادة. موقع التنزيل هو دائما متجر MY للكمبيوتر Windows (certlm.msc).
C:\Packages\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<أحدث إصدار>\RuntimeSettings\ تعرض سجلات خدمة ملحق الجهاز الظاهري لـ Key Vault حالة الخدمة akvvm_service.
C:\Packages\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<أحدث إصدار>\Status\ التكوين والثنائيات لخدمة ملحق الجهاز الظاهري ل Key Vault.

الحصول على الدعم

فيما يلي بعض الخيارات الأخرى لمساعدتك في حل مشكلات النشر:

  • للحصول على المساعدة، اتصل بخبراء Azure في منتديات Q&A و Stack Overflow.

  • إذا لم تعثر على إجابة على الموقع، فيمكنك نشر سؤال لإدخاله من Microsoft أو أعضاء آخرين في المجتمع.

  • يمكنك أيضا الاتصال بدعم Microsoft. للحصول على معلومات حول استخدام دعم Azure، اقرأ الأسئلة المتداولة حول دعم Azure.