App Service 및 Azure Functions의 Key Vault 참조 사용(미리 보기)Use Key Vault references for App Service and Azure Functions (preview)

참고

Key Vault 참조는 현재 미리 보기로 제공됩니다.Key Vault references are currently in preview.

이 항목에서는 코드 변경 없이도 App Service 또는 Azure Functions 애플리케이션에서 Azure Key Vault의 비밀을 사용하는 방법을 보여 줍니다.This topic shows you how to work with secrets from Azure Key Vault in your App Service or Azure Functions application without requiring any code changes. Azure Key Vault는 액세스 정책 및 감사 기록에 대한 전체 제어와 함께 중앙 집중식 비밀 관리를 제공하는 서비스입니다.Azure Key Vault is a service that provides centralized secrets management, with full control over access policies and audit history.

Key Vault에 앱 액세스 권한 부여Granting your app access to Key Vault

Key Vault에서 비밀을 읽으려면 자격 증명 모음을 만들고 해당 자격 증명에 앱 권한을 부여해야 합니다.In order to read secrets from Key Vault, you need to have a vault created and give your app permission to access it.

  1. Key Vault 빠른 시작에 따라 키 자격 증명 모음을 만듭니다.Create a key vault by following the Key Vault quickstart.

  2. 애플리케이션에 대한 시스템 할당 관리형 ID를 만듭니다.Create a system-assigned managed identity for your application.

    참고

    Key Vault 참조는 현재 시스템 할당 관리형 ID만 지원합니다.Key Vault references currently only support system-assigned managed identities. 사용자 할당 ID를 사용할 수 없습니다.User-assigned identities cannot be used.

  3. 이전에 만든 애플리케이션 ID에 대한 Key Vault에서 액세스 정책을 만듭니다.Create an access policy in Key Vault for the application identity you created earlier. 이 정책에 대한 “가져오기” 비밀 권한을 사용하도록 설정합니다.Enable the "Get" secret permission on this policy. "권한 있는 애플리케이션" 또는 applicationId 설정은 관리 ID와 호환되지 않으므로 구성하지 마세요.Do not configure the "authorized application" or applicationId settings, as this is not compatible with a managed identity.

참조 구문Reference syntax

Key Vault 참조는 @Microsoft.KeyVault({referenceString}) 형식이며, 여기서 {referenceString}은 다음 옵션 중 하나로 대체됩니다.A Key Vault reference is of the form @Microsoft.KeyVault({referenceString}), where {referenceString} is replaced by one of the following options:

참조 문자열Reference string 설명Description
SecretUri=secretUriSecretUri=secretUri SecretUri는 버전을 포함하여 Key Vault에 있는 비밀의 전체 데이터 평면 URI여야 합니다(예: https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931 ).The SecretUri should be the full data-plane URI of a secret in Key Vault, including a version, e.g., https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931
VaultName=vaultName;SecretName=secretName;SecretVersion=secretVersionVaultName=vaultName;SecretName=secretName;SecretVersion=secretVersion VaultName은 Key Vault 리소스의 이름이어야 합니다.The VaultName should the name of your Key Vault resource. SecretName은 대상 비밀의 이름이어야 합니다.The SecretName should be the name of the target secret. SecretVersion은 사용할 비밀의 버전이어야 합니다.The SecretVersion should be the version of the secret to use.

참고

현재 미리 보기에서 버전은 필수입니다.In the current preview, versions are required. 비밀을 회전할 때 애플리케이션 구성에서 버전을 업데이트해야 합니다.When rotating secrets, you will need to update the version in your application configuration.

예를 들어 전체 참조는 다음과 같습니다.For example, a complete reference would look like the following:

@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931)

또는 다음과 같습니다.Alternatively:

@Microsoft.KeyVault(VaultName=myvault;SecretName=mysecret;SecretVersion=ec96f02080254f109c51a1f14cdb1931)

Key Vault의 원본 애플리케이션 설정Source Application Settings from Key Vault

Key Vault 참조를 애플리케이션 설정 값으로 사용할 수 있어 사이트 구성 대신 Key Vault에서 비밀을 유지할 수 있습니다. 애플리케이션 설정은 안전하게 암호화되어 있지만 비밀 관리 기능이 필요한 경우 Key Vault로 이동해야 합니다.Key Vault references can be used as values for Application Settings, allowing you to keep secrets in Key Vault instead of the site config. Application Settings are securely encrypted at rest, but if you need secret management capabilities, they should go into Key Vault.

애플리케이션 설정에 Key Vault 참조를 사용하려면 참조를 설정 값으로 설정합니다.To use a Key Vault reference for an application setting, set the reference as the value of the setting. 앱은 키를 사용하여 비밀을 정상적으로 참조할 수 있습니다.Your app can reference the secret through its key as normal. 코드 변경은 필요하지 않습니다.No code changes are required.

Key Vault 참조를 사용하는 대부분의 애플리케이션 설정은 각 환경에 대해 별도의 자격 증명 모음이 있어야 슬롯 설정으로 표시되어야 합니다.Most application settings using Key Vault references should be marked as slot settings, as you should have separate vaults for each environment.

Azure Resource Manager 배포Azure Resource Manager deployment

