Übergeben eines Geheimnisses als Parameter während der Bicep-Bereitstellung mithilfe von Azure Key Vault
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:
- Festlegen und Abrufen eines Geheimnisses mithilfe der Azure CLI
- Festlegen und Abrufen eines Geheimnisses mithilfe von Azure PowerShell
- Festlegen und Abrufen eines Geheimnisses über das Azure-Portal
- Festlegen und Abrufen eines Geheimnisses mit .NET
- Festlegen und Abrufen eines Geheimnisses mit Node.js
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:
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.
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
- Allgemeine Informationen zu Schlüsseltresoren finden Sie unter Informationen zu Azure Key Vault.
- Vollständige GitHub-Beispiele, die das Verweisen auf Schlüsseltresorgeheimnisse veranschaulichen, finden Sie unter Key Vault-Beispiele.
- Ein Learn-Modul, das die Übergabe eines sicheren Werts mithilfe eines Schlüsseltresors behandelt, finden Sie unter Verwalten komplexer Cloudbereitstellungen mithilfe erweiterter Funktionen von JSON ARM-Vorlagen.