共用方式為


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

本文說明如何在 Bicep 部署期間,使用 Azure 金鑰保存庫 傳遞秘密作為參數。 您可以在部署期間,從 Azure 金鑰保存庫 擷取值,而不是直接輸入密碼之類的安全值到 Bicep 檔案或參數檔案中。

當模組預期已套用修飾詞的secure:true字串參數時,您可以使用 函getSecret式來取得金鑰保存庫密碼。 您不會公開值,因為您只參考其密鑰保存庫識別碼。

重要

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

本文未涵蓋如何將虛擬機 (VM) 屬性設定為金鑰保存庫中憑證的 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. 使用 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() 裝飾項目的參數使用。

您可以使用 Bicep 參數檔案中呼叫 az.getSecret() 的另一個函式來擷取金鑰保存庫秘密。 如需詳細資訊,請參閱 擷取參數檔案中的秘密。

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"