Share via

Verwenden von Azure Key Vault zum Übergeben eines sicheren Parameterwerts während der Bicep-Bereitstellung

  • Artikel

Anstatt einen sicheren Wert (wie ein Kennwort) direkt in Ihre Bicep-Datei oder Parameterdatei einzufügen, können Sie den Wert während einer Bereitstellung aus einem Azure Key Vault abrufen. Wenn ein Modul einen string-Parameter mit secure:true-Modifizierer erwartet, können Sie die getSecret-Funktion verwenden, um ein Schlüsseltresorgeheimnis abzurufen. Der Wert wird nie offengelegt, da Sie nur auf die Schlüsseltresor-ID verweisen.

Wichtig

Der Schwerpunkt dieses Artikels liegt auf der Übergabe eines vertraulichen Werts als Vorlagenparameter. Wenn das Geheimnis als Parameter übergeben wird, kann sich der Schlüsseltresor in einem anderen Abonnement befinden als die Ressourcengruppe, die als Ziel für die Bereitstellung verwendet wird.

In diesem Artikel wird nicht erläutert, wie Sie eine VM-Eigenschaft auf die URL eines Zertifikats in einem Schlüsseltresor festlegen. Eine Schnellstartvorlage für dieses Szenario finden Sie unter Installieren eines Zertifikats aus Azure Key Vault auf einem virtuellen Computer.

Bereitstellen von Schlüsseltresoren und Geheimnissen

Um während der Bicep-Bereitstellung auf einen Schlüsseltresor zuzugreifen, legen Sie enabledForTemplateDeployment für den Schlüsseltresor auf true fest.

Wenn Sie bereits über einen Schlüsseltresor verfügen, stellen Sie sicher, dass er Vorlagenbereitstellungen zulässt.

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

Um einen neuen Schlüsseltresor zu erstellen und ein Geheimnis hinzuzufügen, verwenden Sie:

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. Wenn der Benutzer, der mit Geheimnissen arbeitet, nicht der Besitzer des Schlüsseltresors ist, gewähren Sie den Zugriff mit:

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:

Gewähren des Zugriffs auf die Geheimnisse

Der Benutzer, der die Bicep-Datei bereitstellt, muss die Berechtigung Microsoft.KeyVault/vaults/deploy/action für den Bereich der Ressourcengruppe und des Schlüsseltresors besitzen. Die Rollen Besitzer und Mitwirkender gewähren diesen Zugriff. Wenn Sie den Schlüsseltresor erstellt haben, sind Sie der Besitzer und verfügen somit über die Berechtigung.

Das folgende Verfahren zeigt das Erstellen einer Rolle mit der Mindestberechtigung und das Zuweisen des Benutzers.

  1. Erstellen einer benutzerdefinierten Rollendefinition (JSON-Datei):

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

    Ersetzen Sie „00000000-0000-0000-0000-000000000000“ durch die Abonnement-ID.

  2. Erstellen Sie die neue Rolle mithilfe der JSON-Datei:

    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>

    Die Beispiele weisen dem Benutzer auf Ressourcengruppenebene die benutzerdefinierte Rolle zu.

Wenn Sie einen Schlüsseltresor mit der Bicep-Datei für eine verwaltete Anwendung verwenden, müssen Sie den Zugriff auf den Geräte-Ressourcenanbieter-Dienstprinzipal gewähren. Weitere Informationen finden Sie unter Zugreifen auf das Geheimnis im Schlüsseltresor bei der Bereitstellung von Azure Managed Applications.

Abrufen von Geheimnissen in der Bicep-Datei

Sie können die getSecret-Funktion in Bicep-Dateien verwenden, um ein Schlüsseltresorgeheimnis abzurufen. Beachten Sie, dass die getSecret-Funktion ausschließlich für eine Microsoft.KeyVault/vaults-Ressource gilt. Darüber hinaus ist sie auf die Verwendung innerhalb des Abschnitts params eines Moduls beschränkt und kann nur mit Parametern mit dem Decorator-Element @secure() verwendet werden.

Eine andere Funktion namens az.getSecret() kann in Bicep-Parameterdateien zum Abrufen von Schlüsseltresorgeheimnissen verwendet werden. Weitere Informationen finden Sie unter Abrufen von Geheimnissen in der Parameterdatei.

Die Funktion getSecret kann nur innerhalb des Abschnitts params eines Moduls verwendet werden. Erstellen Sie daher eine Datei vom Typ sql.bicep im selben Verzeichnis wie die Datei main.bicep mit folgendem Inhalt:

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

Beachten Sie in der vorherigen Bicep-Datei, dass der Parameter adminPassword das Decorator-Element @secure() hat.

Die folgende Bicep-Datei verwendet sql.bicep als Modul. Die Bicep-Datei verweist auf einen vorhandenen Schlüsseltresor, ruft die getSecret-Funktion auf, um das Schlüsseltresorgeheimnis abzurufen, und übergibt den Wert dann als Parameter an das Modul.

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

Abrufen von Geheimnissen in einer Parameterdatei

Wenn Sie kein Modul verwenden möchten, können Sie Schlüsseltresorgeheimnnisse in der Parameterdatei abrufen. Der Ansatz variiert jedoch abhängig davon, ob Sie eine JSON-Parameterdatei oder eine Bicep-Parameterdatei verwenden.

Die folgende Bicep-Datei stellt einen SQL-Server bereit, der ein Administratorkennwort enthält. Der Kennwortparameter ist auf eine sichere Zeichenfolge festgelegt. Die Bicep-Datei gibt jedoch nicht an, woher dieser Wert stammt.

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

Erstellen Sie jetzt eine Parameterdatei für die vorherige Bicep-Datei.

Bicep-Parameterdatei

Die Funktion az.getSecret kann in einer .bicepparam-Datei verwendet werden, um den Wert eines Geheimnisses aus einem Schlüsseltresor abzurufen.

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-Parameterdatei

Geben Sie in der JSON-Parameterdatei einen Parameter an, der dem Namen des Parameters in der Bicep-Datei entspricht. Verweisen Sie für den Parameterwert auf das Geheimnis aus dem Schlüsseltresor. Sie verweisen auf den geheimen Schlüssel, indem Sie den Ressourcenbezeichner des Schlüsseltresors und den Namen des Geheimnisses übergeben:

In der folgenden Parameterdatei muss das Schlüsseltresorgeheimnis bereits vorhanden sein, und Sie geben einen statischen Wert für seine Ressourcen-ID an.

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

Wenn Sie eine andere Version des Geheimnisses als die aktuelle Version verwenden müssen, fügen Sie die secretVersionEigenschaft ein.

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

Nächste Schritte