快速入门:在 Windows 桌面应用中让用户登录并调用 Microsoft Graph

在本快速入门中,你将下载并运行一个代码示例,该示例演示 Windows Presentation Foundation (WPF) 应用程序如何让用户登录并获取访问令牌来调用 Microsoft Graph API。 生成的桌面应用使用与代码交换证明密钥 (PKCE) 标准配对的授权代码流。

有关说明,请参阅示例工作原理

先决条件

注册并下载快速入门应用

可以使用两个选项来启动快速入门应用程序:

选项 1:注册并自动配置应用,然后下载代码示例

  1. 转到 Microsoft Entra 管理中心 - 应用注册快速入门体验。
  2. 输入应用程序的名称并选择“注册”。
  3. 遵照说明下载内容,并只需单击一下自动配置新应用程序。

选项 2:注册并手动配置应用程序和代码示例

步骤 1:注册应用程序

提示

本文中的步骤可能因开始使用的门户而略有不同。

若要手动注册应用程序并将应用的注册信息添加到解决方案,请执行以下步骤:

  1. 登录 Microsoft Entra 管理中心
  2. 如果你有权访问多个租户,请使用顶部菜单中的“设置”图标 ,通过“目录 + 订阅”菜单切换到你希望在其中注册应用程序的租户。
  3. 浏览至“标识”>“应用程序”>“应用注册”,然后选择“新建注册”。
  4. 输入应用程序的名称(例如 Win-App-calling-MsGraph)。 应用的用户可能会看到此名称,你稍后可对其进行更改。
  5. 在“支持的帐户类型”部分,选择“任何组织目录中的帐户和个人 Microsoft 帐户(例如 Skype、Xbox、Outlook.com)”。
  6. 选择“注册”以创建应用程序。
  7. 在“管理”下,选择“身份验证”。
  8. 选择“添加平台”>“移动和桌面应用程序” 。
  9. 在“重定向 URI”部分中,选择 https://login.microsoftonline.com/common/oauth2/nativeclient,然后在“自定义重定向 URI”中添加 ms-appx-web://microsoft.aad.brokerplugin/{client_id},其中 {client_id} 是应用程序的应用程序(客户端)ID(与 msal{client_id}://auth 复选框中显示的 GUID 相同) 。
  10. 选择“配置” 。

步骤 2:下载项目

下载 WPF 示例应用程序

提示

若要避免由于 Windows 中路径长度限制导致的错误,我们建议将存档提取或克隆到驱动器根目录附近的目录中。

步骤 3:配置项目

  1. 将 zip 文件提取到靠近磁盘根目录的本地文件夹,例如 C:\Azure-Samples

  2. 在 Visual Studio 中打开项目。

  3. 编辑 App.Xaml.cs 并将字段 ClientIdTenant 的值替换为以下代码:

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

其中:

  • Enter_the_Application_Id_here - 是已注册应用程序的应用程序(客户端)ID

    若要查找应用程序(客户端)ID 的值,请转到 Microsoft Entra 管理中心中应用的“概述”页。

  • Enter_the_Tenant_Info_Here - 设置为以下选项之一:

    • 如果应用程序支持“此组织目录中的帐户”,请将该值替换为租户 ID租户名称(例如 contoso.microsoft.com)

    • 如果应用程序支持“任何组织目录中的帐户”,请将该值替换为organizations

    • 如果应用支持“任何组织目录中的帐户和个人 Microsoft 帐户”,请将此值替换为“common”。

      若要查找目录(租户)ID 的值和支持的帐户类型,请转到 Microsoft Entra 管理中心中应用的“概述”页。

步骤 4:运行应用程序

若要在 Visual Studio 中生成并运行示例应用程序,请选择“调试菜单”>开始调试,或按 F5 键。 将显示应用程序的 MainWindow。

当应用的主窗口出现时,选择“调用 Microsoft 图形 API”按钮。 系统会提示你使用 Microsoft Entra 帐户(工作或学校帐户)或 Microsoft 帐户(live.com、outlook.com)凭据登录。

如果是首次运行应用程序,系统会提示你同意允许应用程序访问用户配置文件并登录。 同意请求的权限后,应用将显示你已成功登录。 应会看到一些基本令牌信息和用户数据,这些信息通过调用 Microsoft Graph API 获得。

详细信息

示例工作原理

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

MSAL.NET

MSAL (Microsoft.Identity.Client) 是一个库,用于用户登录和请求令牌,此类令牌用于访问受 Microsoft 标识平台保护的 API。 可在 Visual Studio 的包管理器控制台中运行以下命令,以便安装 MSAL:

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();
其中: 说明
ClientId 是在 Microsoft Entra 管理中心中注册的应用程序(客户端)ID。 可以在 Microsoft Entra 管理中心中应用的“概述”页上找到此值。

请求令牌

MSAL 有两种获取令牌的方法:AcquireTokenInteractiveAcquireTokenSilent

以交互方式获取用户令牌

在某些情况下,需要强制用户通过弹出窗口来与 Microsoft 标识平台进行交互,以验证其凭据或授予同意。 示例包括:

  • 用户首次登录应用程序
  • 由于密码已过期,用户可能需要重新输入凭据的情况
  • 应用程序正在请求访问用户需要同意的资源的情况
  • 需要双重身份验证的情况
authResult = await app.AcquireTokenInteractive(_scopes)
                                      .ExecuteAsync();
其中: 说明
_scopes 包含所请求的范围,例如 { "user.read" }(针对 Microsoft Graph)或 { "api://<Application ID>/access_as_user" }(针对自定义 Web API)。

以无提示方式获取用户令牌

你不希望在用户每次需要访问资源时都要求其验证其凭据。 大多数情况下,你希望在无需任何用户交互的情况下进行令牌获取和续订。 可以使用 AcquireTokenSilent 方法获取令牌,以在初始 AcquireTokenInteractive 方法后访问受保护资源:

var accounts = await app.GetAccountsAsync();
var firstAccount = accounts.FirstOrDefault();
authResult = await app.AcquireTokenSilent(scopes, firstAccount)
                                      .ExecuteAsync();
其中: 说明
scopes 包含所请求的范围,例如 { "user.read" }(针对 Microsoft Graph)或 { "api://<Application ID>/access_as_user" }(针对自定义 Web API)。
firstAccount 指定缓存中的第一个用户(MSAL 支持单个应用中的多个用户)。

帮助和支持

如果需要帮助、需要报告问题,或者需要详细了解支持选项,请参阅面向开发人员的帮助和支持

后续步骤

试用 Windows 桌面教程,了解有关构建应用程序和新功能的完整分布指南,包括本快速入门的完整说明。