共用方式為

在 Bicep 部署期間，使用 Azure 金鑰保存庫 從金鑰保存庫傳遞秘密作為參數

  • 發行項

您可以在部署期間，從 Azure 金鑰保存庫 擷取值，而不是直接輸入密碼之類的安全值到 Bicep 檔案或參數檔案中。 當模組需要string具有secure:true修飾詞的參數時，您可以使用 函getSecret式來取得密鑰保存庫密碼。 您只參考其金鑰保存庫識別碼，因此該值絕不會公開。

重要

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

本文未涵蓋如何將虛擬機屬性設定為密鑰保存庫中憑證的 URL。 如需該案例的快速入門範本，請參閱 Windows VM 上的 WinRM。

部署金鑰保存庫和祕密

若要在 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. USe 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'
  }
}

參數 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 伺服器。 當 password 參數設定為安全字串時，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"

下一步