Używanie usługi Azure Key Vault do przekazywania wartości bezpiecznego parametru podczas wdrażania aplikacji Bicep

  • Artykuł

Zamiast umieszczać bezpieczną wartość (np. hasło) bezpośrednio w pliku lub pliku parametrów Bicep, możesz pobrać wartość z usługi Azure Key Vault podczas wdrażania. Gdy moduł oczekuje parametru string z secure:true modyfikatorem, możesz użyć funkcji getSecret, aby uzyskać wpis tajny magazynu kluczy. Wartość nigdy nie jest uwidoczniana, ponieważ używane jest tylko odwołanie do jej identyfikatora magazynu kluczy.

Ważne

W tym artykule opisano sposób przekazywania poufnej wartości jako parametru szablonu. Gdy wpis tajny jest przekazywany jako parametr, magazyn kluczy może istnieć w innej subskrypcji niż wdrażana grupa zasobów.

W tym artykule nie opisano sposobu ustawiania właściwości maszyny wirtualnej na adres URL certyfikatu w magazynie kluczy. Aby zapoznać się z szablonem szybkiego startu tego scenariusza, zobacz Instalowanie certyfikatu z usługi Azure Key Vault na maszynie wirtualnej.

Wdrażanie magazynów kluczy i wpisów tajnych

Aby uzyskać dostęp do magazynu kluczy podczas wdrażania Bicep, ustaw dla enabledForTemplateDeployment magazynu kluczy wartość true.

Jeśli masz już magazyn kluczy, upewnij się, że zezwala na wdrożenia szablonów.

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

Aby utworzyć nowy magazyn kluczy i dodać wpis tajny, użyj:

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"

Jako właściciel magazynu kluczy masz automatycznie dostęp do tworzenia wpisów tajnych. Jeśli użytkownik pracujący z wpisami tajnymi nie jest właścicielem magazynu kluczy, udziel dostępu:

az keyvault set-policy \
  --upn <user-principal-name> \
  --name ExampleVault \
  --secret-permissions set delete get list

Aby uzyskać więcej informacji na temat tworzenia magazynów kluczy i dodawania wpisów tajnych, zobacz:

Udzielanie dostępu do wpisów tajnych

Użytkownik, który wdraża plik Bicep, musi mieć Microsoft.KeyVault/vaults/deploy/action uprawnienie do zakresu grupy zasobów i magazynu kluczy. Role Właściciel i Współautor przyznają ten dostęp. Jeśli utworzono magazyn kluczy, jesteś właścicielem i masz uprawnienie.

Poniższa procedura pokazuje, jak utworzyć rolę z minimalnym uprawnieniem oraz jak przypisać użytkownika.

  1. Utwórz plik JSON definicji roli niestandardowej:

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

    Zastąp wartość "00000000-0000-0000-0000-000000000000" identyfikatorem subskrypcji.

  2. Utwórz nową rolę przy użyciu pliku JSON:

    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>

    Przykłady przypisują rolę niestandardową do użytkownika na poziomie grupy zasobów.

W przypadku korzystania z magazynu kluczy z plikiem Bicep dla aplikacji zarządzanej należy udzielić dostępu do jednostki usługi dostawcy zasobów urządzenia. Aby uzyskać więcej informacji, zobacz Access Key Vault secret when deploying Azure Managed Applications (Uzyskiwanie dostępu do wpisu tajnego usługi Key Vault podczas wdrażania aplikacji zarządzanych platformy Azure).

Pobieranie wpisów tajnych w pliku Bicep

Aby uzyskać wpis tajny magazynu kluczy, możesz użyć funkcji getSecret w plikach Bicep. Należy pamiętać, że getSecret funkcja ma zastosowanie wyłącznie do Microsoft.KeyVault/vaults zasobu. Ponadto jest on ograniczony do użycia w params sekcji modułu i może być używany tylko z parametrami z dekoratorem @secure() .

Inna funkcja o nazwie az.getSecret() function może służyć w plikach parametrów Bicep do pobierania wpisów tajnych magazynu kluczy. Aby uzyskać więcej informacji, zobacz Pobieranie wpisów tajnych w pliku parametrów.

getSecret Ponieważ funkcja może być używana tylko w params sekcji modułu. Utwórzmy plik sql.bicep w tym samym katalogu co plik main.bicep o następującej zawartości:

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

Zwróć uwagę, że w poprzednim pliku adminPassword Bicep parametr ma @secure() dekorator.

Poniższy plik Bicep używa pliku sql.bicep jako modułu. Plik Bicep odwołuje się do istniejącego magazynu kluczy i wywołuje getSecret funkcję w celu pobrania wpisu tajnego magazynu kluczy, a następnie przekazuje wartość jako parametr do modułu.

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

Pobieranie wpisów tajnych w pliku parametrów

Jeśli nie chcesz używać modułu, możesz pobrać wpisy tajne magazynu kluczy w pliku parametrów. Jednak podejście różni się w zależności od tego, czy używasz pliku parametrów JSON, czy pliku parametrów Bicep.

Poniższy plik Bicep wdraża serwer SQL zawierający hasło administratora. Parametr hasła jest ustawiony na bezpieczny ciąg. Ale Bicep nie określa, skąd pochodzi ta wartość.

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

Teraz utwórz plik parametrów dla poprzedniego pliku Bicep.

Plik parametrów Bicep

az.getSecret funkcja może służyć w .bicepparam pliku do pobierania wartości wpisu tajnego z magazynu kluczy.

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

Plik parametrów JSON

W pliku parametrów JSON określ parametr zgodny z nazwą parametru w pliku Bicep. W przypadku wartości parametru należy odwołać się do wpisu tajnego z magazynu kluczy. Odwołujesz się do wpisu tajnego, przekazując identyfikator zasobu magazynu kluczy i nazwę wpisu tajnego:

W poniższym pliku parametrów wpis tajny magazynu kluczy musi już istnieć i należy podać wartość statyczną dla jego identyfikatora zasobu.

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

Jeśli musisz użyć wersji wpisu tajnego innej niż bieżąca wersja, dołącz secretVersion właściwość .

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

Następne kroki