Использование ссылок Key Vault в качестве параметров приложения в службе приложений Azure и Azure Functions

В этой статье показано, как использовать секреты из Azure Key Vault в качестве значений параметров приложения или строк подключения в приложениях Службы приложений Azure или Функций Azure.

Key Vault — это служба, которая обеспечивает централизованное управление секретами с полным контролем над политиками доступа и журналом аудита. Если параметр приложения или строка подключения является ссылкой на Key Vault, код приложения может использовать его как любой другой параметр приложения или строку подключения. Таким образом, вы можете хранить секреты отдельно от конфигурации приложения. Параметры приложения безопасно шифруются в состоянии покоя, но если вам нужны возможности для управления секретами, они должны храниться в хранилище ключей.

Предоставление приложению доступа к хранилищу ключей

Чтобы прочитать секреты из хранилища ключей, сначала необходимо создать хранилище и предоставить приложению разрешение на доступ к нему:

1. Чтобы создать хранилище ключей, изучите краткое руководство по Key Vault.

2. Создайте для приложения управляемое удостоверение.

   Ссылки на хранилище ключей используют удостоверение, назначаемое системой, по умолчанию, но вы можете указать удостоверение, назначаемое пользователем.

3. Разрешите доступ на чтение к секретам в хранилище ключей для управляемого удостоверения, которое вы создали. Как это сделать, зависит от модели разрешений хранилища ключей:

   • Контроль доступа, основанный на ролях Azure: Назначьте управляемому удостоверению роль Пользователь секретов Key Vault. См. Предоставление доступа к ключам, сертификатам и секретам Key Vault с использованием управления доступом на основе ролей в Azure.
   • Политика доступа к хранилищу: назначьте разрешение "Получить секреты" управляемому идентификатору. См. раздел «Назначение политики доступа Key Vault».

Доступ к хранилищам с ограничением через сеть

Если хранилище настроено с сетевыми ограничениями, убедитесь, что у приложения есть сетевой доступ. Хранилища не должны зависеть от общедоступных исходящих IP-адресов приложения, так как ip-адрес источника секретного запроса может отличаться. Вместо этого хранилище должно быть настроено для приема трафика из виртуальной сети, которую использует приложение.

1. Убедитесь, что в приложении настроены исходящие сетевые возможности, как описано в сетевых функциях службы приложений и параметрах сети Функций Azure.

   В настоящее время приложения Linux, подключающиеся к частным конечным точкам, должны быть явно настроены для маршрутизации всего трафика через виртуальную сеть. Чтобы настроить этот параметр, выполните следующую команду:

   • Azure CLI
   • Azure PowerShell

   az webapp config set --resource-group <group-name>  --subscription <subscription> --name <app-name> --generic-configurations '{"vnetRouteAllEnabled": true}'
   

2. Убедитесь, что конфигурация хранилища разрешает доступ к сети или подсети, которую приложение использует для доступа к нему.

Обратите внимание, что даже если вы правильно настроили хранилище для приема трафика из вашей виртуальной сети, в журналах аудита хранилища все равно может отображаться неудачное событие доступа (403 - запрещено) SecretGet из общедоступного исходящего IP-адреса приложения. За этим должно последовать успешное событие SecretGet с частного IP-адреса приложения, так и задумано.

Доступ к хранилищам с использованием пользовательского удостоверения

Некоторые приложения должны ссылаться на секреты во время создания, когда системно назначаемое удостоверение ещё недоступно. В этих случаях создайте назначенную пользователем идентификацию и предоставьте ей доступ к хранилищу заранее.

После предоставления разрешений идентификации, назначенной пользователем, выполните следующие действия.

1. присвоить удостоверение вашему приложению.

2. Настройте приложение для использования этого удостоверения при выполнении операций с Key Vault, установив свойство keyVaultReferenceIdentity в значение идентификатора ресурса назначенного пользователем удостоверения.

   • Azure CLI
   • Azure PowerShell

   identityResourceId=$(az identity show --resource-group <group-name> --name <identity-name> --query id -o tsv)
   az webapp update --resource-group <group-name> --name <app-name> --set keyVaultReferenceIdentity=${identityResourceId}
   

Этот параметр применяется ко всем ссылкам Key Vault для приложения.

Понимание поворота

Если секретная версия не указана в ссылке, приложение использует последнюю версию, которая существует в хранилище ключей. Когда новые версии становятся доступными, например с поворотом, приложение автоматически обновляется и начинает использовать последнюю версию в течение 24 часов.

Задержка обусловлена тем, что служба App Service кэширует значения ссылок Key Vault и обновляет их каждые 24 часа. Любое изменение конфигурации в приложении приводит к перезапуску приложения и немедленному повторному извлечению всех ссылочных секретов.

Чтобы принудительно разрешить ссылки на Key Vault приложения, выполните прошедший проверку подлинности запрос POST к конечной точке https://management.azure.com/[Resource ID]/config/configreferences/appsettings/refresh?api-version=2022-03-01API.

Общие сведения о параметрах исходного приложения из Key Vault

Чтобы использовать ссылку Key Vault, задайте ссылку в качестве значения параметра. Ваше приложение может ссылаться на секрет через его ключ как обычно. Изменения кода не требуются.

Ссылка на Key Vault имеет форму @Microsoft.KeyVault({referenceString}), где {referenceString} находится в одном из следующих форматов:

Например, полная ссылка без определенной версии будет выглядеть следующим образом:

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

