Teilen über

Übergeben eines Geheimnisses aus einem Schlüsseltresor als Parameter während der Bicep-Bereitstellung mithilfe von Azure Key Vault

  • 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 Azure Key Vault abrufen. Wenn ein Modul einen string-Parameter mit secure:true-Modifizierer erwartet, können Sie die Funktion getSecret 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 dieses Szenarios finden Sie unter WinRM auf einer Windows-VM.

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 Benutzenden.

  1. Erstellen Sie eine benutzerdefinierte JSON-Datei mit einer Rollendefinition:

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

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

  2. Verwenden Sie die JSON-Datei zum Erstellen der neuen Rolle:

    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 Benutzenden 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 Funktion getSecret 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.

Da die getSecret-Funktion nur im Abschnitt params eines Moduls verwendet werden kann, erstellen Sie eine Datei vom Typ sql.bicep im selben Verzeichnis, in dem sich auch die Datei main.bicep befindet, 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'
  }
}

Der Parameter adminPassword hat in der vorherigen Datei das Decorator-Element @secure().

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 einer Parameterdatei abrufen. Der Ansatz variiert jedoch abhängig davon, ob Sie eine JSON- oder eine Bicep-Parameterdatei verwenden.

Die folgende Bicep-Datei stellt einen SQL-Server bereit, der ein Administratorkennwort enthält. Der Kennwortparameter ist zwar auf eine sichere Zeichenfolge festgelegt, aber Bicep gibt den Ursprung dieses Werts nicht an:

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 als Nächstes 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 einer JSON-Parameterdatei einen Parameter an, der dem Namen des Parameters in der Bicep-Datei entspricht. Sie verweisen für den Parameterwert auf das Geheimnis aus dem Schlüsseltresor. Dazu übergeben Sie den Ressourcenbezeichner des Schlüsseltresors und den Namen des Geheimnisses. 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 eine secretVersion-Eigenschaft ein:

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

Nächste Schritte