Краткое руководство. Реализация входа пользователей и вызова Microsoft Graph в приложении универсальной платформы Windows

  • Статья

В этом кратком руководстве описано, как скачать и выполнить пример кода, который демонстрирует, как приложение универсальной платформы Windows (UWP) может реализовать вход пользователей и получать маркер доступа для вызова API Microsoft Graph.

Иллюстрацию см. в разделе Как работает этот пример.

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

Регистрация и скачивание приложения, используемого в этом кратком руководстве

У вас есть два варианта запуска приложения, используемого в этом кратком руководстве:

Вариант 1. Регистрация и автоматическая настройка приложения, а затем скачивание примера кода

  1. Перейдите в Центр администрирования AMicrosoft Entra — Регистрация приложений краткое руководство.
  2. Введите имя приложения и нажмите кнопку Зарегистрировать.
  3. Следуйте инструкциям, чтобы быстро скачать и автоматически настроить новое приложение.

Вариант 2. Регистрация и настройка приложения и примера кода вручную

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

Совет

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

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

  1. Войдите в центр администрирования Microsoft Entra.
  2. Если у вас есть доступ к нескольким клиентам, используйте значок Параметры в верхнем меню, чтобы переключиться на клиент, в котором вы хотите зарегистрировать приложение из меню каталогов и подписок.
  3. Перейдите к приложениям> удостоверений>Регистрация приложений выберите "Создать регистрацию".
  4. Введите имя приложения, например UWP-App-calling-MsGraph. Пользователи приложения могут видеть это имя. Вы можете изменить его позже.
  5. В разделе Поддерживаемые типы учетных записей выберите Accounts in any organizational directory and personal Microsoft accounts (for example, Skype, Xbox, Outlook.com) (Учетные записи в любом каталоге организации и личные учетные записи Майкрософт (например, Skype, Xbox, Outlook.com)).
  6. Выберите пункт Регистрация, чтобы создать приложение и запишите Идентификатор приложения (клиент), он понадобится на следующих этапах.
  7. В разделе Управление выберите Проверка подлинности.
  8. Поочередно выберите Добавить платформу>Мобильные и классические приложения.
  9. В разделе URI перенаправления выберите https://login.microsoftonline.com/common/oauth2/nativeclient.
  10. Выберите Настроить.

Шаг 2. Скачивание проекта

Скачать пример приложения UWP

Совет

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

Шаг 3. Настройка проекта

  1. Извлеките ZIP-архив в локальную папку рядом с корнем диска. Например, в папку C:\Azure-Samples.

  2. Откройте проект в Visual Studio. При наличии запроса установите рабочую нагрузку Разработка приложений для универсальной платформы Windows и отдельные компоненты пакета SDK.

  3. В MainPage.Xaml.cs замените значение переменной ClientId на идентификатор приложения (клиент), которое вы зарегистрировали ранее.

    private const string ClientId = "Enter_the_Application_Id_here";

    Идентификатор приложения (клиента) можно найти на панели обзора приложения в Центре администрирования Microsoft Entra (Приложения> удостоверений>Регистрация приложений>{Регистрация приложения}).

  4. Создайте и выберите новый самозаверяющий тестовый сертификат для пакета:

    1. В Обозревателе решений дважды щелкните файл Package.appxmanifest.
    2. Выберите Упаковка>Выбор сертификата...>Создать....
    3. Введите пароль и нажмите OK. Будет создан сертификат с именем Native_UWP_V2_TemporaryKey.pfx.
    4. Нажмите кнопку ОК, чтобы закрыть диалоговое окно Выбор сертификата, а затем убедитесь, что вы видите Native_UWP_V2_TemporaryKey.pfx в Обозревателе решений.
    5. В Обозревателе решений нажмите правой кнопкой мыши проект Native_UWP_V2 и выберите пункт Свойства.
    6. Выберите Подпись,а затем созданный PFX-файл в раскрывающемся списке Выберите файл ключа строгого имени.

Шаг 4. Запуск приложения

Для запуска примера приложения на локальном компьютере:

  1. На панели инструментов Visual Studio выберите нужную платформу (x64 или x86, но не ARM). Значение целевого устройства должно измениться с Устройство на Локальный компьютер.

  2. Выберите Отладка>Запустить без отладки.

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

Когда откроется окно приложения, можно нажать кнопку Call Microsoft Graph API (Вызов API Microsoft Graph), ввести данные для входа и дать согласие на разрешения, запрашиваемые приложением. В случае успешного выполнения приложение отобразит информацию о токенах и данные, полученные в результате вызова API Microsoft Graph.

Как работает этот пример

Diagram showing how the sample app generated by this quickstart works.

MSAL.NET

MSAL (Microsoft.Identity.Client) — это библиотека, используемая для выполнения входа пользователей и запросов маркеров безопасности. Маркеры безопасности используются для доступа к API, защищенному платформа удостоверений Майкрософт. MSAL можно установить, выполнив в консоли диспетчера пакетов Visual Studio следующую команду.

Install-Package Microsoft.Identity.Client

Инициализация MSAL

Добавив следующий код, вы можете добавить ссылку на MSAL.

using Microsoft.Identity.Client;

Затем выполните инициализацию MSAL с помощью следующего кода:

public static IPublicClientApplication PublicClientApp;
PublicClientApp = PublicClientApplicationBuilder.Create(ClientId)
                                                .WithRedirectUri("https://login.microsoftonline.com/common/oauth2/nativeclient")
                                                    .Build();

Значением ClientId является идентификатор приложения (клиента), зарегистрированного в Центре администрирования Microsoft Entra. Это значение можно найти на странице обзора приложения в Центре администрирования Microsoft Entra.

Запрос маркеров

В MSAL есть два метода получения маркеров в приложении UWP: AcquireTokenInteractive и AcquireTokenSilent.

Интерактивное получение маркера

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

  • первый вход пользователей в приложение;
  • когда пользователям может потребоваться повторно ввести учетные данные, так как истек срок действия пароля;
  • когда ваше приложение запрашивает доступ к ресурсу, для чего пользователь должен предоставить согласие;
  • когда требуется двухфакторная проверка подлинности.
authResult = await PublicClientApp.AcquireTokenInteractive(scopes)
                      .ExecuteAsync();

Параметр scopes содержит запрашиваемые области, такие как { "user.read" } для Microsoft Graph или { "api://<Application ID>/access_as_user" } для пользовательских веб-API.

Автоматическое получение маркера пользователя

Используйте метод AcquireTokenSilent, чтобы получить маркеры безопасности для доступа к защищенным ресурсам после первоначального метода AcquireTokenInteractive. Вы не хотите требовать от пользователя проверки своих учетных данных каждый раз, когда ему необходимо получить доступ к ресурсу. Большую часть времени вы хотите приобретать и обновлять маркеры без какого-либо взаимодействия с пользователем.

var accounts = await PublicClientApp.GetAccountsAsync();
var firstAccount = accounts.FirstOrDefault();
authResult = await PublicClientApp.AcquireTokenSilent(scopes, firstAccount)
                                      .ExecuteAsync();
  • scopes содержит запрашиваемые области, такие как { "user.read" } для Microsoft Graph или { "api://<Application ID>/access_as_user" } для пользовательских веб-API.
  • firstAccount указывает первую учетную запись в кэше (MSAL поддерживает несколько пользователей в одном приложении).

Справка и поддержка

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

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

В руководстве по классическому приложению Windows вы найдете пошаговые инструкции по созданию приложений и компонентов, в том числе полное описание того, о чем говорится в этом кратком руководстве.

Вызов API Microsoft Graph из приложения для универсальной платформы Windows (XAML)