للحصول على مزيد من المعلومات، راجع استخدام Azure Key Vault لتمرير قيمة المعلمة الآمنة أثناء التوزيع

مقالة
05/07/2024

بدلا من وضع قيمة آمنة (مثل كلمة مرور) مباشرة في ملف Bicep أو ملف المعلمات، يمكنك استرداد القيمة من Azure Key Vault أثناء التوزيع. عندما تتوقع وحدة نمطيةstringمعلمة بمُعدِّلsecure:true، يمكنك استخدام دالة getSecret للحصول على البيانات السرية لخزينة المفتاح. لا يتم عرض القيمة مطلقاً لأنك تشير فقط إلى معرف مخزن المفاتيح الخاص بها.

هام

تركز هذه المقالة على كيفية تمرير قيمة حساسة كمعامل قالب. عندما يتم تمرير السر كمعامل، يمكن أن يوجد مخزن المفاتيح في اشتراك مختلف عن مجموعة الموارد التي تقوم بالنشر إليها.

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

توزيع خزائن المفاتيح والبيانات السرية

للوصول إلى قيمة المفتاح أثناء توزيع Bicep، قم بتعيينenabledForTemplateDeploymentعلى قيمة المفتاح إلى true.

إذا كان لديك خزنة مفاتيح بالفعل، فتأكد من أنها تسمح بنشر القالب.

Azure CLI
بوويرشيل

az keyvault update  --name ExampleVault --enabled-for-template-deployment true

Set-AzKeyVaultAccessPolicy -VaultName ExampleVault -EnabledForTemplateDeployment

لإنشاء خزنة مفاتيح جديدة وإضافة سر، استخدم:

Azure CLI
بوويرشيل

az group create --name ExampleGroup --location centralus
az keyvault create \
  --name ExampleVault \
  --resource-group ExampleGroup \
  --location centralus \
  --enabled-for-template-deployment true
az keyvault secret set --vault-name ExampleVault --name "ExamplePassword" --value "hVFkk965BuUv"

New-AzResourceGroup -Name ExampleGroup -Location centralus
New-AzKeyVault `
  -VaultName ExampleVault `
  -resourceGroupName ExampleGroup `
  -Location centralus `
  -EnabledForTemplateDeployment
$secretvalue = ConvertTo-SecureString 'hVFkk965BuUv' -AsPlainText -Force
$secret = Set-AzKeyVaultSecret -VaultName ExampleVault -Name 'ExamplePassword' -SecretValue $secretvalue

بصفتك مالك لخزنة المفاتيح، يمكنك تلقائيا الوصول إلى إنشاء بيانات سرية. إذا لم يكن المستخدم الذي يتعامل مع بيانات سرية هو صاحب خزينة المفاتيح، فامنح الوصول باستخدام:

Azure CLI
بوويرشيل

az keyvault set-policy \
  --upn <user-principal-name> \
  --name ExampleVault \
  --secret-permissions set delete get list

$userPrincipalName = "<Email Address of the deployment operator>"

Set-AzKeyVaultAccessPolicy `
  -VaultName ExampleVault `
  -UserPrincipalName <user-principal-name> `
  -PermissionsToSecrets set,delete,get,list

للحصول على مزيد من المعلومات حول إنشاء خزائن المفاتيح وإضافة بيانات سرية، راجع:

منح حق الوصول إلى البيانات السرية

يجب أن يكون لدى المستخدم الذي يقوم بتوزيع الملف Bicep Microsoft.KeyVault/vaults/deploy/action الإذن لنطاق مجموعة الموارد وخزنة المفاتيح. يمنح كل من أدوار المالكوالمساهمهذا الوصول. إذا أنشأت خزينة المفاتيح، فأنت المالك ولديك الإذن.

يوضح الإجراء التالي كيفية إنشاء دور بأدنى حد من الإذن وكيفية تعيين اسم المستخدم.

إنشاء ملف JSON لتعريف دور مخصص:

{
  "Name": "Key Vault Bicep deployment operator",
  "IsCustom": true,
  "Description": "Lets you deploy a Bicep file with the access to the secrets in the Key Vault.",
  "Actions": [
    "Microsoft.KeyVault/vaults/deploy/action"
  ],
  "NotActions": [],
  "DataActions": [],
  "NotDataActions": [],
  "AssignableScopes": [
    "/subscriptions/00000000-0000-0000-0000-000000000000"
  ]
}

استبدل "00000000-0000-0000-0000-000000000000" بمعرف الاشتراك.

أنشئ الدور الجديد باستخدام ملف JSON:

Azure CLI
بوويرشيل

az role definition create --role-definition "<path-to-role-file>"
az role assignment create \
  --role "Key Vault Bicep deployment operator" \
  --scope /subscriptions/<Subscription-id>/resourceGroups/<resource-group-name> \
  --assignee <user-principal-name>

New-AzRoleDefinition -InputFile "<path-to-role-file>"
New-AzRoleAssignment `
  -ResourceGroupName ExampleGroup `
  -RoleDefinitionName "Key Vault Bicep deployment operator" `
  -SignInName <user-principal-name>

تقوم العينات بتعيين الدور المخصص للمستخدم على مستوى مجموعة الموارد.

عند استخدام خزنة مفاتيح مع ملف Bicep لتطبيق مُدار، يجب منح حق الوصول إلى مدير خدمة موفر موارد الأجهزة. لمزيد من المعلومات، راجع Access Key Vault secret عند توزيع تطبيقات Azure المُدارة.

