Использование Key Vault ссылок для службы приложений и функций AzureUse Key Vault references for App Service and Azure Functions

В этой статье показано, как работать с секретами из Azure Key Vault в приложении Службы приложений или Функций Azure без каких-либо изменений кода.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 VaultGranting 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. Создайте для приложения управляемое удостоверение, назначаемое системой.Create a system-assigned managed identity for your application.

    Примечание

    Ссылки на Key Vault сейчас поддерживают только назначаемые системой управляемые удостоверения.Key Vault references currently only support system-assigned managed identities. Вы не сможете использовать удостоверения, назначаемые пользователем.User-assigned identities cannot be used.

  3. Создайте политику доступа в Key Vault для созданного ранее удостоверения приложения.Create an access policy in Key Vault for the application identity you created earlier. Включите в этой политике разрешения "Get" на получение секретов.Enable the "Get" secret permission on this policy. Не устанавливайте "авторизованное приложение" или параметр applicationId, так как он не совместим с управляемым удостоверением.Do not configure the "authorized application" or applicationId settings, as this is not compatible with a managed identity.

    Важно!

    Key Vault ссылки в настоящее время не могут разрешать секреты, хранящиеся в хранилище ключей, с ограничениями сети , если только приложение не размещено в Среда службы приложений.Key Vault references are not presently able to resolve secrets stored in a key vault with network restrictions unless the app is hosted within an App Service Environment.

Синтаксис ссылок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 является полным URI плоскости данных секрета в Key Vault, включая версию, например: 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.

Примечание

В настоящее время требуются версии.Versions are currently 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 VaultSource 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 ManagerAzure 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. Это связано с тем, что сначала нужно определить сайт и получить для него назначаемый системой идентификатор, и лишь затем можно применить этот идентификатор в политике доступа.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 pseudo-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.

Устранение неполадок Key Vault ссылокTroubleshooting Key Vault References

Если ссылка не разрешается должным образом, вместо нее будет использоваться ссылочное значение.If a reference is not resolved properly, the reference value will be used instead. Это означает, что для параметров приложения будет создана переменная среды со значением @Microsoft.KeyVault(...) синтаксиса.This means that for application settings, an environment variable would be created whose value has the @Microsoft.KeyVault(...) syntax. Это может привести к тому, что приложение выдаст ошибки, так как оно ожидало секрета определенной структуры.This may cause the application to throw errors, as it was expecting a secret of a certain structure.

Чаще всего это происходит из-за ненужной настройки политики доступа Key Vault.Most commonly, this is due to a misconfiguration of the Key Vault access policy. Однако это также может быть вызвано тем, что секрет больше не существует, или синтаксическую ошибку в самой ссылке.However, it could also be due to a secret no longer existing or a syntax error in the reference itself.

Если синтаксис правильный, можно просмотреть другие причины ошибки, проверив текущее состояние разрешения на портале.If the syntax is correct, you can view other causes for error by checking the current resolution status in the portal. Перейдите к разделу Параметры приложения и выберите команду "Изменить", чтобы получить ссылку на вопрос.Navigate to Application Settings and select "Edit" for the reference in question. После настройки параметров должны отобразиться сведения о состоянии, включая ошибки.Below the setting configuration, you should see status information, including any errors. Отсутствие этих данных означает, что синтаксис ссылки недействителен.The absence of these implies that the reference syntax is invalid.

Для получения дополнительных сведений можно также использовать один из встроенных обнаружений.You can also use one of the built-in detectors to get additional information.

Использование средства обнаружения для службы приложенийUsing the detector for App Service

  1. На портале перейдите к своему приложению.In the portal, navigate to your app.
  2. Выберите колонку Диагностика и решение проблем.Select Diagnose and solve problems.
  3. Выберите доступность и производительность , а затем — веб-приложение.Choose Availability and Performance and select Web app down.
  4. Найдите Key Vault диагностика параметров приложения и щелкните Дополнительные сведения.Find Key Vault Application Settings Diagnostics and click More info.

Использование средства обнаружения для функций AzureUsing the detector for Azure Functions

  1. На портале перейдите к своему приложению.In the portal, navigate to your app.
  2. Перейдите к разделу функции платформы.Navigate to Platform features.
  3. Выберите колонку Диагностика и решение проблем.Select Diagnose and solve problems.
  4. Выберите доступность и производительность , а затем выберите приложение функции вниз или отчет об ошибках.Choose Availability and Performance and select Function app down or reporting errors.
  5. Щелкните Key Vault параметры приложения диагностика.Click on Key Vault Application Settings Diagnostics.