Управление API и версиями среды выполнения для аутентификации Службы приложений

  • Статья

В этой статье показано, как настроить API и версии среды выполнения для встроенной аутентификации и авторизации в Службе приложений.

Существует две версии API управления для аутентификации Службы приложений. Версия V2 необходима для работы аутентификации на портале Azure. Если приложение уже использует API версии V1, то его можно обновить до версии V2, внеся несколько изменений. Для этого нужно перенести секретную конфигурацию в параметры приложения, связанные со слотом. Это можно сделать автоматически из раздела "Аутентификация" на портале для вашего приложения.

Обновление версии конфигурации

Предупреждение

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

API версии 2 не поддерживает создание или редактирование учетной записи Майкрософт в качестве отдельного поставщика, как было сделано в версии 1. Скорее, он использует конвергентную платформа удостоверений Майкрософт для входа пользователей с идентификатором Microsoft Entra и личными учетными записями Майкрософт. При переключении на API версии 2 конфигурация Microsoft Entra версии 1 используется для настройки поставщика платформа удостоверений Майкрософт. Поставщик учетной записи Майкрософт версии 1 будет перенесен в процессе миграции и продолжит работать как обычный, но следует перейти к новой модели платформа удостоверений Майкрософт. Дополнительные сведения см. в разделе Поддержка регистрации поставщика учетных записей Майкрософт.

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

  1. Перейдите к приложению на портале и выберите пункт Authentication (Аутентификация).
  2. Если приложение настроено с помощью модели версии 1, появится кнопка "Обновить ".
  3. Проверьте описание в запросе подтверждения. Если вы готовы выполнить миграцию, нажмите кнопку "Обновить " в запросе.

Управление миграцией вручную

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

Перемещение секретов в параметры приложения

  1. Получите существующую конфигурацию с помощью API версии V1:

    az webapp auth show -g <group_name> -n <site_name>

    В результате полезных данных JSON запишите значение секрета, используемое для каждого поставщика, настроенного:

    • Идентификатор Microsoft Entra: clientSecret
    • Google: googleClientSecret
    • Facebook: facebookAppSecret
    • Твиттер: twitterConsumerSecret
    • Учетная запись Майкрософт: microsoftAccountClientSecret

    Важно!

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

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

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

    # For Web Apps, Google example    
az webapp config appsettings set -g <group_name> -n <site_name> --slot-settings GOOGLE_PROVIDER_AUTHENTICATION_SECRET=<value_from_previous_step>

