Azure Key Vault gebruiken om tijdens de implementatie een veilige parameterwaarde door te gevenUse Azure Key Vault to pass secure parameter value during deployment

In plaats van een beveiligde waarde (zoals een wacht woord) rechtstreeks in uw sjabloon of parameter bestand te plaatsen, kunt u tijdens een implementatie de waarde van een Azure Key Vault ophalen.Instead of putting a secure value (like a password) directly in your template or parameter file, you can retrieve the value from an Azure Key Vault during a deployment. U haalt de waarde op door te verwijzen naar de sleutel kluis en het geheim in het parameter bestand.You retrieve the value by referencing the key vault and secret in your parameter file. De waarde zelf wordt nooit getoond, omdat u alleen verwijst naar de sleutelkluis-id.The value is never exposed because you only reference its key vault ID. De sleutel kluis kan zich in een ander abonnement bevinden dan de resource groep die u implementeert.The key vault can exist in a different subscription than the resource group you're deploying to.

Dit artikel richt zich op het scenario voor het door geven van een gevoelige waarde in als een sjabloon parameter.This article focuses on the scenario of passing a sensitive value in as a template parameter. Het scenario voor het instellen van een virtuele-machine-eigenschap is niet van toepassing op de URL van een certificaat in een Key Vault.It doesn't cover the scenario of setting a virtual machine property to the URL of a certificate in a Key Vault. Zie een certificaat van Azure Key Vault op een virtuele machine installerenvoor een Quick Start-sjabloon van dat scenario.For a quickstart template of that scenario, see Install a certificate from Azure Key Vault on a Virtual Machine.

Sleutel kluizen en geheimen implementerenDeploy key vaults and secrets

Als u toegang wilt krijgen tot een sleutel kluis tijdens enabledForTemplateDeployment het implementeren van de sjabloon, stelt u de sleutel kluis in op true .To access a key vault during template deployment, set enabledForTemplateDeployment on the key vault to true.

Als u al een Key Vault hebt, moet u ervoor zorgen dat sjabloon implementaties zijn toegestaan.If you already have a Key Vault, make sure it allows template deployments.

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

Als u een nieuw Key Vault wilt maken en een geheim wilt toevoegen, gebruikt u:To create a new Key Vault and add a secret, 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"

Als eigenaar van de sleutel kluis hebt u automatisch toegang tot het maken van geheimen.As the owner of the key vault, you automatically have access to creating secrets. Als de gebruiker werkt met geheimen niet de eigenaar van de sleutel kluis, verleent u toegang met:If the user working with secrets isn't the owner of the key vault, grant access with:

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

Zie voor meer informatie over het maken van sleutel kluizen en het toevoegen van geheimen:For more information about creating key vaults and adding secrets, see:

Toegang verlenen tot de geheimenGrant access to the secrets

De gebruiker die de sjabloon implementeert, moet beschikken over de Microsoft.KeyVault/vaults/deploy/action machtiging voor het bereik van de resource groep en de sleutel kluis.The user who deploys the template must have the Microsoft.KeyVault/vaults/deploy/action permission for the scope of the resource group and key vault. De rollen eigenaar en Inzender verlenen deze toegang.The Owner and Contributor roles both grant this access. Als u de sleutel kluis hebt gemaakt, bent u de eigenaar, zodat u over de juiste machtigingen beschikt.If you created the key vault, you're the owner so you have the permission.

De volgende procedure laat zien hoe u een rol met de minimale machtiging maakt en hoe u de gebruiker toewijstThe following procedure shows how to create a role with the minimum permission, and how to assign the user

  1. Een JSON-bestand met een aangepaste roldefinitie maken:Create a custom role definition JSON file:

    {
      "Name": "Key Vault resource manager template deployment operator",
      "IsCustom": true,
      "Description": "Lets you deploy a resource manager template 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"
      ]
    }
    

    Vervang "00000000-0000-0000-0000-000000000000" door de abonnements-ID.Replace "00000000-0000-0000-0000-000000000000" with the subscription ID.

  2. Maak de nieuwe rol met behulp van het JSON-bestand:Create the new role using the JSON file:

    az role definition create --role-definition "<path-to-role-file>"
    az role assignment create \
      --role "Key Vault resource manager template deployment operator" \
      --assignee <user-principal-name> \
      --resource-group ExampleGroup
    

    De voor beelden wijzen de aangepaste rol toe aan de gebruiker op het niveau van de resource groep.The samples assign the custom role to the user on the resource group level.