استرداد البيانات السرية في ملف Bicep

يمكنك استخدام الدالة getSecret في ملفات Bicep للحصول على سر key vault. لاحظ أن الدالة getSecret قابلة للتطبيق حصريا Microsoft.KeyVault/vaults على مورد. بالإضافة إلى ذلك، يقتصر على الاستخدام داخل params قسم الوحدة النمطية ولا يمكن استخدامه إلا مع المعلمات مع @secure() مصمم الديكور.

يمكن استخدام دالة أخرى تسمى az.getSecret() دالة في ملفات معلمات Bicep لاسترداد أسرار خزنة المفاتيح. لمزيد من المعلومات، راجع استرداد الأسرار في ملف المعلمات.

لأنه يمكن استخدام الدالة getSecret فقط في params قسم الوحدة النمطية. دعونا ننشئ sql.bicep في نفس الدليل مثل ملف main.bicep بالمحتوى التالي:

param sqlServerName string
param location string = resourceGroup().location
param adminLogin string

@secure()
param adminPassword string

resource sqlServer 'Microsoft.Sql/servers@2023-08-01-preview' = {
  name: sqlServerName
  location: location
  properties: {
    administratorLogin: adminLogin
    administratorLoginPassword: adminPassword
    version: '12.0'
  }
}

لاحظ في ملف Bicep السابق أن المعلمة adminPassword تحتوي على @secure() مصمم.

يستهلك ملف Bicep التالي sql.bicep كوحدة نمطية. يشير ملف Bicep إلى مخزن مفاتيح موجود، ويستدعي الدالة getSecret لاسترداد البيانات السرية لمخزن المفاتيح، ثم يمرر القيمة كمعلمة إلى الوحدة النمطية.

param sqlServerName string
param adminLogin string

param subscriptionId string
param kvResourceGroup string
param kvName string

resource kv 'Microsoft.KeyVault/vaults@2023-07-01' existing = {
  name: kvName
  scope: resourceGroup(subscriptionId, kvResourceGroup )
}

module sql './sql.bicep' = {
  name: 'deploySQL'
  params: {
    sqlServerName: sqlServerName
    adminLogin: adminLogin
    adminPassword: kv.getSecret('vmAdminPassword')
  }
}

استرداد البيانات السرية في ملف المعلمات

إذا كنت لا تريد استخدام وحدة نمطية، يمكنك استرداد أسرار مخزن المفاتيح في ملف المعلمات. ومع ذلك، يختلف الأسلوب اعتمادا على ما إذا كنت تستخدم ملف معلمة JSON أو ملف معلمة Bicep.

يوزع الملف Bicep التالي خادم SQL ويتضمن كلمة مرور المسؤول. تم تعيين مَعلمة كلمة المرور على سلسلة آمنة. ولكن Bicep لا يحدد من أين تأتي القيمة.

param sqlServerName string
param location string = resourceGroup().location
param adminLogin string

@secure()
param adminPassword string

resource sqlServer 'Microsoft.Sql/servers@2023-08-01-preview' = {
  name: sqlServerName
  location: location
  properties: {
    administratorLogin: adminLogin
    administratorLoginPassword: adminPassword
    version: '12.0'
  }
}

الآن، قم بإنشاء ملف معلمات لملف Bicep السابق.

ملف معلمة Bicep

az.getSecret يمكن استخدام الدالة .bicepparam في ملف لاسترداد قيمة سر من مخزن مفاتيح.

using './main.bicep'

param sqlServerName = '<your-server-name>'
param adminLogin = '<your-admin-login>'
param adminPassword = az.getSecret('<subscription-id>', '<rg-name>', '<key-vault-name>', '<secret-name>', '<secret-version>')

ملف معلمة JSON

في ملف معلمات JSON، حدد معلمة تطابق اسم المعلمة في ملف Bicep. لقيمة المعلمة، الرجوع إلى البيانات السرية لخزنة المفتاح. تشير إلى السر عن طريق تمرير معرّف المورد لخزنة المفاتيح واسم السر:

في ملف المعلمات التالي، يجب أن يكون سر key vault موجودا بالفعل، وأن توفر قيمة ثابتة لمعرف المورد الخاص به.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "adminLogin": {
      "value": "<your-admin-login>"
    },
    "adminPassword": {
      "reference": {
        "keyVault": {
          "id": "/subscriptions/<subscription-id>/resourceGroups/<rg-name>/providers/Microsoft.KeyVault/vaults/<key-vault-name>"
        },
        "secretName": "ExamplePassword"
      }
    },
    "sqlServerName": {
      "value": "<your-server-name>"
    }
  }
}

إذا كنت بحاجة إلى استخدام إصدار من السر بخلاف الإصدار الحالي، فقم بتضمين الخاصية secretVersion.

"secretName": "ExamplePassword",
"secretVersion": "cd91b2b7e10e492ebb870a6ee0591b68"

الخطوات التالية

للحصول على معلومات عامة حول خزانات المفاتيح، راجع ما هو Azure Key Vault؟
للحصول على أمثلة كاملة للإشارة إلى أسرار المفاتيح، راجع أمثلة على مخازن البيانات السرية على GitHub.
بالنسبة إلى وحدة Learn النمطية التي تغطي تمرير قيمة آمنة من مخزن المفاتيح، راجع إدارة عمليات النشر السحابية المعقدة باستخدام ميزات قالب ARM المتقدمة.

Share via