# For Azure Functions, Twitter example
az functionapp config appsettings set -g <group_name> -n <site_name> --slot-settings TWITTER_PROVIDER_AUTHENTICATION_SECRET=<value_from_previous_step>

    Примечание.

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

  3. Создайте новый JSON-файл с именем authsettings.json. Возьмите полученные ранее выходные данные и удалите из него каждое значение секрета. Запишите оставшиеся выходные данные в файл без секретов. В некоторых случаях в конфигурации могут быть массивы, содержащие пустые строки. Убедитесь, что microsoftAccountOAuthScopes это не так, и если это делается, переключите это значение nullна .

  4. Добавьте свойство, authsettings.json указывающее на имя параметра приложения, созданное ранее для каждого поставщика:

    • Идентификатор Microsoft Entra: clientSecretSettingName
    • Google: googleClientSecretSettingName
    • Facebook: facebookAppSecretSettingName
    • Твиттер: twitterConsumerSecretSettingName
    • Учетная запись Майкрософт: microsoftAccountClientSecretSettingName

    Пример файла после этой операции может выглядеть примерно так, в этом случае настроен только для идентификатора Microsoft Entra:

    {
    "id": "/subscriptions/00d563f8-5b89-4c6a-bcec-c1b9f6d607e0/resourceGroups/myresourcegroup/providers/Microsoft.Web/sites/mywebapp/config/authsettings",
    "name": "authsettings",
    "type": "Microsoft.Web/sites/config",
    "location": "Central US",
    "properties": {
        "enabled": true,
        "runtimeVersion": "~1",
        "unauthenticatedClientAction": "AllowAnonymous",
        "tokenStoreEnabled": true,
        "allowedExternalRedirectUrls": null,
        "defaultProvider": "AzureActiveDirectory",
        "clientId": "3197c8ed-2470-480a-8fae-58c25558ac9b",
        "clientSecret": "",
        "clientSecretSettingName": "MICROSOFT_IDENTITY_AUTHENTICATION_SECRET",
        "clientSecretCertificateThumbprint": null,
        "issuer": "https://sts.windows.net/0b2ef922-672a-4707-9643-9a5726eec524/",
        "allowedAudiences": [
            "https://mywebapp.azurewebsites.net"
        ],
        "additionalLoginParams": null,
        "isAadAutoProvisioned": true,
        "aadClaimsAuthorization": null,
        "googleClientId": null,
        "googleClientSecret": null,
        "googleClientSecretSettingName": null,
        "googleOAuthScopes": null,
        "facebookAppId": null,
        "facebookAppSecret": null,
        "facebookAppSecretSettingName": null,
        "facebookOAuthScopes": null,
        "gitHubClientId": null,
        "gitHubClientSecret": null,
        "gitHubClientSecretSettingName": null,
        "gitHubOAuthScopes": null,
        "twitterConsumerKey": null,
        "twitterConsumerSecret": null,
        "twitterConsumerSecretSettingName": null,
        "microsoftAccountClientId": null,
        "microsoftAccountClientSecret": null,
        "microsoftAccountClientSecretSettingName": null,
        "microsoftAccountOAuthScopes": null,
        "isAuthFromFile": "false"
    }   
}

  5. Отправьте этот файл в качестве новой конфигурации для аутентификации или авторизации в приложении:

    az rest --method PUT --url "/subscriptions/<subscription_id>/resourceGroups/<group_name>/providers/Microsoft.Web/sites/<site_name>/config/authsettings?api-version=2020-06-01" --body @./authsettings.json

  6. Убедитесь, что приложение работает, как раньше.

  7. Удалите файл, который использовался на предыдущих шагах.

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