Wanneer u een Key Vault gebruikt met de sjabloon voor een beheerde toepassing, moet u toegang verlenen tot de service-principal van het toestel bron provider .When using a Key Vault with the template for a Managed Application, you must grant access to the Appliance Resource Provider service principal. Zie toegang Key Vault geheim bij het implementeren van Azure Managed Applicationsvoor meer informatie.For more information, see Access Key Vault secret when deploying Azure Managed Applications.

Referentie geheimen met een statische IDReference secrets with static ID

Met deze methode verwijst u naar de sleutel kluis in het parameter bestand, niet de sjabloon.With this approach, you reference the key vault in the parameter file, not the template. De volgende afbeelding laat zien hoe het parameter bestand verwijst naar het geheim en dat deze waarde wordt door gegeven aan de sjabloon.The following image shows how the parameter file references the secret and passes that value to the template.

Diagram van de statische ID van de Resource Manager-sleutel kluis integratie

Zelf studie: Azure Key Vault integreren in Resource Manager Sjabloonimlementatie gebruikt deze methode.Tutorial: Integrate Azure Key Vault in Resource Manager Template deployment uses this method.

Met de volgende sjabloon wordt een SQL-Server geïmplementeerd met een beheerders wachtwoord.The following template deploys a SQL server that includes an administrator password. De wachtwoord parameter is ingesteld op een veilige teken reeks.The password parameter is set to a secure string. Maar de sjabloon geeft niet op waar de waarde vandaan komt.But, the template doesn't specify where that value comes from.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "adminLogin": {
      "type": "string"
    },
    "adminPassword": {
      "type": "securestring"
    },
    "sqlServerName": {
      "type": "string"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Sql/servers",
      "apiVersion": "2015-05-01-preview",
      "name": "[parameters('sqlServerName')]",
      "location": "[resourceGroup().location]",
      "tags": {},
      "properties": {
        "administratorLogin": "[parameters('adminLogin')]",
        "administratorLoginPassword": "[parameters('adminPassword')]",
        "version": "12.0"
      }
    }
  ],
  "outputs": {
  }
}

Maak nu een parameter bestand voor de voor gaande sjabloon.Now, create a parameter file for the preceding template. Geef in het parameter bestand een para meter op die overeenkomt met de naam van de para meter in de sjabloon.In the parameter file, specify a parameter that matches the name of the parameter in the template. Voor de parameter waarde verwijst u naar het geheim van de sleutel kluis.For the parameter value, reference the secret from the key vault. U verwijst naar het geheim door de resource-id van de sleutel kluis en de naam van het geheim door te geven:You reference the secret by passing the resource identifier of the key vault and the name of the secret:

In het volgende parameter bestand moet het sleutel kluis geheim al bestaan en kunt u een statische waarde voor de resource-ID opgeven.In the following parameter file, the key vault secret must already exist, and you provide a static value for its resource ID.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
      "adminLogin": {
        "value": "exampleadmin"
      },
      "adminPassword": {
        "reference": {
          "keyVault": {
          "id": "/subscriptions/<subscription-id>/resourceGroups/<rg-name>/providers/Microsoft.KeyVault/vaults/<vault-name>"
          },
          "secretName": "ExamplePassword"
        }
      },
      "sqlServerName": {
        "value": "<your-server-name>"
      }
  }
}

Als u een andere versie van het geheim wilt gebruiken dan de huidige versie, gebruikt u de secretVersion eigenschap.If you need to use a version of the secret other than the current version, use the secretVersion property.

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

Implementeer de sjabloon en geef deze door in het parameter bestand:Deploy the template and pass in the parameter file:

az group create --name SqlGroup --location westus2
az deployment group create \
  --resource-group SqlGroup \
  --template-uri <template-file-URI> \
  --parameters <parameter-file>

Referentie geheimen met een dynamische IDReference secrets with dynamic ID

