デプロイ時に Azure Key Vault を使用して、セキュリティで保護されたパラメーター値を渡すUse Azure Key Vault to pass secure parameter value during deployment

お使いのテンプレートやパラメーター ファイルに安全な値 (パスワードなど) を直接入れる代わりに、デプロイ時に、Azure Key Vault から値を取得できます。Instead of putting a secure value (like a password) directly in your template or parameter file, you can retrieve the value from an Azure Key Vault during a deployment. 値を取得するには、キー コンテナーとパラメーター ファイル内のシークレットを参照します。You retrieve the value by referencing the key vault and secret in your parameter file. 参照するのは Key Vault ID だけであるため、値が公開されることはありません。The value is never exposed because you only reference its key vault ID. キー コンテナーは、デプロイ先のリソース グループとは異なるサブスクリプションにあってもかまいません。The key vault can exist in a different subscription than the resource group you're deploying to.

キー コンテナーとシークレットをデプロイするDeploy key vaults and secrets

テンプレートのデプロイ時にキー コンテナーにアクセスするには、キー コンテナーの enabledForTemplateDeploymenttrue に設定します。To access a key vault during template deployment, set enabledForTemplateDeployment on the key vault to true.

Azure CLI と Azure PowerShell の次のサンプルは、キー コンテナーの作成方法と、シークレットの追加方法を示しています。The following Azure CLI and Azure PowerShell samples show how to create the key vault, and add a secret.

az group create --name $resourceGroupName --location $location
az keyvault create \
  --name $keyVaultName \
  --resource-group $resourceGroupName \
  --location $location \
  --enabled-for-template-deployment true
az keyvault secret set --vault-name $keyVaultName --name "ExamplePassword" --value "hVFkk965BuUv"
New-AzResourceGroup -Name $resourceGroupName -Location $location
New-AzKeyVault `
  -VaultName $keyVaultName `
  -resourceGroupName $resourceGroupName `
  -Location $location `
  -EnabledForTemplateDeployment
$secretvalue = ConvertTo-SecureString 'hVFkk965BuUv' -AsPlainText -Force
$secret = Set-AzKeyVaultSecret -VaultName $keyVaultName -Name 'ExamplePassword' -SecretValue $secretvalue

キー コンテナーの所有者には、シークレットを作成するアクセスが自動的に付与されています。As the owner of the key vault, you automatically have access to creating secrets. シークレットを操作しているユーザーが、そのキー コンテナーの所有者でない場合、次を使用してアクセス許可を付与します。If the user working with secrets isn't the owner of the key vault, grant access with:

az keyvault set-policy \
  --upn $userPrincipalName \
  --name $keyVaultName \
  --secret-permissions set delete get list
$userPrincipalName = "<Email Address of the deployment operator>"

Set-AzKeyVaultAccessPolicy `
  -VaultName $keyVaultName `
  -UserPrincipalName $userPrincipalName `
  -PermissionsToSecrets set,delete,get,list

キー コンテナーの作成とシークレットの追加の詳細については、次を参照してください。For more information about creating key vaults and adding secrets, see:

シークレットへのアクセスを許可するGrant access to the secrets

テンプレートをデプロイするユーザーには、そのリソース グループとキー コンテナーのスコーで Microsoft.KeyVault/vaults/deploy/action のアクセス許可がある必要があります。The user who deploys the template must have the Microsoft.KeyVault/vaults/deploy/action permission for the scope of the resource group and key vault. このアクセスは、所有者ロールと共同作成者ロールが許可します。The Owner and Contributor roles both grant this access. キー コンテナーの作成者である場合は、その所有者であるため、そのアクセス許可を持っています。If you created the key vault, you're the owner so you have the permission.

次の手順は、最小限のアクセス許可を持つロールを作成する方法と、ユーザーを割り当てる方法を示しますThe following procedure shows how to create a role with the minimum permission, and how to assign the user

  1. カスタム ロール定義の JSON ファイルを作成します。Create a custom role definition JSON file:

    {
      "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" はサブスクリプション ID に置き換えます。Replace "00000000-0000-0000-0000-000000000000" with the subscription ID.

  2. JSON ファイルを使用して新しいロールを作成します。Create the new role using the JSON file:

    az role definition create --role-definition "<PathToRoleFile>"
    az role assignment create \
      --role "Key Vault resource manager template deployment operator" \
      --assignee $userPrincipalName \
      --resource-group $resourceGroupName
    
    New-AzRoleDefinition -InputFile "<PathToRoleFile>" 
    New-AzRoleAssignment `
      -ResourceGroupName $resourceGroupName `
      -RoleDefinitionName "Key Vault resource manager template deployment operator" `
      -SignInName $userPrincipalName
    

    このサンプルでは、リソース グループ レベルでカスタム ロールを割り当てます。The samples assign the custom role to the user on the resource group level.