Поддержка регистрации поставщика учетных записей Майкрософт

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

  1. Перейдите в раздел Регистрация приложений на портале Azure и найдите регистрацию, связанную с поставщиком учетных записей Майкрософт. Она может быть под заголовком Applications from personal account (Приложения из личной учетной записи).
  2. Перейдите на страницу Authentication (Аутентификация) регистрации. В разделе "URI перенаправления" должна появиться запись, заканчивающаяся /.auth/login/microsoftaccount/callback. Скопируйте этот универсальный код ресурса (URI).
  3. Добавьте новый URI, совпадающий с только что скопированным, но с окончанием /.auth/login/aad/callback. Это позволит конфигурации аутентификации и авторизации Службы приложения использовать эту регистрацию.
  4. Перейдите к конфигурации аутентификации и авторизации своего приложения в Службе приложений.
  5. Сохраните конфигурацию для поставщика учетных записей Майкрософт.
  6. Настройте поставщика Microsoft Entra с помощью режима управления Advanced, указав идентификатор клиента и значения секрета клиента, собранные на предыдущем шаге. Для URL-адреса издателя используйте <authentication-endpoint>/<tenant-id>/v2.0и замените <конечную точку> проверки подлинности конечной точкой проверки подлинности для облачной среды (например, "https://login.microsoftonline.com" для глобальной службы Azure также замените <идентификатор> клиента идентификатором каталога (клиента).
  7. После сохранения конфигурации проверьте поток входа, перейдя в браузере к /.auth/login/aad конечной точке сайта и завершив процесс входа.
  8. На этом этапе вы успешно скопировали конфигурацию, но существующая конфигурация поставщика учетных записей Майкрософт остается. Прежде чем удалить его, убедитесь, что все части приложения ссылались на поставщика Microsoft Entra через ссылки для входа и т. д. Убедитесь, что все части приложения работают должным образом.
  9. Убедившись, что все работает с поставщиком Microsoft Entra, можно удалить конфигурацию поставщика учетных записей Майкрософт.

Предупреждение

Можно объединить две регистрации, изменив поддерживаемые типы учетных записей для регистрации приложения Microsoft Entra. В этом случае система принудительно запросит согласие для пользователей учетных записей Майкрософт. Заявки на удостоверение этих пользователей могут отличаться по структуре: sub заметно меняет значения после использования нового идентификатора приложения. Этот подход не рекомендуется использовать без полного понимания ситуации. Вместо этого следует дождаться поддержки двух регистраций в API версии V2.

Переключение на версию V2

После выполнения описанных выше действий перейдите к приложению на портале Azure. Выберите раздел Authentication (Аутентификация).

Кроме того, вы можете выполнить запрос PUT для ресурса config/authsettingsv2 под ресурсом веб-сайта. Схема полезных данных аналогична схеме, описанной в статье Настройка на основе файлов.

Как прикрепить приложение к определенной версии среды выполнения аутентификации

При включении проверки подлинности и авторизации ПО промежуточного слоя платформы внедряется в конвейер HTTP-запросов, как описано в обзоре функции. В это ПО периодически добавляются новые функции и улучшения в рамках регулярного обновления платформы. По умолчанию ваше веб-приложение или приложение-функция будет выполняться в последней версии этого ПО промежуточного слоя платформы. Автоматические обновления всегда совместимы со старыми версиями. В редких случаях автоматическое обновление выдает ошибку среды выполнения веб-приложения или приложения-функции. В этом случае можно временно вернуться к предыдущей версии ПО промежуточного слоя. Из этой статьи вы узнаете, как временно прикрепить приложение к определенной версии ПО промежуточного слоя для аутентификации.

Обновление версий автоматически и вручную

Вы можете прикрепить приложение к конкретной версии ПО промежуточного слоя платформы, задав параметр runtimeVersion. Если этого не сделать, ваше приложение будет работать в последней версии. Одновременно всегда поддерживается несколько версий. Если вы прикрепите приложение к версии, которая больше не поддерживается, приложение будет использовать последнюю версию. Чтобы всегда запускать приложение в последней версии, установите значение ~1 для runtimeVersion.

Просмотр и обновление текущей версии среды выполнения

Вы можете изменить версию среды выполнения для приложения. Новая версия среды выполнения будет использоваться после его перезапуска.

Просмотр текущей версии среды выполнения

Текущую версию ПО промежуточного слоя для аутентификации можно просмотреть с помощью Azure CLI или через одну из встроенных конечных точек HTTP в приложении.

Использование Azure CLI

С помощью Azure CLI просмотрите текущую версию ПО промежуточного слоя, используя команду az webapp auth show.

az webapp auth show --name <my_app_name> \
--resource-group <my_resource_group>

В этом коде замените <my_app_name> названием приложения-функции. Также замените <my_resource_group> на название группы ресурсов для вашего приложения.

Вы увидите runtimeVersion поле в выходных данных CLI. Оно будет похоже на приведенный ниже пример, который был усечен для большей ясности.

{
  "additionalLoginParams": null,
  "allowedAudiences": null,
    ...
  "runtimeVersion": "1.3.2",
    ...
}
Использование конечной точки версии

Просмотреть текущую версию ПО промежуточного слоя, которое использует приложение, можно с помощью конечной точки /.auth/version. Результат будет выглядеть примерно так:

{
"version": "1.3.2"
}

Обновление текущей версии среды выполнения

С помощью Azure CLI можно обновить параметр runtimeVersion в приложении, используя команду az webapp auth update.

az webapp auth update --name <my_app_name> \
--resource-group <my_resource_group> \
--runtime-version <version>

Замените <my_app_name> на название приложения. Также замените <my_resource_group> на название группы ресурсов для вашего приложения. Замените <version> на значение допустимой версии среды выполнения 1.x или на значение ~1 для последней версии. Чтобы узнать, за какой версией нужно закрепить приложение, см. заметки о выпуске для разных версий среды выполнения.

Эту команду можно выполнить в Azure Cloud Shell, выбрав Попробовать в предыдущем примере кода. Также можно использовать Azure CLI локально для выполнения этой команды после выполнения команды az login для входа.

Следующие шаги

Руководство. Сквозная аутентификация и авторизация пользователей