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

發行項
03/22/2024

您可以在部署期間從 Azure Key Vault 擷取值，而非將安全值 (例如密碼) 直接放入範本或參數檔案中。您可以藉由參考金鑰保存庫和參數檔案中的密碼來擷取值。您只參考其金鑰保存庫識別碼，因此該值絕不會公開。

重要

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

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

部署金鑰保存庫和祕密

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

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

Azure CLI
PowerShell

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

Set-AzKeyVaultAccessPolicy -VaultName ExampleVault -EnabledForTemplateDeployment

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

Azure CLI
PowerShell

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"

New-AzResourceGroup -Name ExampleGroup -Location centralus
New-AzKeyVault `
  -VaultName ExampleVault `
  -resourceGroupName ExampleGroup `
  -Location centralus `
  -EnabledForTemplateDeployment
$secretvalue = ConvertTo-SecureString 'hVFkk965BuUv' -AsPlainText -Force
$secret = Set-AzKeyVaultSecret -VaultName ExampleVault -Name 'ExamplePassword' -SecretValue $secretvalue

身為金鑰保存庫的擁有者，您會自動擁有建立祕密的存取權。如果您需要讓另一位使用者建立祕密，請使用：

Azure CLI
PowerShell

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

$userPrincipalName = "<Email Address of the deployment operator>"

Set-AzKeyVaultAccessPolicy `
  -VaultName ExampleVault `
  -UserPrincipalName <user-principal-name> `
  -PermissionsToSecrets set,delete,get,list

如果使用者正在部署擷取祕密的範本，則不需要存取原則。只有當使用者需要直接使用祕密時，才需要將該使用者新增至存取原則。部署權限會在下一節中定義。

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

授與祕密的部署存取權

部署範本的使用者必須擁有資源群組範圍和金鑰保存庫的 Microsoft.KeyVault/vaults/deploy/action 權限。透過檢查此存取權，Azure Resource Manager 可透過傳入金鑰保存庫的資源識別碼，來防止未經核准的使用者存取祕密。您可以將部署存取權授與使用者，而不必授與祕密的寫入權限。

擁有者和參與者角色皆可授與此權限。如果金鑰保存庫是由您建立，您就是擁有者並具有權限。

針對其他使用者，請授與 Microsoft.KeyVault/vaults/deploy/action 權限。下列程序說明如何建立具有最低權限的角色，並將其指派給使用者。

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

{
  "Name": "Key Vault resource manager template deployment operator",
  "IsCustom": true,
  "Description": "Lets you deploy a resource manager template 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"
  ]
}

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

使用 JSON 檔案建立新的角色：

Azure CLI
PowerShell

az role definition create --role-definition "<path-to-role-file>"
az role assignment create \
  --role "Key Vault resource manager template deployment operator" \
  --scope /subscriptions/<Subscription-id>/resourceGroups/<resource-group-name> \
  --assignee <user-principal-name> \
  --resource-group ExampleGroup

New-AzRoleDefinition -InputFile "<path-to-role-file>"
New-AzRoleAssignment `
  -ResourceGroupName ExampleGroup `
  -RoleDefinitionName "Key Vault resource manager template deployment operator" `
  -SignInName <user-principal-name>

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

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

使用靜態識別碼參考祕密

透過這個方法，您可參考參數檔案中的金鑰保存庫，而非範本。下圖顯示參數檔案如何參考祕密，並將該值傳遞至範本。

Diagram showing Resource Manager key vault integration with Static ID.

教學課程：在 Resource Manager 範本部署中整合 Azure Key Vault 會使用此方法。

下列範本會部署包含管理員密碼的 SQL 伺服器。密碼參數會設定為安全字串。但是，範本並未指定該值來自何處。

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "sqlServerName": {
      "type": "string"
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    },
    "adminLogin": {
      "type": "string"
    },
    "adminPassword": {
      "type": "securestring"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Sql/servers",
      "apiVersion": "2021-11-01",
      "name": "[parameters('sqlServerName')]",
      "location": "[parameters('location')]",
      "properties": {
        "administratorLogin": "[parameters('adminLogin')]",
        "administratorLoginPassword": "[parameters('adminPassword')]",
        "version": "12.0"
      }
    }
  ]
}