Managed Applications のテンプレートで Key Vault を使用する場合は、アプライアンス リソース プロバイダー サービス プリンシパルにアクセス許可を付与する必要があります。When using a Key Vault with the template for a Managed Application, you must grant access to the Appliance Resource Provider service principal. 詳細については、「Access Key Vault secret when deploying Azure Managed Applications」(Azure Managed Applications のデプロイ時に Key Vault シークレットにアクセスする) を参照してください。For more information, see Access Key Vault secret when deploying Azure Managed Applications.

固定 ID でのシークレットの参照Reference secrets with static ID

この手法では、テンプレートではなく、パラメーター ファイルでキー コンテナーを参照します。With this approach, you reference the key vault in the parameter file, not the template. 次の図は、パラメーター ファイルがシークレットを参照し、その値をテンプレートに渡すしくみを示しています。The following image shows how the parameter file references the secret and passes that value to the template.

Resource Manager キー コンテナー統合の固定 ID の図

チュートリアル:Resource Manager テンプレートのデプロイで Azure Key Vault を統合する」では、この手法が利用されます。Tutorial: Integrate Azure Key Vault in Resource Manager Template deployment uses this method.

次のテンプレートでは、管理者パスワードを含む SQL サーバーがデプロイされます。The following template deploys a SQL server that includes an administrator password. パスワード パラメーターは、セキュリティで保護された文字列に設定されます。The password parameter is set to a secure string. しかし、テンプレートには値がどこから来ているかが指定されていません。But, the template doesn't specify where that value comes from.

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

ここで、前のテンプレートのためにパラメーター ファイルを作成します。Now, create a parameter file for the preceding template. このパラメーター ファイルで、テンプレート内のパラメーターの名前に一致するパラメーターを指定します。In the parameter file, specify a parameter that matches the name of the parameter in the template. パラメーター値のために、キー コンテナーのシークレットを参照します。For the parameter value, reference the secret from the key vault. シークレットを参照するには、Key Vault のリソース識別子とシークレットの名前を渡します。You reference the secret by passing the resource identifier of the key vault and the name of the secret:

次のパラメーター ファイルには、キー コンテナーのシークレットが既に存在している必要があり、そのリソース ID に対して静的な値を指定します。In the following parameter file, the key vault secret must already exist, and you provide a static value for its resource ID.

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-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 プロパティを使用します。If you need to use a version of the secret other than the current version, use the secretVersion property.

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

テンプレートをデプロイし、パラメーター ファイルを渡します。Deploy the template and pass in the parameter file:

Azure CLI では、次を使用します。For Azure CLI, use:

az group create --name $resourceGroupName --location $location
az group deployment create \
    --resource-group $resourceGroupName \
    --template-uri <The Template File URI> \
    --parameters <The Parameter File>

PowerShell では、次を使用します。For PowerShell, use:

