Compartir vía

Uso de Azure Key Vault para pasar un secreto desde un almacén de claves como parámetro durante la implementación de Bicep

  • Artículo

En lugar de escribir un valor seguro como una contraseña directamente en el archivo de Bicep o en el archivo de parámetros, puede recuperar el valor de una Azure Key Vault durante una implementación. Cuando un módulo espera un parámetro string con el modificador secure:true, puede usar la getSecret función para obtener un secreto del almacén de claves. El valor nunca se expone debido a que solo hace referencia a su identificador de almacén de claves.

Importante

Este artículo se centra en cómo se pasa un valor confidencial como parámetro de plantilla. Cuando el secreto se pasa como parámetro, el almacén de claves puede existir en una suscripción diferente del grupo de recursos al que va a implementar.

En este artículo no se explica cómo establecer una propiedad de máquina virtual en la dirección URL de un certificado en un almacén de claves. Para obtener una plantilla de inicio rápido de ese escenario, consulte WinRM en una máquina virtual Windows.

Implementación de almacenes de claves y secretos

Para acceder a un almacén de claves durante la implementación de Bicep, establezca enabledForTemplateDeployment en el almacén de claves en true.

Si ya tiene un almacén de claves, asegúrese de que permite implementaciones de plantillas.

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

Para crear un nuevo almacén de claves y agregar un secreto, 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 propietario del almacén de claves, tiene acceso de forma automática a la creación de secretos. Si el usuario que trabaja con los secretos no es el propietario del almacén de claves, conceda acceso con:

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

Para más información sobre cómo crear almacenes de claves y agregar secretos, vea:

Concesión de acceso a los secretos

El usuario que implementa el archivo de Bicep debe tener el permiso Microsoft.KeyVault/vaults/deploy/action para el ámbito del grupo de recursos y el almacén de claves. Los roles Propietario y Colaborador conceden este acceso. Si creó el almacén de claves, es el propietario y tiene el permiso.

En el procedimiento siguiente se muestra cómo crear un rol con el permiso mínimo y cómo asignar el usuario.

  1. Cree un archivo JSON personalizado con una definición de rol:

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

    Reemplace "00000000-0000-0000-0000-000000000000" por el identificador de la suscripción.

  2. Use el archivo JSON para crear el nuevo rol:

    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>

    Los ejemplos asignan el rol personalizado al usuario en el nivel de grupo de recursos.

Al usar un almacén de claves con el archivo de Bicep en una aplicación administrada, debe conceder acceso a la entidad de servicio del proveedor de recursos del dispositivo. Para más información, consulte Acceso al secreto de Key Vault al implementar Azure Managed Applications.

Recuperar secretos en el archivo Bicep

Puede usar la getSecret función en archivos de Bicep para obtener un secreto del almacén de claves. Tenga en cuenta que la función getSecret se aplica exclusivamente a un recurso Microsoft.KeyVault/vaults. Además, está restringido al uso dentro de la sección params de un módulo y solo se puede usar con parámetros con el decorador @secure().

Otra función denominada función az.getSecret() se puede usar en archivos de parámetros de Bicep para recuperar secretos del almacén de claves. Para obtener más información, consulte Recuperar secretos en el archivo de parámetros.

Dado que la función getSecret solo se puede usar en la sección params de un módulo, cree un archivo sql.bicep en el mismo directorio que el archivo main.bicep con el siguiente contenido:

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

El parámetro adminPassword tiene un decorador @secure() en el archivo anterior.

El siguiente archivo de Bicep consume sql.bicep como módulo. El archivo Bicep hace referencia a un almacén de claves existente, llama a la función getSecret para recuperar el secreto del almacén de claves y, a continuación, pasa el valor como parámetro al 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')
  }
}

Recuperar secretos en el archivo de parámetros

Si no desea usar un módulo, puede recuperar secretos del almacén de claves en un archivo de parámetros. Sin embargo, el enfoque varía en función de si usa un archivo de parámetros JSON o Bicep.

El siguiente archivo de Bicep implementa un servidor SQL que incluye una contraseña de administrador. Aunque el parámetro contraseña se establece en una cadena segura, Bicep no especifica el origen de ese 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'
  }
}

A continuación, cree un archivo de parámetros para el archivo Bicep anterior.

Archivo de parámetros de Bicep

La función az.getSecret se puede usar en un archivo .bicepparam para recuperar el valor de un secreto de un almacén de claves:

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

Archivo de parámetros JSON

En un archivo de parámetros JSON, especifique un parámetro que coincida con el nombre del parámetro en el archivo de Bicep. Para el valor del parámetro, haga referencia al secreto del almacén de claves; Para ello, pase el identificador de recursos del almacén de claves y el nombre del secreto. En el siguiente archivo de parámetros, el secreto del almacén de claves ya debe existir y se proporciona un valor estático para su 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>"
    }
  }
}

Si necesita usar una versión del secreto distinto del actual, incluya una propiedad secretVersion:

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

Pasos siguientes