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. 매개 변수 파일에서 Key Vault 및 비밀을 참조하여 이 값을 검색합니다.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.

관리되는 애플리케이션 템플릿과 함께 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

이 방식을 사용할 때는 템플릿이 아닌 매개 변수 파일에서 Key Vault를 참조합니다.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 Key Vault 통합 정적 ID 다이어그램

자습서: 리소스 관리자 템플릿 배포에서 Azure Key Vault를 통합 하는 방법을 사용 합니다.Tutorial: Integrate Azure Key Vault in Resource Manager Template deployment uses this method.

다음 템플릿은 관리자 암호를 포함 하는 SQL server를 배포 합니다.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. 매개 변수 값으로는 Key Vault의 비밀을 참조합니다.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. 하지만, 일부 시나리오에서는, 현재 배포를 기반으로 달라지는 키 자격 증명 모음 암호를 참조해야 합니다.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. 두 경우 모두 링크된 템플릿을 사용하여 Key Vault 비밀의 리소스 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

다음 템플릿은 동적으로 키 자격 증명 모음 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