Руководство. Создание мультитенантной управляющей программы, использующего платформа удостоверений Майкрософт

  • Статья

При работе с этим руководством вы скачаете и запустите веб-приложение управляющей программы ASP.NET, на примере которого показано предоставление учетных данных клиента OAuth 2.0 для получения маркера доступа для вызова API Microsoft Graph.

В этом руководстве рассматриваются следующие темы:

  • Интеграция управляющей программы с платформой удостоверений Майкрософт.
  • Непосредственное предоставление разрешений приложению администратором.
  • Получение маркера доступа для вызова API Microsoft Graph
  • Вызовите API Microsoft Graph.

Если у вас нет подписки Azure, создайте бесплатную учетную запись, прежде чем приступить к работе.

Необходимые компоненты

  • Visual Studio 2017 или 2019.
  • Клиент Microsoft Entra. Дополнительные сведения см. в разделе "Как получить клиент Microsoft Entra".
  • Одна или несколько учетных записей пользователей в клиенте. Этот пример не будет работать с учетной записью Майкрософт. Если вы выполнили вход с помощью учетной записи Майкрософт и никогда не создали учетную запись пользователя в каталоге, сделайте это сейчас.

Сценарий

Это приложение создается в формате приложения ASP.NET MVC. Для входа пользователей в нем используется ПО промежуточного слоя OWIN для OpenID Connect.

Компонент управляющей программы в этом примере является контроллером API SyncController.cs. При вызове контроллера он извлекает список пользователей в клиенте Microsoft Entra клиента из Microsoft Graph. SyncController.cs активируется AJAX-вызовом в веб-приложении. Контроллер использует библиотеку аутентификации Майкрософт (MSAL) для .NET, чтобы получить маркер доступа для Microsoft Graph.

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

Diagram shows UserSync App with three local items connecting to Azure, with Start dot Auth acquiring a token interactively to connect to Microsoft Entra ID, AccountController getting admin consent to connect to Microsoft Entra ID, and SyncController reading user to connect to Microsoft Graph.

Дополнительные сведения об основных понятиях, используемых в этом примере, см. в документации по протоколу учетных данных клиента для платформы удостоверений.

Клонирование или скачивание этого репозитория

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

git clone https://github.com/Azure-Samples/active-directory-dotnet-daemon-v2.git

Вы также можете скачать пример в виде ZIP-файла.

Регистрация приложения

Этот пример содержит один проект. Чтобы зарегистрировать приложение в клиенте Microsoft Entra, можно:

Если вы хотите использовать автоматизацию, сделайте следующее:

  1. В Windows запустите PowerShell и перейдите в корень клонированного каталога.

  2. Выполните следующую команду:

    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force

  3. Запустите скрипт, чтобы создать приложение Microsoft Entra и настроить код примера приложения соответствующим образом:

    .\AppCreationScripts\Configure.ps1

    Другие способы выполнения скриптов описаны в статье о скриптах создания приложения.

  4. Откройте решение Visual Studio и щелкните Пуск, чтобы выполнить код.

Если вы не хотите использовать автоматизацию, выполните шаги из следующих разделов.

Выбор клиента

Совет

Действия, описанные в этой статье, могут немного отличаться на портале, с который вы начинаете работу.

  1. Войдите в Центр администрирования Microsoft Entra как минимум разработчик приложений.

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

  3. Перейдите к приложениям> удостоверений>Регистрация приложений.

  4. Выберите Создать регистрацию.

  5. Введите имя приложения, например dotnet-web-daemon-v2. Пользователи приложения могут видеть это имя. Вы можете изменить его позже.

  6. В разделе Поддерживаемые типы учетных записей выберите Учетные записи в любом каталоге организации.

  7. В разделе URI перенаправления (необязательно) выберите Интернет в поле со списком и введите URI перенаправления https://localhost:44316/ и https://localhost:44316/Account/GrantPermissions.

    Если у вас более двух URI перенаправления, их придется добавить на вкладке Проверка подлинности позднее, после успешного создания приложения.

  8. Выберите Зарегистрировать, чтобы создать приложение.

  9. На странице приложения Обзор найдите идентификатор приложения (клиента) и запишите его, чтобы использовать позже. Он понадобится для настройки файла конфигурации Visual Studio для этого проекта.

  10. В разделе Управление выберите Проверка подлинности.

  11. Задайте для параметра URL-адрес выхода переднего канала значение https://localhost:44316/Account/EndSession.

  12. В разделе Неявное предоставление разрешения и гибридные потоки выберите Маркеры доступа и Маркеры идентификации. Для этого примера должен быть включен поток неявного предоставления, чтобы пользователь мог входить в систему и вызывать API.

  13. Выберите Сохранить.

  14. В разделе Управление выберите Сертификаты и секреты.

  15. В разделе Секреты клиента выберите Создать секрет клиента.

  16. Введите описание ключа (например, секрет приложения).

  17. Выберите срок действия ключа 1 год, 2 года или Срок действия неограничен.

  18. Выберите Добавить. Сохраните значение ключа в надежном месте. Этот ключ потребуется позже для настройки проекта в Visual Studio.

  19. В разделе Управление выберите Разрешения API>Добавить разрешение.

  20. В разделе Часто используемые интерфейсы API Microsoft выберите Microsoft Graph.

  21. В разделе разрешений приложения убедитесь, что выбраны правильные разрешения: User.Read.All.

  22. Выберите Добавить разрешения.

