Compartir vía

Uso de Azure Key Vault para pasar valores de parámetro seguros durante la implementación de Bicep

  • Artículo

En lugar de colocar un valor seguro (como una contraseña) directamente en el archivo de Bicep o el archivo de parámetros, puede recuperar el valor de una instancia de Azure Key Vault durante una implementación. Cuando un módulo espera un parámetro string con el modificador secure:true, puede usar la función getSecret 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 a la del grupo de recursos en el que se realiza la implementación.

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 este escenario, consulte Instalar un certificado de Azure Key Vault en una máquina virtual.

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 plantilla.

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.

El siguiente procedimiento muestra cómo crear un rol con los permisos mínimos y cómo asignar el usuario.

  1. Creación de un archivo JSON de definición de rol personalizado

    {
  "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. Cree el nuevo rol con el archivo 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>

    En los ejemplos se asigna 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 función getSecret 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. Vamos a crear 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'
  }
}

Observe que en el archivo Bicep anterior, el parámetro adminPassword tiene un decorador @secure().

El siguiente archivo de Bicep consume sql.bicep como módulo. El archivo de Bicep hace referencia a un almacén de claves existente y llama a la función getSecret para recuperar el secreto del almacén de claves; luego, 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 el archivo de parámetros. Sin embargo, el enfoque varía en función de si usa un archivo de parámetros de JSON o un archivo de parámetros de Bicep.

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

Ahora cree un archivo de parámetros para el archivo de 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 el archivo de parámetros JSON, especifique un parámetro que coincida con el nombre del parámetro del archivo de Bicep. Para el valor del parámetro, haga referencia al secreto del almacén de claves. Se hace referencia al secreto pasando el identificador de recurso de almacén de claves y el nombre del secreto:

En el siguiente archivo de parámetros, debe existir el secreto del almacén de claves y tendrá que proporcionar 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 utilizar una versión del secreto distinta de la actual, incluya la propiedad secretVersion.

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

Pasos siguientes