Еще один вариант:

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

Соображения по подключению Azure Files

Приложения могут использовать WEBSITE_CONTENTAZUREFILECONNECTIONSTRING параметр приложения для подключения Azure Files в качестве файловой системы. Эта настройка содержит проверку для валидации, чтобы убедиться, что приложение может быть корректно запущено.

Платформа опирается на область общего доступа к содержимому в Azure Files. Платформа назначает имя по умолчанию, если не указано другое имя с помощью параметра WEBSITE_CONTENTSHARE. Для любых запросов, изменяющих эти параметры, платформа проверяет, существует ли эта общая папка содержимого. Если общий доступ к контенту не существует, платформа пытается создать его. Если платформа не может найти или создать общий доступ к содержимому, она блокирует запрос.

При использовании ссылок Key Vault в этих настройках проверка по умолчанию завершается ошибкой, так как секрет не может быть определён во время обработки входящего запроса. Чтобы избежать этой проблемы, можно пропустить проверку, установив WEBSITE_SKIP_CONTENTSHARE_VALIDATION на 1. Этот параметр указывает службе приложений обходить все проверки и не создавать общую папку содержимого для вас. Необходимо заранее создать общий доступ к содержимому.

При создании приложения попытка монтирования общего доступа к содержимому может завершиться ошибкой, так как разрешения управляемого удостоверения не предоставляются, или не настроена интеграция виртуальной сети. Вы можете отложить настройку файлов Azure до конца в шаблоне развертывания, чтобы обеспечить это поведение. Дополнительные сведения см. в статье о развертывании Azure Resource Manager далее в этой статье.

В этом случае Служба приложений использует файловую систему по умолчанию до настройки Azure Files, и файлы не копируются. Необходимо убедиться, что попытки развертывания не выполняются в течение временного интервала до подключения Файлов Azure.

Рекомендации по инструментированию Application Insights

Приложения могут использовать APPINSIGHTS_INSTRUMENTATIONKEY параметры приложения или APPLICATIONINSIGHTS_CONNECTION_STRING параметры приложения для интеграции с Application Insights.

Для службы приложений и Azure Functions портал Azure также использует эти параметры для отображения данных телеметрии из ресурса. Если эти значения ссылаются из Key Vault, этот подход недоступен. Вместо этого необходимо напрямую работать с ресурсом Application Insights для просмотра телеметрии. Однако эти значения не считаются секретами, поэтому их можно настроить непосредственно вместо использования ссылок Key Vault.

Развертывание Azure Resource Manager

При автоматизации развертываний ресурсов с помощью шаблонов Azure Resource Manager может потребоваться задать порядок последовательности зависимостей. Не забудьте задать параметры приложения как отдельный ресурс, а не использовать свойство siteConfig в определении приложения. Сначала необходимо определить приложение, чтобы с ним было создано назначаемое системой удостоверение и могло использоваться в политике доступа.

Следующий псевдо-шаблон является примером того, как может выглядеть приложение-функция:

{
    //...
    "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('storageConnectionStringName')).secretUriWithVersion, ')')]",
                        "WEBSITE_CONTENTAZUREFILECONNECTIONSTRING": "[concat('@Microsoft.KeyVault(SecretUri=', reference(variables('storageConnectionStringName')).secretUriWithVersion, ')')]",
                        "APPINSIGHTS_INSTRUMENTATIONKEY": "[concat('@Microsoft.KeyVault(SecretUri=', reference(variables('appInsightsKeyName')).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(resourceId('Microsoft.Web/sites/', variables('functionAppName')), '2020-12-01', 'Full').identity.tenantId]",
                        "objectId": "[reference(resourceId('Microsoft.Web/sites/', variables('functionAppName')), '2020-12-01', 'Full').identity.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'),'2019-09-01').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')), '2019-09-01').InstrumentationKey]"
                    }
                }
            ]
        }
    ]
}

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

Если ссылка не разрешена должным образом, вместо нее используется строка ссылки, например @Microsoft.KeyVault(...). Эта ситуация может привести к возникновению ошибок в приложении, так как ожидается секрет с другим значением.

Не удается устранить проблему, как правило, из-за неправильной настройки политики доступа к Key Vault. Однако причиной может также быть то, что секрет больше не существует, или ссылка содержит синтаксическую ошибку.

Если синтаксис правильный, вы можете просмотреть другие причины ошибки, проверив текущее состояние разрешения на портале Azure. Перейдите в раздел "Параметры приложения " и выберите "Изменить " для ссылки. В диалоговом окне редактирования отображаются сведения о состоянии, включая любые ошибки. Если сообщение о состоянии не отображается, это означает, что синтаксис недопустим и не распознается как ссылка на Key Vault.

Вы также можете использовать один из встроенных детекторов для получения дополнительных сведений.

Чтобы использовать детектор для службы приложений, выполните следующие действия.

1. На портале Azure перейдите к приложению.
2. Выберите Диагностика и решение проблем.
3. Выберите "Доступность и производительность>Сбой веб-приложения".
4. В поле поиска выполните поиск и выберите Key Vault Application Settings Diagnostics.

Чтобы использовать детектор функций Azure, выполните следующие действия.

1. На портале Azure перейдите к приложению.
2. Перейдите к функциям платформы.
3. Выберите Диагностика и решение проблем.
4. Выберите Доступность и производительность>Функция приложения не работает или сообщает об ошибках.
5. Выберите диагностику параметров приложения Key Vault.