Compartilhar via

Usar o Azure Key Vault para aprovar um valor de parâmetro seguro durante a implantação do Bicep

  • Artigo

Em vez de inserir um valor seguro (como uma senha) diretamente no arquivo Bicep ou arquivo de parâmetro, é possível recuperar o valor de um Azure Key Vault durante uma implantação. Quando um módulo espera obter um parâmetro string com um modificador secure:true, é possível usar a função getSecret para obter um segredo do cofre de chaves. O valor nunca é exposto porque você apenas fazer referência à sua ID de cofre de chaves.

Importante

O foco deste artigo é mostrar como aprovar um valor confidencial como um parâmetro do modelo. Quando o segredo é passado como um parâmetro, o cofre de chaves pode existir em uma assinatura que não seja a do grupo de recursos de destino da implantação.

Este artigo não aborda como definir uma propriedade de máquina virtual para a URL de um certificado em um cofre de chaves. Para obter um modelo de início rápido desse cenário, confira Instalar um certificado do Azure Key Vault em uma máquina virtual.

Implantar Key Vaults e segredos

Para acessar um cofre de chaves durante a implantação do Bicep, defina enabledForTemplateDeployment como true no cofre de chaves.

Caso já tenha um cofre de chaves, verifique se ele permite executar implantações de modelos.

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

Para criar um cofre de chaves e adicionar um segredo, use:

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"

Como proprietário do cofre de chaves, você tem acesso de modo automático para criar segredos. Se o usuário que está trabalhando com segredos não for o proprietário do cofre de chaves, conceda acesso com:

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

Para obter mais informações sobre como criar cofres de chaves e adicionar segredos, confira:

Permitir acesso aos segredos

O usuário que implanta um arquivo Bicep deverá ter a permissão Microsoft.KeyVault/vaults/deploy/action para usar o escopo do grupo de recursos e do cofre de chaves. Ambas as funções Proprietário e Colaborador concedem esse acesso. Caso tenha criado o cofre de chaves, você é o proprietário e tem a permissão.

O procedimento a seguir mostrará de que modo criar uma função com permissão mínima, bem como atribuir um usuário.

  1. Crie um arquivo JSON de definição de função personalizada:

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

    Substitua "00000000-0000-0000-0000-000000000000" por sua ID da assinatura.

  2. Crie a nova função usando o arquivo 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>

    As amostras designam a função personalizada para o usuário no nível do grupo de recursos.

Ao usar um cofre de chaves com o arquivo Bicep em um Aplicativo Gerenciado, será preciso permitir acesso à entidade de serviço do Provedor de Recursos do Dispositivo. Para obter mais informações, confira Segredo do Azure Key Vault durante a implantação de Aplicativos Gerenciados do Azure.

Recuperar segredos no arquivo Bicep

Você pode usar a função getSecret em arquivos Bicep para obter um segredo do cofre de chaves. Observe que a função getSecret é aplicável exclusivamente a um recurso Microsoft.KeyVault/vaults. Além disso, ele é restrito ao uso na seção params de um módulo e só pode ser usado com parâmetros com o decorador @secure().

Outra função chamada de função az.getSecret() pode ser usada em arquivos de parâmetro Bicep para recuperar segredos do cofre de chaves. Para obter mais informações, consulte Recuperar segredos no arquivo de parâmetros.

Porque a função getSecret só pode ser usada na seção params de um módulo. Vamos criar um sql.bicep no mesmo diretório que o arquivo main.bicep com o seguinte conteúdo:

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

Observe que, no arquivo Bicep anterior, o parâmetro adminPassword tem um decorador @secure().

O arquivo Bicep mostrado abaixo consumirá o arquivo sql.bicep como um módulo. O arquivo Bicep faz referência a um cofre de chaves existente, depois executa uma chamada à função getSecret para recuperar o segredo do cofre de chaves. Em seguida, ele aprova o valor como um parâmetro para o módulo.

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

Segredos de referência em arquivo de parâmetros

Se você não quiser usar um módulo, poderá recuperar segredos do cofre de chaves no arquivo de parâmetros. No entanto, a abordagem varia dependendo se você está usando um arquivo de parâmetro JSON ou um arquivo de parâmetro Bicep.

O arquivo Bicep mostrado abaixo implantará um servidor SQL que inclui uma senha de administrador. O parâmetro de senha é definido como uma cadeia de caracteres segura. No entanto, o Bicep não especifica a origem desse valor.

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

Agora, crie um arquivo de parâmetros para o arquivo Bicep anterior.

Arquivo do parâmetro Bicep

A função az.getSecret pode ser usada em um arquivo .bicepparam para recuperar o valor de um segredo de um cofre de chaves.

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

Arquivo de parâmetro JSON

No arquivo de parâmetros JSON, especifique um parâmetro correspondente ao nome do parâmetro usado no arquivo Bicep. Para o valor do parâmetro, referenciar o segredo do cofre de chave. Você faz referência ao segredo transmitindo o identificador de recurso do cofre de chaves e o nome do segredo:

No arquivo de parâmetros a seguir, o segredo do cofre de chaves já deve existir e você fornece um valor estático para sua ID de recurso.

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

Caso precise usar uma versão do segredo diferente da versão atual, inclua a propriedade secretVersion.

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

Próximas etapas