Verwenden von Azure Key Vault zum Übergeben eines sicheren Parameterwerts während der BereitstellungUse Azure Key Vault to pass secure parameter value during deployment

Anstatt einen sicheren Wert (wie ein Kennwort) direkt in Ihre Vorlage oder Parameterdatei einzufügen, können Sie den Wert während einer Bereitstellung aus einem Azure Key Vault abrufen.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. Sie rufen den Wert ab, indem Sie den Schlüsseltresor und das Geheimnis in Ihrer Parameterdatei angeben.You retrieve the value by referencing the key vault and secret in your parameter file. Der Wert wird nie offengelegt, da Sie nur auf die Schlüsseltresor-ID verweisen.The value is never exposed because you only reference its key vault ID. Der Schlüsseltresor kann in einem anderen Abonnement als die Ressourcengruppe vorhanden sein, für die Sie ihn bereitstellen.The key vault can exist in a different subscription than the resource group you're deploying to.

Dieser Artikel konzentriert sich auf das Szenario, bei dem ein sensibler Wert als Vorlagenparameter zur Eingabe übergeben wird.This article focuses on the scenario of passing a sensitive value in as a template parameter. Er behandelt nicht das Szenario, in dem eine Eigenschaft eines virtuellen Computers auf die URL eines Zertifikats in einem Schlüsseltresor festgelegt wird.It doesn't cover the scenario of setting a virtual machine property to the URL of a certificate in a Key Vault. Eine Schnellstartvorlage für dieses Szenario finden Sie unter Installieren eines Zertifikats aus Azure Key Vault auf einem virtuellen Computer.For a quickstart template of that scenario, see Install a certificate from Azure Key Vault on a Virtual Machine.

Bereitstellen von Schlüsseltresoren und GeheimnissenDeploy key vaults and secrets

Um während der Vorlagenbereitstellung auf einen Schlüsseltresor zuzugreifen, legen Sie enabledForTemplateDeployment für den Schlüsseltresor auf true fest.To access a key vault during template deployment, set enabledForTemplateDeployment on the key vault to true.

Wenn Sie bereits über einen Schlüsseltresor verfügen, stellen Sie sicher, dass er Vorlagenbereitstellungen zulässt.If you already have a Key Vault, make sure it allows template deployments.

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

Verwenden Sie zum Erstellen eines neuen Schlüsseltresors Folgendes: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 Besitzer des Schlüsseltresors haben Sie automatisch Zugriff auf die Erstellung von Geheimnissen.As the owner of the key vault, you automatically have access to creating secrets. Wenn der Benutzer, der mit Geheimnissen arbeitet, nicht der Besitzer des Schlüsseltresors ist, gewähren Sie den Zugriff mit: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

Weitere Informationen zum Erstellen von Schlüsseltresoren und zum Hinzufügen von Geheimnissen finden Sie unter:For more information about creating key vaults and adding secrets, see:

Gewähren des Zugriffs auf die GeheimnisseGrant access to the secrets

Der Benutzer, der die Vorlage bereitstellt, muss die Berechtigung Microsoft.KeyVault/vaults/deploy/action für den Bereich der Ressourcengruppe und des Schlüsseltresors besitzen.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. Die Rollen Besitzer und Mitwirkender gewähren diesen Zugriff.The Owner and Contributor roles both grant this access. Wenn Sie den Schlüsseltresor erstellt haben, sind Sie der Besitzer und verfügen somit über die Berechtigung.If you created the key vault, you're the owner so you have the permission.

Die folgende Prozedur zeigt das Erstellen einer Rolle mit der Mindestberechtigung und das Zuweisen des BenutzersThe following procedure shows how to create a role with the minimum permission, and how to assign the user

  1. Erstellen einer benutzerdefinierten Rollendefinition (JSON-Datei):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"
      ]
    }
    

    Ersetzen Sie „00000000-0000-0000-0000-000000000000“ durch die Abonnement-ID.Replace "00000000-0000-0000-0000-000000000000" with the subscription ID.

  2. Erstellen Sie die neue Rolle mithilfe der JSON-Datei: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
    

    Die Beispiele weisen dem Benutzer auf Ressourcengruppenebene die benutzerdefinierte Rolle zu.The samples assign the custom role to the user on the resource group level.

Wenn ein Schlüsseltresor zusammen mit der Vorlage für eine verwaltete Anwendung verwendet wird, müssen Sie Zugriff auf den Dienstprinzipal des Ressourcenanbieters der Appliance erteilen.When using a Key Vault with the template for a Managed Application, you must grant access to the Appliance Resource Provider service principal. Weitere Informationen finden Sie unter Zugreifen auf das Geheimnis im Schlüsseltresor bei der Bereitstellung von Azure Managed Applications.For more information, see Access Key Vault secret when deploying Azure Managed Applications.

