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

  • Статья

Вместо того, чтобы помещать безопасное значение (например, пароль) непосредственно в файл Bicep или файл параметров, его можно получить из Key Vault Azure во время развертывания. Если модуль принимает параметр string с модификатором secure:true, для получения секрета хранилища ключей можно использовать функцию getSecret. Это значение никогда не будет раскрыто, так как указывается только его идентификатор в хранилище ключей.

Важно!

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

В статье не рассматривается настройка свойства виртуальной машины для URL-адреса сертификата в хранилище ключей. Шаблон быстрого запуска такого сценария описан в статье Установка сертификата на виртуальной машине из хранилища ключей Azure.

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

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

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

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

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

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"

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

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

Дополнительные сведения о создании хранилищ ключей и добавлении секретных кодов представлены в следующих статьях:

Предоставление доступа к секретам

Пользователь, развертывающий файл Bicep, должен иметь разрешение Microsoft.KeyVault/vaults/deploy/action для области группы ресурсов и хранилища ключей. Оно имеется у ролей Владелец и Участник. Если вы создали хранилище ключей, вы являетесь владельцем и имеете такое разрешение.

Ниже показано, как создать роль с минимальным разрешением и назначить пользователя

  1. Создание 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" на идентификатор подписки.

  2. Создание новой роли с помощью JSON-файла:

    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>

    В этих примерах роль назначается пользователю на уровне группы ресурсов.

При использовании хранилища ключей с файлом Bicep для управляемого приложения необходимо предоставить доступ к субъекту-службе Поставщик ресурсов устройств. Дополнительные сведения см. в статье Доступ к секрету Key Vault при развертывании Управляемых приложений Azure.

Использование функции getSecret

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

Следующий файл Bicep создает сервер SQL Azure. Параметр adminPassword имеет декоратор @secure().

param sqlServerName string
param adminLogin string

@secure()
param adminPassword string

resource sqlServer 'Microsoft.Sql/servers@2020-11-01-preview' = {
  name: sqlServerName
  location: resourceGroup().location
  properties: {
    administratorLogin: adminLogin
    administratorLoginPassword: adminPassword
    version: '12.0'
  }
}

Давайте воспользуемся предыдущим файлом Bicep в качестве модуля с именем файла sql.bicep в том же каталоге, что и основной файл Bicep.

Следующий файл 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-02-01' existing = {
  name: kvName
  scope: resourceGroup(subscriptionId, kvResourceGroup )
}

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

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

using './main.bicep'

param secureUserName = getSecret('exampleSubscription', 'exampleResourceGroup', 'exampleKeyVault', 'exampleSecretUserName', 'exampleSecretVersion')
param securePassword = az.getSecret('exampleSubscription', 'exampleResourceGroup', 'exampleKeyVault', 'exampleSecretPassword')

Ссылка на секреты в файле параметров

Если вы не хотите использовать модуль, вы можете ссылаться на хранилище ключей непосредственно в файле параметров. На следующем рисунке показано, как файл параметров ссылается на секрет и передает это значение в файл Bicep.

Схема интеграции хранилища ключей с Resource Manager

Примечание

В настоящее время вы можете ссылаться на хранилище ключей только в файлах параметров JSON. Вы не можете ссылаться на хранилище ключей в файле параметров Bicep.

Следующий файл Bicep развертывает сервер SQL, который содержит пароль администратора. В качестве параметра пароля задается защищенная строка. Но Bicep не указывает, откуда берется это значение.

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

@secure()
param adminPassword string

param sqlServerName string

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

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

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

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

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

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

Разверните шаблон и передайте файл параметров:

az group create --name SqlGroup --location westus2
az deployment group create \
  --resource-group SqlGroup \
  --template-file <Bicep-file> \
  --parameters <parameters-file>

Дальнейшие действия