New-AzResourceGroup -Name $resourceGroupName -Location $location
New-AzResourceGroupDeployment `
  -ResourceGroupName $resourceGroupName `
  -TemplateUri <The Template File URI> `
  -TemplateParameterFile <The Parameter File>

動的 ID でのシークレットの参照Reference secrets with dynamic ID

前のセクションでは、Key Vault シークレットの静的リソース ID をパラメーターから渡す方法について説明しました。The previous section showed how to pass a static resource ID for the key vault secret from the parameter. しかし参照すべき Key Vault シークレットがデプロイごとに変わる状況も考えられます。However, in some scenarios, you need to reference a key vault secret that varies based on the current deployment. または、パラメーター ファイルに参照パラメーターを作成するのではなく、テンプレートでパラメーター値を渡すこともできます。Or, you may want to pass parameter values to the template rather than create a reference parameter in the parameter file. いずれの場合でも、リンクされたテンプレートを使用して、キー コンテナー シークレットのリソース ID を動的に生成することができます。In either case, you can dynamically generate the resource ID for a key vault secret by using a linked template.

パラメーター ファイルではテンプレート式が使用できないので、パラメーター ファイルでリソース ID を動的に生成することはできません。You can't dynamically generate the resource ID in the parameters file because template expressions aren't allowed in the parameters file.

親テンプレートに、そのリンクされたテンプレートを追加し、動的に生成されたリソース ID をパラメーターに格納して渡します。In your parent template, you add the linked template and pass in a parameter that contains the dynamically generated resource ID. 次の図は、リンクされたテンプレート内のパラメーターがシークレットを参照するしくみを示しています。The following image shows how a parameter in the linked template references the secret.

動的 ID

次のテンプレートは、動的に key vault ID を作成し、パラメーターとして渡します。The following template dynamically creates the key vault ID and passes it as a parameter.

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-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."
            }
        },
        "_artifactsLocation": {
            "type": "string",
            "metadata": {
                "description": "The base URI where artifacts required by this template are located. When the template is deployed using the accompanying scripts, a private location in the subscription will be used and this value will be automatically generated."
            },
            "defaultValue": "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/201-key-vault-use-dynamic-id/"
        },
        "_artifactsLocationSasToken": {
            "type": "securestring",
            "metadata": {
                "description": "The sasToken required to access _artifactsLocation.  When the template is deployed using the accompanying scripts, a sasToken will be automatically generated."
            },
            "defaultValue": ""
        }
    },
    "resources": [
        {
            "apiVersion": "2018-05-01",
            "name": "dynamicSecret",
            "type": "Microsoft.Resources/deployments",
            "properties": {
                "mode": "Incremental",
                "templateLink": {
                    "contentVersion": "1.0.0.0",
                    "uri": "[uri(parameters('_artifactsLocation'), concat('./nested/sqlserver.json', parameters('_artifactsLocationSasToken')))]"
                },
                "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')]"
                        }
                    }
                }
            }
        }
    ],
    "outputs": {
        "sqlFQDN": {
            "type": "string",
            "value": "[reference('dynamicSecret').outputs.sqlFQDN.value]"
        }
    }
}

上記のテンプレートをデプロイし、パラメーターの値を指定します。Deploy the preceding template, and provide values for the parameters. GitHub のサンプル テンプレートを使用できますが、環境に合わせたパラメーター値を指定する必要があります。You can use the example template from GitHub, but you must provide parameter values for your environment.

Azure CLI では、次を使用します。For Azure CLI, use:

az group create --name $resourceGroupName --location $location
az group deployment create \
    --resource-group $resourceGroupName \
    --template-uri https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/201-key-vault-use-dynamic-id/azuredeploy.json \
    --parameters vaultName=$keyVaultName vaultResourceGroupName=examplegroup secretName=examplesecret

PowerShell では、次を使用します。For PowerShell, use:

New-AzResourceGroup -Name $resourceGroupName -Location $location
New-AzResourceGroupDeployment `
  -ResourceGroupName $resourceGroupName `
  -TemplateUri https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/201-key-vault-use-dynamic-id/azuredeploy.json `
  -vaultName $keyVaultName -vaultResourceGroupName $keyVaultResourceGroupName -secretName $secretName

次の手順Next steps