Verweisen auf Geheimnisse mit einer statischen IDReference secrets with static ID

Bei dieser Herangehensweise verweisen Sie auf den Schlüsseltresor in der Parameterdatei, nicht in der Vorlage.With this approach, you reference the key vault in the parameter file, not the template. Die folgende Abbildung zeigt, wie die Parameterdatei auf das Geheimnis verweist und diesen Wert an die Vorlage übergibt.The following image shows how the parameter file references the secret and passes that value to the template.

Diagramm der Resource Manager-Integration des Schlüsseltresors mit statischer ID

Tutorial: Integrieren von Azure Key Vault in die Resource Manager-Vorlagenbereitstellung verwendet diese Methode.Tutorial: Integrate Azure Key Vault in Resource Manager Template deployment uses this method.

Die folgende Vorlage stellt einen SQL-Server bereit, der ein Administratorkennwort enthält.The following template deploys a SQL server that includes an administrator password. Der Kennwortparameter ist auf eine sichere Zeichenfolge festgelegt.The password parameter is set to a secure string. Aber die Vorlage gibt nicht an, woher dieser Wert stammt.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": {
  }
}

Erstellen Sie jetzt eine Parameterdatei für der vorherige Vorlage.Now, create a parameter file for the preceding template. Geben Sie in der Parameterdatei einen Parameter an, der dem Namen des Parameters in der Vorlage entspricht.In the parameter file, specify a parameter that matches the name of the parameter in the template. Verweisen Sie für den Parameterwert auf das Geheimnis aus dem Schlüsseltresor.For the parameter value, reference the secret from the key vault. Sie verweisen auf den geheimen Schlüssel, indem Sie den Ressourcenbezeichner des Schlüsseltresors und den Namen des Geheimnisses übergeben:You reference the secret by passing the resource identifier of the key vault and the name of the secret:

In der folgenden Parameterdatei muss das Schlüsseltresorgeheimnis bereits vorhanden sein, und Sie geben einen statischen Wert für seine Ressourcen-ID an.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>"
      }
  }
}

Wenn Sie den geheimen Schlüssel in einer Version verwenden müssen, die nicht die aktuelle Version ist, verwenden Sie die secretVersion-Eigenschaft.If you need to use a version of the secret other than the current version, use the secretVersion property.

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

Stellen Sie die Vorlage bereit, und übergeben Sie sie in der Parameterdatei: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>

Verweisen auf Geheimnisse mit einer dynamischen IDReference secrets with dynamic ID

Im vorherigen Abschnitt wurde für das Geheimnis des Schlüsseltresors eine statische Ressourcen-ID aus dem Parameter übergeben.The previous section showed how to pass a static resource ID for the key vault secret from the parameter. Manchmal muss jedoch auf einen geheimen Schlüsseltresorschlüssel verwiesen werden, der je nach aktueller Bereitstellung variiert.However, in some scenarios, you need to reference a key vault secret that varies based on the current deployment. Oder Sie möchten Parameterwerte an die Vorlage übergeben, statt einen Referenzparameter in der Parameterdatei zu erstellen.Or, you may want to pass parameter values to the template rather than create a reference parameter in the parameter file. In beiden Fällen können Sie die Ressourcen-ID für ein Schlüsseltresorgeheimnis mithilfe einer verknüpften Vorlage dynamisch erstellen.In either case, you can dynamically generate the resource ID for a key vault secret by using a linked template.

Da in der Parameterdatei keine Vorlagenausdrücke zulässig sind, kann die Ressourcen-ID nicht dynamisch in der Parameterdatei generiert werden.You can't dynamically generate the resource ID in the parameters file because template expressions aren't allowed in the parameters file.

In Ihrer übergeordneten Vorlage fügen Sie die geschachtelte Vorlage hinzu und übergeben einen Parameter, der die dynamisch generierte Ressourcen-ID enthält.In your parent template, you add the nested template and pass in a parameter that contains the dynamically generated resource ID. Die folgende Abbildung zeigt, wie ein Parameter in der verknüpften Vorlage auf das Geheimnis verweist.The following image shows how a parameter in the linked template references the secret.

Dynamische ID

Die folgende Vorlage erstellt dynamisch die Schlüsseltresor-ID und übergibt sie als Parameter.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": "2018-05-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": {
  }
}

Nächste SchritteNext steps