Utilizzare Azure Key Vault per passare il valore di parametro protetto durante la distribuzione Bicep

  • Articolo

Invece di inserire un valore protetto (ad esempio una password) direttamente nel file Bicep o nel file dei parametri, è possibile recuperare il valore da un Azure Key Vault durante una distribuzione. Quando un modulo prevede un parametro string con modificatore secure:true, è possibile usare la funzione getSecret per ottenere un segreto dell'insieme di credenziali delle chiavi. Il valore non viene mai esposto, in quanto si fa riferimento solo all'ID dell'insieme di credenziali chiave.

Importante

Questo articolo è incentrato su come passare un valore sensibile come parametro di modello. Quando il segreto viene passato come parametro, l'insieme di credenziali delle chiavi può esistere in una sottoscrizione diversa rispetto al gruppo di risorse in cui si esegue la distribuzione.

Questo articolo non tratta l’argomento su come impostare una proprietà della macchina virtuale su un URL di un certificato in un insieme di credenziali delle chiavi. Per un modello di avvio rapido di questo scenario, vedere Installare un certificato da Azure Key Vault in una macchina virtuale.

Distribuire insiemi di credenziali delle chiavi e segreti

Per accedere a un insieme di credenziali delle chiavi durante la distribuzione di Bicep, impostare enabledForTemplateDeploymentnell'insieme di credenziali delle chiavi su true.

Se si dispone già di un insieme di credenziali delle chiavi, assicurarsi che consenta le distribuzioni di modelli.

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

Per creare un nuovo insieme di credenziali delle chiavi e aggiungere un segreto, usare:

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"

Come proprietario dell'insieme di credenziali delle chiavi, si ha automaticamente accesso alla creazione di segreti. Se l'utente che lavora con i segreti non è il proprietario dell'insieme di credenziali delle chiavi, concedere l'accesso con:

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

Per altre informazioni sulla creazione di insiemi di credenziali delle chiavi e sull'aggiunta di segreti, vedere:

Concedere l'accesso ai segreti

L'utente che distribuisce il file Bicep deve disporre dell'autorizzazione Microsoft.KeyVault/vaults/deploy/action per l'ambito del gruppo di risorse e dell'insieme di credenziali delle chiavi. Entrambi i ruoli Proprietario e Collaboratore possono concedere l'accesso. L’utente che ha creato l'insieme di credenziali delle chiavi è il proprietario e ha l'autorizzazione.

La routine seguente mostra come creare un ruolo con l’autorizzazione minima e come assegnarlo all'utente.

  1. Creare un file JSON di definizione del ruolo personalizzato:

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

    Sostituire "00000000-0000-0000-0000-000000000000" con l’ID sottoscrizione.

  2. Creare il nuovo ruolo usando il file 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>

    I campioni assegnano il ruolo personalizzato all'utente a livello di gruppo di risorse.

Quando si usa un insieme di credenziali delle chiavi con il file Bicep per una Applicazione gestita, è necessario concedere l'accesso all'entità servizio Provider di risorse Appliance. Per altre informazioni, vedere Segreto di accesso di Key Vault quando si distribuiscono Applicazioni gestite di Azure.

Recuperare i segreti nel file Bicep

È possibile usare la funzione getSecret nei file Bicep per ottenere un segreto dell'insieme di credenziali delle chiavi. Si noti che la getSecret funzione è applicabile esclusivamente a una Microsoft.KeyVault/vaults risorsa. Inoltre, è limitato all'utilizzo all'interno della params sezione di un modulo e può essere usato solo con i parametri con l'elemento @secure() Decorator.

Un'altra funzione denominata az.getSecret() funzione può essere usata nei file di parametri Bicep per recuperare i segreti dell'insieme di credenziali delle chiavi. Per altre informazioni, vedere Recuperare i segreti nel file dei parametri.

Poiché la getSecret funzione può essere usata solo nella params sezione di un modulo. Creare un file sql.bicep nella stessa directory del file main.bicep con il contenuto seguente:

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

Si noti che nel file Bicep precedente il adminPassword parametro ha un @secure() elemento Decorator.

Il file Bicep seguente usa sql.bicep come modulo. Il file Bicep fa riferimento a un insieme di credenziali delle chiavi esistente e chiama la funzione getSecret per recuperare il segreto dell'insieme di credenziali delle chiavi e quindi passa il valore come parametro al modulo.

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

Recuperare segreti nel file dei parametri

Se non si vuole usare un modulo, è possibile recuperare i segreti dell'insieme di credenziali delle chiavi nel file dei parametri. Tuttavia, l'approccio varia a seconda che si usi un file di parametri JSON o un file di parametri Bicep.

Il file Bicep seguente distribuisce un server SQL che include una password di amministratore. Il parametro della password è impostato su una stringa sicura, Tuttavia il file Bicep non specifica da dove proviene tale valore.

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

Creare ora un file di parametri per il file Bicep precedente.

File di parametri Bicep

az.getSecret funzione può essere usata in un .bicepparam file per recuperare il valore di un segreto da un insieme di credenziali delle chiavi.

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

File di parametri JSON

Nel file di parametri JSON specificare un parametro che corrisponda al nome del parametro nel file Bicep. Per il valore del parametro, fare riferimento al segreto dall'insieme di credenziali delle chiavi. Si fa riferimento al segreto passando l'identificatore della risorsa dell'insieme di credenziali delle chiavi e il nome del segreto:

Nel file dei parametri seguente il segreto dell'insieme di credenziali delle chiavi deve esistere già e si deve fornire un valore statico per il relativo ID della risorsa.

{
  "$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 è necessario usare una versione del segreto diversa dalla versione corrente, usare la proprietà secretVersion.

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

Passaggi successivi