Использование Azure Key Vault для передачи секрета в качестве параметра во время развертывания Bicep

Статья
2025-04-11

В этой статье объясняется, как использовать Azure Key Vault для передачи секрета в качестве параметра во время развертывания Bicep. Вместо ввода безопасного значения, например пароля непосредственно в файл Bicep или файл параметров, можно получить значение из Azure Key Vault во время развертывания.

Когда модуль ожидает строковый параметр с примененным модификатором, вы можете использовать функцию getSecret для получения секрета хранилища ключей. Вы не раскрываете значение, так как ссылаетесь только на ID хранилища ключей.

Внимание

В этой статье основное внимание уделяется передаче конфиденциального значения в качестве параметра шаблона. При передаче секрета в качестве параметра хранилище ключей может существовать в другой подписке, отличной от группы ресурсов, в которой выполняется развертывание.

В этой статье не объясняется, как установить свойство виртуальной машины для URL-адреса сертификата в хранилище ключей. Для быстрого запуска по этому сценарию см. WinRM на виртуальной машине Windows.

Развертывание хранилищ Key Vault и секретов

Чтобы получить доступ к хранилищу ключей во время развертывания Bicep, задайте для enabledForTemplateDeployment хранилища ключей значение true.

Если у вас уже есть хранилище ключей, убедитесь, что он разрешает развертывания шаблонов.

Azure CLI
Azure PowerShell

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

Set-AzKeyVaultAccessPolicy -VaultName ExampleVault -EnabledForTemplateDeployment

Чтобы создать новое хранилище ключей и добавить секрет, используйте следующее.

Azure CLI
Azure PowerShell

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
Azure PowerShell

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/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e"
  ]
}

Замените "00000000-0000-0000-0000-000000000000" на идентификатор подписки.

Используйте JSON-файл для создания новой роли:

Azure CLI
Azure PowerShell

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 для управляемого приложения, необходимо предоставить доступ служебному принципалу службы поставщика ресурсов устройства. Дополнительные сведения см. в статье "Доступ к секрету Key Vault" при развертывании управляемых приложений Azure.

Извлечение секретов в файле Bicep

Вы можете использовать функцию getSecret в файле Bicep для получения секрета из хранилища ключей. Функцию getSecret можно использовать только с ресурсом Microsoft.KeyVault/vaults . Кроме того, его можно использовать только в params разделе модуля и только с параметрами, имеющими @secure() декоратор.

Для получения секретов хранилища ключей в файле параметров Bicep можно использовать другую функцию под названием az.getSecret(). Дополнительные сведения см. в разделе Получение секретов в файле параметров.

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'
  }
}

В предыдущем файле параметру 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-файле. Для значения параметра используйте ссылку на секрет из хранилища ключей. Передайте идентификатор ресурса хранилища ключей и имя секрета. В следующем файле параметров секрет хранилища ключей должен уже существовать. Вы предоставляете статическое значение для его идентификатора ресурса.

{
  "$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 JSON".

Поделиться через