Быстрое начало: Вход пользователей и вызов Microsoft Graph в приложении Универсальной платформы Windows

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

Узнайте, как работает пример для иллюстрации.

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

• Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно.
• Visual Studio

Зарегистрируйтесь и скачайте своё приложение для быстрого старта.

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

• [Express] Вариант 1. Регистрация и автоматическая настройка приложения, а затем скачивание примера кода
• [Вручную] Вариант 2. Регистрация и настройка приложения и примера кода вручную

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

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

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

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

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

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

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

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

Шаг 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 (Entra ID>Регистрация приложений>{Регистрация вашего приложения}).

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

   1. В обозревателе решений дважды щелкните файл Package.appxmanifest .
   2. Выберите Упаковка>Выбрать сертификат...>Создайте....
   3. Введите пароль и нажмите кнопку "ОК". Создается сертификат с именем 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. Выберите Отладка>Запуск без отладки.

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

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

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

MSAL.NET

MSAL (Microsoft.Identity.Client) — это библиотека, используемая для входа пользователей и запроса маркеров безопасности. Маркеры безопасности используются для доступа к API, защищенному идентификационной платформой Microsoft. Вы можете установить 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, чтобы получить полное пошаговое руководство по созданию приложений и новых функций, включая полное объяснение этого быстрого старта.