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

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

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

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

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

Предварительные требования

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

Сценарий

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

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

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

Схема, на которой показано приложение UserSync с тремя локальными элементами, подключенными к Azure: Startup.Auth с получением маркера в интерактивном режиме для подключения к Azure AD, AccountController с получением согласия администратора для подключения к Azure AD и SyncController со считыванием данных пользователя для подключения к Microsoft Graph.

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

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

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

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

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

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

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

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

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

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

    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force
    
  3. Запустите скрипт, чтобы создать приложение Azure AD и соответствующим образом настройте код примера приложения.

    .\AppCreationScripts\Configure.ps1
    

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

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

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

Выбор арендатора Azure AD

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

Зарегистрируйте клиентское приложение (dotnet-web-daemon-v2).

  1. Найдите и выберите Azure Active Directory.

  2. В разделе Управление выберите Регистрация приложений > Создать регистрацию.

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

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

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

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

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

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

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

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

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

  11. Щелкните Сохранить.

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

  13. В разделе Секреты клиента выберите Новый секрет клиента.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

предоставление согласия пользователем.

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

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

Согласие администратора

После предоставления разрешений выполняется выход из приложения. Выход нужен для того, чтобы удалить из кэша маркеров все существующие маркеры доступа для 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-адресом этого проекта. Если вы увидите стандартную веб-страницу проекта, значит публикация прошла успешно.

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

  1. Вернитесь на портал Azure.
  2. На панели слева выберите службу Azure Active Directory, а затем щелкните Регистрация приложений.
  3. Выберите приложение dotnet-web-daemon-v2.
  4. На странице Аутентификация приложения обновите поля URL-адрес выхода переднего канала, указав адрес службы. Например, воспользуйтесь https://dotnet-web-daemon-v2-contoso.azurewebsites.net/Account/EndSession.
  5. В меню Фирменная символика измените URL-адрес домашней страницы на адрес службы. Например, воспользуйтесь https://dotnet-web-daemon-v2-contoso.azurewebsites.net.
  6. Сохраните конфигурацию.
  7. Добавьте тот же 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: