Dela via


Använda Azure Key Vault för att skicka en hemlighet som en parameter under Bicep-distributionen

Den här artikeln beskriver hur du använder Azure Key Vault för att skicka en hemlighet som en parameter under Bicep-distributionen. I stället för att ange ett säkert värde som ett lösenord direkt i Bicep-filen eller parameterfilen kan du hämta värdet från Azure Key Vault under en distribution.

När en modul förväntar sig en strängparameter med en secure:true modifierare kan du använda getSecret funktionen för att hämta en nyckelvalvshemlighet. Du exponerar inte värdet eftersom du bara refererar till dess nyckelvalvs-ID.

Viktigt!

Den här artikeln fokuserar på hur du skickar ett känsligt värde som en mallparameter. När hemligheten skickas som en parameter kan nyckelvalvet finnas i en annan prenumeration än den resursgrupp som du distribuerar till.

Den här artikeln beskriver inte hur du anger en virtuell datoregenskap (VM) till ett certifikats URL i ett nyckelvalv. En snabbstartsmall för det scenariot finns i WinRM på en virtuell Windows-dator.

Distribuera nyckelvalv och hemligheter

Om du vill komma åt ett nyckelvalv under Bicep-distributionen anger du enabledForTemplateDeployment nyckelvalvet till true.

Om du redan har ett nyckelvalv kontrollerar du att det tillåter malldistributioner.

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

Om du vill skapa ett nytt nyckelvalv och lägga till en hemlighet använder du:

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"

Ägaren till nyckelvalvet har automatiskt åtkomst till att skapa hemligheter. Om användaren som arbetar med hemligheter inte är ägare till nyckelvalvet kan du bevilja åtkomst med:

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

Mer information om hur du skapar nyckelvalv och lägger till hemligheter finns i:

Bevilja åtkomst till hemligheterna

Den användare som distribuerar Bicep-filen måste ha Microsoft.KeyVault/vaults/deploy/action behörighet för resursgruppens och nyckelvalvets omfång. Rollerna Ägare och Deltagare beviljar båda den här åtkomsten. Om du har skapat nyckelvalvet är du ägare och har behörigheten.

Följande procedur visar hur du skapar en roll med minsta behörighet och hur du tilldelar användaren:

  1. Skapa en anpassad JSON-fil med en rolldefinition:

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

    Ersätt "00000000-0000-0000-0000-0000000000000" med prenumerations-ID:t.

  2. Använd JSON-filen för att skapa den nya rollen:

    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>
    

    Föregående exempel tilldelar den anpassade rollen till användaren på resursgruppsnivå.

Om du använder ett nyckelvalv med en Bicep-fil för ett hanterat program måste du bevilja åtkomst till tjänstens huvudnamn för apparatresursprovidern . Mer information finns i Åtkomst till en Key Vault-hemlighet när du distribuerar Azure-hanterade program.

Hämta hemligheter i en Bicep-fil

Du kan använda getSecret funktionen i en Bicep-fil för att hämta en nyckelvalvshemlighet. Funktionen getSecret kan endast användas med en Microsoft.KeyVault/vaults resurs. Dessutom kan den endast användas i params avsnittet i en modul och endast med parametrar som har dekoratören @secure() .

Du kan använda en annan funktion som heter az.getSecret() i en Bicep-parameterfil för att hämta key vault-hemligheter. Mer information finns i Hämta hemligheter i en parameterfil.

getSecret Eftersom funktionen endast kan användas i avsnittet i params en modul skapar du en sql.bicep-fil i samma katalog som filen main.bicep med följande innehåll:

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

Parametern adminPassword har en @secure() dekoratör i föregående fil.

Följande Bicep-fil använder sql.bicep som en modul. Bicep-filen refererar till ett befintligt nyckelvalv, anropar getSecret funktionen för att hämta nyckelvalvets hemlighet och skickar sedan värdet som en parameter till modulen:

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

Hämta hemligheter i en parameterfil

Om du inte vill använda en modul kan du hämta key vault-hemligheter i en parameterfil. Metoden varierar dock beroende på om du använder en JSON- eller Bicep-parameterfil.

Följande Bicep-fil distribuerar en SQL-server som innehåller ett administratörslösenord. Även om lösenordsparametern är inställd på en säker sträng anger Bicep inte värdets ursprung:

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

Skapa sedan en parameterfil för föregående Bicep-fil.

Bicep-parameterfil

Funktionen az.getSecret kan användas i en .bicepparam fil för att hämta värdet för en hemlighet från ett nyckelvalv:

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

JSON-parameterfil

I en JSON-parameterfil anger du en parameter som matchar namnet på parametern i Bicep-filen. För parametervärdet refererar du till hemligheten från nyckelvalvet. Skicka resursidentifieraren för nyckelvalvet och namnet på hemligheten. I följande parameterfil måste nyckelvalvshemligheten redan finnas. Du anger ett statiskt värde för dess resurs-ID.

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

Om du behöver använda en annan version av hemligheten än den aktuella ska du inkludera en secretVersion egenskap:

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