Azure Resource Manager 템플릿을 통해 리소스 배포를 자동화할 때 이 기능이 작동하려면 종속성을 특정 순서로 시퀀스해야 할 수 있습니다.When automating resource deployments through Azure Resource Manager templates, you may need to sequence your dependencies in a particular order to make this feature work. 중요한 것은, 사이트 정의에서 siteConfig 속성을 사용하는 대신 애플리케이션 설정을 자체 리소스로 정의해야 합니다.Of note, you will need to define your application settings as their own resource, rather than using a siteConfig property in the site definition. 이는 사이트를 먼저 정의해야 사이트를 사용하여 시스템 할당 ID를 만들고 액세스 정책에서 사용할 수 있기 때문입니다.This is because the site needs to be defined first so that the system-assigned identity is created with it and can be used in the access policy.

함수 앱에 대한 예제 의사 템플릿은 다음과 같습니다.An example psuedo-template for a function app might look like the following:

{
    //...
    "resources": [
        {
            "type": "Microsoft.Storage/storageAccounts",
            "name": "[variables('storageAccountName')]",
            //...
        },
        {
            "type": "Microsoft.Insights/components",
            "name": "[variables('appInsightsName')]",
            //...
        },
        {
            "type": "Microsoft.Web/sites",
            "name": "[variables('functionAppName')]",
            "identity": {
                "type": "SystemAssigned"
            },
            //...
            "resources": [
                {
                    "type": "config",
                    "name": "appsettings",
                    //...
                    "dependsOn": [
                        "[resourceId('Microsoft.Web/sites', variables('functionAppName'))]",
                        "[resourceId('Microsoft.KeyVault/vaults/', variables('keyVaultName'))]",
                        "[resourceId('Microsoft.KeyVault/vaults/secrets', variables('keyVaultName'), variables('storageConnectionStringName'))]",
                        "[resourceId('Microsoft.KeyVault/vaults/secrets', variables('keyVaultName'), variables('appInsightsKeyName'))]"
                    ],
                    "properties": {
                        "AzureWebJobsStorage": "[concat('@Microsoft.KeyVault(SecretUri=', reference(variables('storageConnectionStringResourceId')).secretUriWithVersion, ')')]",
                        "WEBSITE_CONTENTAZUREFILECONNECTIONSTRING": "[concat('@Microsoft.KeyVault(SecretUri=', reference(variables('storageConnectionStringResourceId')).secretUriWithVersion, ')')]",
                        "APPINSIGHTS_INSTRUMENTATIONKEY": "[concat('@Microsoft.KeyVault(SecretUri=', reference(variables('appInsightsKeyResourceId')).secretUriWithVersion, ')')]",
                        "WEBSITE_ENABLE_SYNC_UPDATE_SITE": "true"
                        //...
                    }
                },
                {
                    "type": "sourcecontrols",
                    "name": "web",
                    //...
                    "dependsOn": [
                        "[resourceId('Microsoft.Web/sites', variables('functionAppName'))]",
                        "[resourceId('Microsoft.Web/sites/config', variables('functionAppName'), 'appsettings')]"
                    ],
                }
            ]
        },
        {
            "type": "Microsoft.KeyVault/vaults",
            "name": "[variables('keyVaultName')]",
            //...
            "dependsOn": [
                "[resourceId('Microsoft.Web/sites', variables('functionAppName'))]"
            ],
            "properties": {
                //...
                "accessPolicies": [
                    {
                        "tenantId": "[reference(concat('Microsoft.Web/sites/',  variables('functionAppName'), '/providers/Microsoft.ManagedIdentity/Identities/default'), '2015-08-31-PREVIEW').tenantId]",
                        "objectId": "[reference(concat('Microsoft.Web/sites/',  variables('functionAppName'), '/providers/Microsoft.ManagedIdentity/Identities/default'), '2015-08-31-PREVIEW').principalId]",
                        "permissions": {
                            "secrets": [ "get" ]
                        }
                    }
                ]
            },
            "resources": [
                {
                    "type": "secrets",
                    "name": "[variables('storageConnectionStringName')]",
                    //...
                    "dependsOn": [
                        "[resourceId('Microsoft.KeyVault/vaults/', variables('keyVaultName'))]",
                        "[resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName'))]"
                    ],
                    "properties": {
                        "value": "[concat('DefaultEndpointsProtocol=https;AccountName=', variables('storageAccountName'), ';AccountKey=', listKeys(variables('storageAccountResourceId'),'2015-05-01-preview').key1)]"
                    }
                },
                {
                    "type": "secrets",
                    "name": "[variables('appInsightsKeyName')]",
                    //...
                    "dependsOn": [
                        "[resourceId('Microsoft.KeyVault/vaults/', variables('keyVaultName'))]",
                        "[resourceId('Microsoft.Insights/components', variables('appInsightsName'))]"
                    ],
                    "properties": {
                        "value": "[reference(resourceId('microsoft.insights/components/', variables('appInsightsName')), '2015-05-01').InstrumentationKey]"
                    }
                }
            ]
        }
    ]
}

참고

이 예제에서 원본 제어 배포는 애플리케이션 설정에 따라 다릅니다.In this example, the source control deployment depends on the application settings. 일반적으로 앱 설정 업데이트는 비동기적으로 동작하므로 안전하지 않은 동작입니다.This is normally unsafe behavior, as the app setting update behaves asynchronously. 그러나 WEBSITE_ENABLE_SYNC_UPDATE_SITE 애플리케이션 설정을 포함했으므로 업데이트가 동기적입니다.However, because we have included the WEBSITE_ENABLE_SYNC_UPDATE_SITE application setting, the update is synchronous. 이는 애플리케이션 설정이 완전히 업데이트된 후에만 원본 제어 배포가 시작됨을 의미합니다.This means that the source control deployment will only begin once the application settings have been fully updated.