Настройка примера для использования клиента

На следующих шагах значение ClientID совпадает с идентификатором приложения (AppId).

Откройте решение в Visual Studio, чтобы настроить проекты.

Настройка клиентского проекта

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

  1. Откройте файл UserSync\Web.Config.
  2. Найдите ключ приложения Ida:ClientId. Замените существующее значение идентификатором приложения dotnet-web-daemon-v2 , которое было записано ранее.
  3. Найдите ключ приложения ida:ClientSecret. Замените существующее значение ключом, сохраненным во время создания приложения dotnet-web-daemon-v2 .

Запуск примера

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

Когда вы будете входить в систему, приложение сначала запросит у вас разрешение на вход и чтение профиля пользователя. Это согласие подтверждает для приложения, что вы являетесь бизнес-пользователем.

User consent

Затем приложение пытается синхронизировать список пользователей из клиента Microsoft Entra с помощью Microsoft Graph. Если это не удастся, вам (администратору арендатора) будет предложено подключить арендатор к приложению.

Затем приложение запросит разрешение на чтение списка пользователей в арендаторе.

Admin consent

После предоставления разрешений выполняется выход из приложения. Выход нужен для того, чтобы удалить из кэша маркеров все существующие маркеры доступа для Microsoft Graph. Когда вы войдете в следующий раз, вы получите новый маркер с разрешениями для выполнения вызовов к Microsoft Graph.

Получив от вас разрешения, приложение может запрашивать данные пользователей в любой момент. Это можно проверить, нажав кнопку Синхронизация пользователей и обновив список пользователей. Попробуйте добавить или удалить пользователя и повторно синхронизировать список. (Обратите внимание, что приложение синхронизирует только первую страницу списка пользователей.)

Примечания о коде

Соответствующий код для этого примера находится в следующих файлах:

  • App_Start\Startup.Auth.cs, Controllers\AccountController.cs: начальный вход. В частности, действия на контроллере имеют атрибут Authorize, который обеспечивает принудительный вход пользователя в систему. Приложение использует поток кода авторизации для входа пользователя.
  • Controllers\SyncController.cs: синхронизация списка пользователей в локальном хранилище в памяти.
  • Controllers\UserController.cs: отображение списка пользователей из локального хранилища в памяти.
  • Controllers\AccountController.cs: получение разрешений от администратора клиента с помощью конечной точки согласия администратора администратора.

Повторное создание примера приложения

  1. Создайте в Visual Studio новый проект веб-приложения ASP.NET (платформа .NET) для Visual C#.
  2. На следующем экране выберите шаблон проекта MVC. Добавьте также папку и ссылки на основные компоненты для веб-API, так как позднее вы добавите контроллер веб-API. Оставьте выбранный для проекта режим проверки подлинности как стандартный: проверка подлинности отсутствует.
  3. Выберите проект в окне обозревателя решений и нажмите клавишу F4.
  4. В свойствах проекта задайте для параметра SSL включен значение True. Обратите внимание на значение URL-адрес SSL. Оно понадобится при настройке регистрации этого приложения на портале Azure.
  5. Добавьте следующие пакеты NuGet для по промежуточного слоя OWIN ASP.NET:
    • Microsoft.Owin.Security.ActiveDirectory
    • Microsoft.Owin.Security.Cookies
    • Microsoft.Owin.Host.SystemWeb
    • Microsoft.IdentityModel.Protocol.Extensions
    • Microsoft.Owin.Security.OpenIdConnect
    • Microsoft.Identity.Client
  6. В папке App_Start :
    1. Создайте класс с именем Startup.Auth.cs.
    2. Удалите .App_Start из имени пространства имен.
    3. Замените код класса Startup кодом из аналогичного файла в примере приложения. Полностью скопируйте все определение класса. В определении вместо public class Startup теперь указано public partial class Startup.
  7. В файле Startup.Auth.cs разрешите отсутствующие ссылки, добавив инструкции using, которые предложит Visual Studio IntelliSense.
  8. Щелкните проект правой кнопкой мыши, а затем выберите Добавить и Класс.
  9. В поле поиска введите OWIN. В качестве выделенного фрагмента отобразится класс запуска OWIN. Выберите его и присвойте классу имя Startup.cs.
  10. В файле Startup.cs замените код класса Startup кодом из аналогичного файла в примере приложения. В этом определении также вместо public class Startup теперь указано public partial class Startup.
  11. В папке Models добавьте новый класс с именем MsGraphUser.cs. Замените реализацию содержимым файла с тем же именем из примера.
  12. Добавьте новый экземпляр Контроллер MVC 5 — пустой с именем AccountController. Замените реализацию содержимым файла с тем же именем из примера.
  13. Добавьте новый экземпляр Контроллер MVC 5 — пустой с именем UserController. Замените реализацию содержимым файла с тем же именем из примера.
  14. Добавьте новый экземпляр Контроллер Web API 2 — пустой с именем SyncController. Замените реализацию содержимым файла с тем же именем из примера.
  15. Для пользовательского интерфейса в папке Views\Account добавьте три пустых представления (без модели) с именами GrantPermissions, Index и UserMismatch. Еще одно с именем Index добавьте в папку Views\User. Замените реализацию содержимым файла с тем же именем из примера.
  16. Обновите файлы Shared_Layout.cshtml и Home\Index.cshtml, чтобы правильно связать разные представления.

