Uso de Azure Key Vault para pasar valores de parámetro seguros durante la implementación de Bicep
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:
- Establecimiento y recuperación de un secreto mediante la CLI
- Establecimiento y recuperación de un secreto mediante PowerShell
- Establecimiento y recuperación de un secreto mediante Portal
- Establecimiento y recuperación de un secreto mediante .NET
- Establecimiento y recuperación de un secreto mediante Node.js
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.
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/00000000-0000-0000-0000-000000000000" ] }
Reemplace "00000000-0000-0000-0000-000000000000" por el identificador de la suscripción.
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 JSON o un archivo de parámetros 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
- Para obtener información general sobre los almacenes de claves, consulte ¿Qué es Azure Key Vault?
- Para obtener ejemplos completos de secretos de clave de referencia, consulte los ejemplos de almacén de claves en GitHub.
- Para un módulo de Learn donde se usa un valor seguro de un almacén de claves, consulte Administración de implementaciones complejas en la nube mediante características avanzadas de la plantilla de ARM.