現在，請為前述範本建立參數檔案。在參數檔案中，指定符合範本中參數名稱的參數。針對參數值，參考來自金鑰保存庫的密碼。您可以藉由傳遞金鑰保存庫的資源識別碼和密碼的名稱來參考密碼：

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

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "adminLogin": {
      "value": "exampleadmin"
    },
    "adminPassword": {
      "reference": {
        "keyVault": {
          "id": "/subscriptions/<subscription-id>/resourceGroups/<rg-name>/providers/Microsoft.KeyVault/vaults/<vault-name>"
        },
        "secretName": "ExamplePassword"
      }
    },
    "sqlServerName": {
      "value": "<your-server-name>"
    }
  }
}

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

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

部署範本並在參數檔案中傳遞：

Azure CLI
PowerShell

az group create --name SqlGroup --location westus2
az deployment group create \
  --resource-group SqlGroup \
  --template-uri <template-file-URI> \
  --parameters <parameter-file>

New-AzResourceGroup -Name $resourceGroupName -Location $location
New-AzResourceGroupDeployment `
  -ResourceGroupName $resourceGroupName `
  -TemplateUri <template-file-URI> `
  -TemplateParameterFile <parameter-file>

使用動態識別碼參考祕密

上一節已說明如何從參數傳遞金鑰保存庫秘密的靜態資源識別碼。在某些情況下，您需要參考會隨目前部署而變化的金鑰保存庫祕密。或者，您可以將參數值傳遞至範本，而不要在參數檔案中建立傳址參數。解決方案是使用連結的範本，以動態方式產生金鑰保存庫祕密的資源識別碼。

由於參數檔中不允許使用範本運算式，因此您無法在參數檔中以動態方式產生資源識別碼。

在父範本中，您會新增巢狀範本，並傳入包含動態產生之資源識別碼的參數。下圖顯示連結的範本中的參數如何參考祕密。

Diagram illustrating dynamic ID generation for key vault secret.

下列範本會動態建立金鑰保存庫識別碼，並將其當作參數傳遞。

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
      "location": {
        "type": "string",
        "defaultValue": "[resourceGroup().location]",
        "metadata": {
          "description": "The location where the resources will be deployed."
        }
      },
      "vaultName": {
        "type": "string",
        "metadata": {
          "description": "The name of the keyvault that contains the secret."
        }
      },
      "secretName": {
        "type": "string",
        "metadata": {
          "description": "The name of the secret."
        }
      },
      "vaultResourceGroupName": {
        "type": "string",
        "metadata": {
          "description": "The name of the resource group that contains the keyvault."
        }
      },
      "vaultSubscription": {
        "type": "string",
        "defaultValue": "[subscription().subscriptionId]",
        "metadata": {
          "description": "The name of the subscription that contains the keyvault."
        }
      }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2020-10-01",
      "name": "dynamicSecret",
      "properties": {
        "mode": "Incremental",
        "expressionEvaluationOptions": {
          "scope": "inner"
        },
        "template": {
          "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
          "contentVersion": "1.0.0.0",
          "parameters": {
            "adminLogin": {
              "type": "string"
            },
            "adminPassword": {
              "type": "securestring"
            },
            "location": {
              "type": "string"
            }
          },
          "variables": {
            "sqlServerName": "[concat('sql-', uniqueString(resourceGroup().id, 'sql'))]"
          },
          "resources": [
            {
              "type": "Microsoft.Sql/servers",
              "apiVersion": "2021-11-01",
              "name": "[variables('sqlServerName')]",
              "location": "[parameters('location')]",
              "properties": {
                "administratorLogin": "[parameters('adminLogin')]",
                "administratorLoginPassword": "[parameters('adminPassword')]"
              }
            }
          ],
          "outputs": {
            "sqlFQDN": {
              "type": "string",
              "value": "[reference(variables('sqlServerName')).fullyQualifiedDomainName]"
            }
          }
        },
        "parameters": {
          "location": {
            "value": "[parameters('location')]"
          },
          "adminLogin": {
            "value": "ghuser"
          },
          "adminPassword": {
            "reference": {
              "keyVault": {
                "id": "[resourceId(parameters('vaultSubscription'), parameters('vaultResourceGroupName'), 'Microsoft.KeyVault/vaults', parameters('vaultName'))]"
              },
              "secretName": "[parameters('secretName')]"
            }
          }
        }
      }
    }
  ]
}

下一步

如需金鑰保存庫的一般資訊，請參閱什麼是 Azure Key Vault？
如需參考金鑰秘密的完整範例，請參閱 GitHub 上的金鑰保存庫範例。
如需說明從金鑰保存庫傳遞安全值的 Learn 模組，請參閱使用進階 ARM 範本功能，管理複雜的雲端部署。

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

部署金鑰保存庫和祕密

授與祕密的部署存取權

使用靜態識別碼參考祕密

使用動態識別碼參考祕密

下一步

其他資源