In de vorige sectie is geleerd hoe u een statische Resource-ID voor het sleutel kluis geheim kunt door geven uit de para meter.The previous section showed how to pass a static resource ID for the key vault secret from the parameter. In sommige scenario's moet u echter verwijzen naar een sleutel kluis geheim dat afhankelijk is van de huidige implementatie.However, in some scenarios, you need to reference a key vault secret that varies based on the current deployment. Of u wilt parameter waarden door geven aan de sjabloon in plaats van een verwijzings parameter in het parameter bestand te maken.Or, you may want to pass parameter values to the template rather than create a reference parameter in the parameter file. In beide gevallen kunt u de resource-ID voor een sleutel kluis geheim dynamisch genereren met behulp van een gekoppelde sjabloon.In either case, you can dynamically generate the resource ID for a key vault secret by using a linked template.

U kunt de resource-ID in het parameter bestand niet dynamisch genereren omdat sjabloon expressies niet zijn toegestaan in het parameter bestand.You can't dynamically generate the resource ID in the parameters file because template expressions aren't allowed in the parameters file.

In de bovenliggende sjabloon voegt u de geneste sjabloon toe en geeft u een para meter door die de dynamisch gegenereerde Resource-ID bevat.In your parent template, you add the nested template and pass in a parameter that contains the dynamically generated resource ID. In de volgende afbeelding ziet u hoe een para meter in de gekoppelde sjabloon verwijst naar het geheim.The following image shows how a parameter in the linked template references the secret.

Dynamische ID

Met de volgende sjabloon wordt de sleutel kluis-ID dynamisch gemaakt en door gegeven als para meter.The following template dynamically creates the key vault ID and passes it as a parameter.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
      "location": {
        "type": "string",
        "defaultValue": "[resourceGroup().location]",
        "metadata": {
          "description": "The location where the resources will be deployed."
        }
      },
      "vaultName": {
        "type": "string",
        "metadata": {
          "description": "The name of the keyvault that contains the secret."
        }
      },
      "secretName": {
        "type": "string",
        "metadata": {
          "description": "The name of the secret."
        }
      },
      "vaultResourceGroupName": {
        "type": "string",
        "metadata": {
          "description": "The name of the resource group that contains the keyvault."
        }
      },
      "vaultSubscription": {
        "type": "string",
        "defaultValue": "[subscription().subscriptionId]",
        "metadata": {
          "description": "The name of the subscription that contains the keyvault."
        }
      }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2020-10-01",
      "name": "dynamicSecret",
      "properties": {
        "mode": "Incremental",
        "expressionEvaluationOptions": {
          "scope": "inner"
        },
        "template": {
          "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
          "contentVersion": "1.0.0.0",
          "parameters": {
            "adminLogin": {
              "type": "string"
            },
            "adminPassword": {
              "type": "securestring"
            },
            "location": {
              "type": "string"
            }
          },
          "variables": {
            "sqlServerName": "[concat('sql-', uniqueString(resourceGroup().id, 'sql'))]"
          },
          "resources": [
            {
              "type": "Microsoft.Sql/servers",
              "apiVersion": "2018-06-01-preview",
              "name": "[variables('sqlServerName')]",
              "location": "[parameters('location')]",
              "properties": {
                "administratorLogin": "[parameters('adminLogin')]",
                "administratorLoginPassword": "[parameters('adminPassword')]"
              }
            }
          ],
          "outputs": {
            "sqlFQDN": {
              "type": "string",
              "value": "[reference(variables('sqlServerName')).fullyQualifiedDomainName]"
            }
          }
        },
        "parameters": {
          "location": {
            "value": "[parameters('location')]"
          },
          "adminLogin": {
            "value": "ghuser"
          },
          "adminPassword": {
            "reference": {
              "keyVault": {
                "id": "[resourceId(parameters('vaultSubscription'), parameters('vaultResourceGroupName'), 'Microsoft.KeyVault/vaults', parameters('vaultName'))]"
              },
              "secretName": "[parameters('secretName')]"
            }
          }
        }
      }
    }
  ],
  "outputs": {
  }
}

Volgende stappenNext steps