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

Статья
05/19/2024

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

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

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

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

Примечание.

MSAL.NET версии 4.61.0 и выше не поддерживают универсальная платформа Windows (UWP), Xamarin Android и Xamarin iOS. Рекомендуется перенести приложения UWP в современные платформы, такие как WINUI. Дополнительные сведения о нерекомендуемом объявлении о предстоящей отмене MSAL.NET для Xamarin и UWP.

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

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

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

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

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

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

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

Совет

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

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

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

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

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

Совет

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

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

Извлеките ZIP-архив в локальную папку рядом с корнем диска. Например, в папку C:\Azure-Samples.
Откройте проект в Visual Studio. При наличии запроса установите рабочую нагрузку Разработка приложений для универсальной платформы Windows и отдельные компоненты пакета SDK.
В MainPage.Xaml.cs замените значение переменной ClientId на идентификатор приложения (клиент), которое вы зарегистрировали ранее.
```
private const string ClientId = "Enter_the_Application_Id_here";
```
Идентификатор приложения (клиента) можно найти на панели обзора приложения в Центре администрирования Microsoft Entra (Приложения> удостоверений>Регистрация приложений>{Регистрация приложения}).
Создайте и выберите новый самозаверяющий тестовый сертификат для пакета:
1. В Обозревателе решений дважды щелкните файл Package.appxmanifest.
2. Выберите Упаковка>Выбор сертификата...>Создать....
3. Введите пароль и нажмите OK. Будет создан сертификат с именем Native_UWP_V2_TemporaryKey.pfx.
4. Нажмите кнопку ОК, чтобы закрыть диалоговое окно Выбор сертификата, а затем убедитесь, что вы видите Native_UWP_V2_TemporaryKey.pfx в Обозревателе решений.
5. В Обозревателе решений нажмите правой кнопкой мыши проект Native_UWP_V2 и выберите пункт Свойства.
6. Выберите Подпись,а затем созданный PFX-файл в раскрывающемся списке Выберите файл ключа строгого имени.

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

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

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

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

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

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

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

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)

Поделиться через