共用方式為

使用 Azure Key Vault，在 Bicep 部署期間傳遞安全參數值

  • 發行項

您可以在部署期間從 Azure Key Vault 擷取值，而不要將安全的值 (例如密碼) 直接放入 Bicep 檔案或參數檔案中。 模組需要具有 secure:true 修飾元的 string 參數時，您可以使用 getSecret 函式取得金鑰保存庫祕密。 您只參考其金鑰保存庫識別碼，因此該值絕不會公開。

重要

本文著重於如何以範本參數的形式傳遞敏感值。 將祕密做為參數傳遞時，金鑰保存庫可以存在於不同的訂用帳戶，而不是在要部署的資源群組中。

本文不會說明如何將虛擬機器屬性，設為金鑰保存庫中的憑證 URL。 如需該案例的快速入門範本，請參閱在虛擬機器上安裝 Azure Key Vault 的憑證。

部署金鑰保存庫和祕密

若要在 Bicep 部署期間存取金鑰保存庫，請在金鑰保存庫上將 enabledForTemplateDeployment 設為 true。

如果您已具有金鑰保存庫，請確定其允許範本部署作業。

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

若要建立新的金鑰保存庫並新增祕密，請使用：

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"

身為金鑰保存庫的擁有者，您會自動擁有建立祕密的存取權。 如果使用祕密的使用者不是金鑰保存庫的擁有者，則請授與下列存取權：

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

如需建立金鑰保存庫和新增祕密的詳細資訊，請參閱：

授與祕密的存取權

部署 Bicep 檔案的使用者，必須擁有資源群組範圍和金鑰保存庫的 Microsoft.KeyVault/vaults/deploy/action 權限。 擁有者和參與者角色皆可授與此權限。 如果金鑰保存庫是由您所建立，您便是具有權限的金鑰保存庫擁有者。

下列程序說明如何建立具有最低權限的角色，以及如何指派使用者。

  1. 建立自訂角色定義 JSON 檔案：

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

    以訂閱識別碼取代 "00000000-0000-0000-0000-000000000000"。

  2. 使用 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>

    這些範例會在資源群組層級上，將自訂角色指派給使用者。

將金鑰保存庫與受控應用程式的 Bicep 檔案搭配使用時，您必須授與設備資源提供者服務主體的存取權。 如需詳細資訊，請參閱在部署 Azure 受控應用程式時存取金鑰保存庫密碼 (英文)。

擷取 Bicep 檔案中的秘密

您可以使用 Bicep 檔案中的 getSecret 函 式來取得金鑰保存庫秘密。 請注意，函 getSecret 式完全適用於 Microsoft.KeyVault/vaults 資源。 此外，它僅限於在模組的 params 區段中使用，而且只能與裝飾專案搭配 @secure() 參數使用。

另一個稱為 az.getSecret() function 的函式可用於 Bicep 參數檔案，以擷取密鑰保存庫秘密。 如需詳細資訊，請參閱 擷取參數檔案中的秘密。

因為函 getSecret 式只能在模組的 區段中使用 params 。 讓我們使用下列內容，在與 main.bicep 檔案相同的目錄中建立 sql.bicep：

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

請注意，在上述 Bicep 檔案中， adminPassword 參數具有 @secure() 裝飾專案。

下列 Bicep 檔案會 使用 sql.bicep 作為模組。 Bicep 檔案會參考現有的金鑰保存庫，並呼叫 getSecret 函式，以擷取金鑰保存庫祕密，將作為參數的值傳遞至模組。

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

擷取參數檔案中的秘密

如果您不想使用模組，您可以在參數檔案中擷取密鑰保存庫秘密。 不過，方法會根據您使用的是 JSON 參數檔案或 Bicep 參數檔案而有所不同。

下列 Bicep 檔案會部署包含管理員密碼的 SQL 伺服器。 密碼參數會設定為安全字串。 但是 Bicep 不會指定該值的來源。

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

您現在可為前述的 Bicep 檔案建立參數檔案。

Bicep 參數檔案

az.getSecret 函式可用於檔案中 .bicepparam ，從密鑰保存庫擷取秘密的值。

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 參數檔案

在 JSON 參數檔案中，指定符合 Bicep 檔案中參數名稱的參數。 針對參數值，參考來自金鑰保存庫的密碼。 您可以藉由傳遞金鑰保存庫的資源識別碼和密碼的名稱來參考密碼：

在下列參數檔案中，金鑰保存庫祕密必須已經存在，而且您要針對其資源識別碼提供靜態值。

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

如果您需要使用目前版本以外的祕密版本，請包含 secretVersion 屬性。

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

下一步