Развертывание примера в Azure

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

  1. Создайте веб-сайт Azure.
  2. Опубликуйте на этом веб-сайте веб-приложение и веб-API.
  3. Измените клиенты, чтобы они вызвали этот веб-сайт вместо IIS Express.

Создание и публикация dotnet-web-daemon-v2 на веб-сайте Azure

  1. Войдите на портал Azure.
  2. В левом нижнем углу щелкните Создать ресурс.
  3. Выберите Интернет>Веб-приложение и присвойте веб-сайту имя. Например, dotnet-web-daemon-v2-contoso.azurewebsites.net.
  4. Заполните поля Подписка, Группа ресурсов, а также Расположение или план службы приложений- Для параметра Операционная система укажите Windows, а для параметра Публиковать — значение Код.
  5. Щелкните Создать и дождитесь создания службы приложений.
  6. Когда появится уведомление Развертывание выполнено, щелкните Перейти к ресурсу, чтобы перейти к созданной службе приложений.
  7. После создания веб-сайта найдите его на панели мониторинга и щелкните, чтобы открыть окно Обзор для службы приложений.
  8. На этой вкладке Обзор службы приложений скачайте профиль публикации, щелкнув ссылку Скачать профиль публикации, и сохраните его. Вы также можете использовать другие механизмы развертывания, например развертывание из системы управления версиями.
  9. Перейдите в Visual Studio, а затем:
    1. Перейдите к проекту dotnet-web-daemon-v2.
    2. В обозревателе решений щелкните правой кнопкой мыши проект и выберите Опубликовать.
    3. Щелкните Импортировать профиль на нижней панели и импортируйте скачанный ранее профиль публикации.
  10. Выберите Настроить.
  11. На вкладке Подключение измените значение URL-адреса назначения, чтобы в нем был указан протокол HTTPS. Например, используйте https://dotnet-web-daemon-v2-contoso.azurewebsites.net. Выберите Далее.
  12. На вкладке Параметры убедитесь, что снят флажок Включение аутентификации в организации.
  13. Выберите Сохранить. Щелкните Опубликовать на главном экране.

Visual Studio опубликует проект и автоматически откроет в браузере страницу с URL-адресом этого проекта. Если вы увидите стандартную веб-страницу проекта, значит публикация прошла успешно.

Обновление регистрации приложения клиента Microsoft Entra для dotnet-web-daemon-v2

  1. Вернитесь в Центр администрирования Microsoft Entra, а затем выберите приложение dotnet-web-daemon-v2 в Регистрация приложений.
  2. На странице Аутентификация приложения обновите поля URL-адрес выхода переднего канала, указав адрес службы. Например, укажите https://dotnet-web-daemon-v2-contoso.azurewebsites.net/Account/EndSession.
  3. В меню Фирменная символика измените URL-адрес домашней страницы на адрес службы. Например, укажите https://dotnet-web-daemon-v2-contoso.azurewebsites.net.
  4. Сохраните конфигурацию.
  5. Добавьте тот же URL-адрес в список значений в меню Проверка подлинности>URI перенаправления. При наличии нескольких URL-адресов перенаправления убедитесь, что для каждого из них есть новая запись, в которой указан соответствующий URI службы приложений.

Очистка ресурсов

Удалите ненужный объект приложения, созданный на шаге Регистрация приложения. Чтобы удалить приложение, следуйте инструкциям в разделеУдаление приложения, созданного вами или организацией.

Справка

Для получения поддержки от сообщества используйте Microsoft Q&A. Задайте вопросы на сайте Microsoft Q&A и просмотрите имеющиеся проблемы, чтобы узнать, не задавал ли кто-то аналогичные вопросы раньше. Убедитесь, что ваши вопросы или комментарии помечены тегами azure-ad-adal-deprecation, azure-ad-msalи dotnet-standard."

Если вы найдете ошибку в примере, напишите о ней в разделе проблем на сайте GitHub.

Если в MSAL.NET обнаружена ошибка, напишите об этой ошибке в разделе проблем с MSAL.NET на сайте GitHub.

Чтобы предоставить рекомендацию, откройте страницу форума User Voice.

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

Узнайте подробнее о создании управляющих приложений, использующих платформу удостоверений Майкрософт для доступа к защищенным веб-API:

Сценарий: управляющая программа, которая вызывает веб-API