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

Статья
10/24/2023

Из этого краткого руководства вы узнаете, как скачать и выполнить пример кода. В примере кода показано, как в приложении Windows Presentation Foundation (WPF) реализовать вход пользователей и получение маркера доступа для вызова API Microsoft Graph. В классическом приложении, который вы создаете, используется поток кода авторизации, сопоставленный со стандартом PKCE (Proof Key for Code Exchange).

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

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

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

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

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

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

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

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

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

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

Совет

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

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

Войдите в центр администрирования Microsoft Entra.
Если у вас есть доступ к нескольким клиентам, используйте значок Параметры в верхнем меню, чтобы переключиться на клиент, в котором вы хотите зарегистрировать приложение из меню каталогов и подписок.
Перейдите к приложениям> удостоверений>Регистрация приложений выберите "Создать регистрацию".
Введите имя приложения, например Win-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 и в поле Пользовательские URI перенаправления добавьте ms-appx-web://microsoft.aad.brokerplugin/{client_id}, где {client_id} — это идентификатор приложения (клиента) приложения (тот же GUID, который отображается в поле msal{client_id}://auth).
Выберите Настроить.

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

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

Совет

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

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

Извлеките ZIP-файл в локальную папку, расположенную как можно ближе к корню диска (например, C:\Azure-Samples).
Откройте проект в Visual Studio.

Измените файл App.Xaml.cs, заменив значения полей ClientId и Tenant следующим кодом:

private static string ClientId = "Enter_the_Application_Id_here";
private static string Tenant = "Enter_the_Tenant_Info_Here";

Где:

Enter_the_Application_Id_here — это идентификатор приложения (клиента), которое вы зарегистрировали.

Чтобы найти значение идентификатора приложения (клиента), перейдите на страницу обзора приложения в Центре администрирования Microsoft Entra.
Enter_the_Tenant_Info_Here может иметь несколько значений.
- Если приложение поддерживает учетные записи только в этом каталоге организации, замените это значение идентификатором клиента или именем клиента (например, contoso.microsoft.com).
- Если ваше приложение поддерживает вариант Учетные записи в любом каталоге организации, замените это значение на organizations.
- Если приложение поддерживает учетные записи в любом каталоге организации и личные учетные записи Майкрософт, замените это значение на common.
  
  Чтобы найти значения идентификатора каталога (клиента) и поддерживаемых типов учетных записей, перейдите на страницу обзора приложения в Центре администрирования Microsoft Entra.

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

Чтобы собрать и запустить пример приложения в Visual Studio, выберите Отладка>Начать отладку или нажмите клавишу F5. Откроется главное окно приложения.

В этом окне нажмите кнопку "Вызвать API Microsoft Graph". Вам будет предложено войти с помощью учетной записи Microsoft Entra (рабочей или учебной учетной записи) или учетных данных учетной записи Майкрософт (live.com, outlook.com).

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

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

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

using Microsoft.Identity.Client;

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

IPublicClientApplication publicClientApp = PublicClientApplicationBuilder.Create(ClientId)
                .WithRedirectUri("https://login.microsoftonline.com/common/oauth2/nativeclient")
                .WithAuthority(AzureCloudInstance.AzurePublic, Tenant)
                .Build();

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

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

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

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

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

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

authResult = await app.AcquireTokenInteractive(_scopes)
                                      .ExecuteAsync();

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

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

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

var accounts = await app.GetAccountsAsync();
var firstAccount = accounts.FirstOrDefault();
authResult = await app.AcquireTokenSilent(scopes, firstAccount)
                                      .ExecuteAsync();

Где:	Description
`scopes`	Содержит запрашиваемые области, такие как `{ "user.read" }` для Microsoft Graph или `{ "api://<Application ID>/access_as_user" }` для пользовательских веб-API.
`firstAccount`	Указывает первого пользователя в кэше (MSAL поддерживает нескольких пользователей в одном приложении).

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

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

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

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

Руководство по вызову API Graph

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