Partilhar via

Usar o Azure Key Vault para passar um segredo como parâmetro durante a implantação do Bicep

Este artigo explica como usar o Azure Key Vault para passar um segredo como parâmetro durante a implementação de Bicep. Em vez de inserir um valor seguro, como uma senha, diretamente em seu arquivo Bicep ou arquivo de parâmetros, você pode recuperar o valor do Cofre de Chaves do Azure durante uma implantação.

Quando um módulo espera um parâmetro string com um secure:true modificador aplicado, você pode usar a getSecret função para obter um segredo do cofre de chaves. Você não expõe o valor porque faz referência apenas ao ID do cofre de chaves.

Importante

Este artigo se concentra em como passar um valor confidencial como um parâmetro de modelo. Quando o segredo é passado como um parâmetro, o cofre de chaves pode existir numa subscrição diferente do grupo de recursos em que está a implementar.

Este artigo não aborda como definir uma propriedade de máquina virtual (VM) para a URL de um certificado em um cofre de chaves. Para obter um modelo de início rápido desse cenário, consulte WinRM em uma VM do Windows.

Implantar cofres de chaves e segredos

Para aceder a um cofre de chaves durante a implementação do Bicep, configure enabledForTemplateDeployment no cofre de chaves como true.

Se já tiver um cofre de chaves, verifique se permite implementações de modelos.

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

Para criar um novo 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"

O proprietário do cofre de chaves tem automaticamente acesso para criar segredos. Se o usuário que está trabalhando com segredos não for o proprietário do cofre de chaves, você poderá conceder 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, consulte:

Conceder acesso aos segredos

O usuário que implanta o arquivo Bicep deve ter a Microsoft.KeyVault/vaults/deploy/action permissão para o escopo do grupo de recursos e do cofre de chaves. As funções Proprietário e Colaborador concedem esse acesso. Se você criou o cofre de chaves, você é o proprietário e tem a permissão.

O procedimento a seguir mostra como criar uma função com a permissão mínima e como atribuir o usuário:

  1. Crie um arquivo JSON personalizado com uma definição de função:

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

    Substitua "00000000-0000-0000-0000-0000000000000" pelo ID da assinatura.

  2. Use o arquivo JSON para criar a nova função:

    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>

    Os exemplos anteriores atribuem a função personalizada ao usuário no nível do grupo de recursos.

Se utilizar um cofre de chaves com um arquivo Bicep para uma aplicação gerida, deverá conceder acesso à entidade de serviço do Appliance Resource Provider. Para obter mais informações, consulte Aceder a um segredo do Cofre de Chaves ao implantar aplicações geridas do Azure.

Recuperar segredos em um arquivo Bicep

Você pode usar a getSecret função num ficheiro Bicep para obter um segredo do cofre de chaves. A getSecret função só pode ser usada com um Microsoft.KeyVault/vaults recurso. Além disso, ele pode ser usado apenas dentro da params seção de um módulo e apenas com parâmetros que tenham o @secure() decorador.

Você pode usar outra função chamada az.getSecret() num ficheiro de parâmetros do Bicep para recuperar segredos armazenados no cofre de segredos. Para obter mais informações, consulte Recuperar segredos em um arquivo de parâmetros.

Como a getSecret função pode ser usada apenas na params seção de um módulo, crie um arquivo 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@2024-11-01-preview' = {
  name: sqlServerName
  location: location
  properties: {
    administratorLogin: adminLogin
    administratorLoginPassword: adminPassword
    version: '12.0'
  }
}

O adminPassword parâmetro tem um @secure() decorador no ficheiro anterior.

O seguinte arquivo Bicep consome sql.bicep como um módulo. O arquivo Bicep faz referência a um cofre de chaves existente, chama a getSecret função para recuperar o segredo do cofre de chaves e, em seguida, passa 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@2025-05-01' existing = {
  name: kvName
  scope: resourceGroup(subscriptionId, kvResourceGroup )
}

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

Recuperar segredos em um arquivo de parâmetros

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

O seguinte arquivo Bicep implanta um servidor SQL que inclui uma senha de administrador. Embora o parâmetro password esteja definido como uma cadeia de caracteres segura, 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@2024-11-01-preview' = {
  name: sqlServerName
  location: location
  properties: {
    administratorLogin: adminLogin
    administratorLoginPassword: adminPassword
    version: '12.0'
  }
}

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

Arquivo de parâmetros do bíceps

A az.getSecret função pode ser usada num .bicepparam ficheiro 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âmetros JSON

Em um arquivo de parâmetros JSON, especifique um parâmetro que corresponda ao nome do parâmetro no arquivo Bicep. Para o valor do parâmetro, faça referência ao segredo do cofre de chaves. Passe o identificador de recurso do cofre de chaves e o nome do segredo. No seguinte arquivo de parâmetros, o segredo do cofre de chaves já deve existir. Você fornece um valor estático para o identificador 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>"
    }
  }
}

Se você precisar usar uma versão do segredo diferente da atual, inclua uma secretVersion propriedade:

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

Conteúdos relacionados

  • Last updated on