Freigeben über

Übergeben eines Geheimnisses als Parameter während der Bicep-Bereitstellung mithilfe von Azure Key Vault

  • Artikel

In diesem Artikel erfahren Sie, wie Sie mithilfe von Azure Key Vault während der Bicep-Bereitstellung ein Geheimnis als Parameter übergeben. 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 Zeichenfolgenparameter mit angewendetem secure:true-Modifizierer erwartet, können Sie die getSecret-Funktion verwenden, um ein Schlüsseltresorgeheimnis abzurufen. Der Wert wird nie verfügbar gemacht, 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 besitzende Person des Schlüsseltresors haben Sie automatisch Zugriff zum Erstellen von Geheimnissen. Wenn die benutzende Person, die mit Geheimnissen arbeitet, nicht die besitzende Person 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 der benutzenden Person:

  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 vorherigen Beispiele weisen der benutzenden Person die benutzerdefinierte Rolle auf Ressourcengruppenebene zu.

Wenn Sie einen Schlüsseltresor mit einer Bicep-Datei für eine verwaltete Anwendung verwenden, müssen Sie Zugriff auf den Dienstprinzipal Applianceressourcenanbieter 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 einer Bicep-Datei

Sie können die Funktion getSecret in einer Bicep-Datei verwenden, um ein Schlüsseltresorgeheimnis abzurufen. Die Funktion getSecret kann nur mit einer Microsoft.KeyVault/vaults-Ressource verwendet werden. Darüber hinaus kann sie nur innerhalb des Abschnitts params eines Moduls und nur mit Parametern verwendet werden, die das Decorator-Element @secure() aufweisen.

Sie können eine andere Funktion namens az.getSecret() kann in einer Bicep-Parameterdatei zum Abrufen von Schlüsseltresorgeheimnissen verwenden. Weitere Informationen finden Sie unter Abrufen von Geheimnissen in einer 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 Datei vom Typ .bicepparam 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. Verweisen Sie für den Parameterwert auf das Geheimnis aus dem Schlüsseltresor. Übergeben Sie die Ressourcen-ID des Schlüsseltresors und den Namen des Geheimnisses. In der folgenden Parameterdatei muss das Schlüsseltresorgeheimnis bereits vorhanden sein. Sie geben einen statischen Wert für die 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"

Zugehöriger Inhalt