快速入门:在通用 Windows 平台应用中让用户登录并调用 Microsoft Graph
在本快速入门中,你将下载并运行一个代码示例,该示例演示通用 Windows 平台 (UWP) 应用程序如何让用户登录并获取访问令牌来调用 Microsoft Graph API。
有关说明,请参阅示例工作原理。
先决条件
- 具有活动订阅的 Azure 帐户。 免费创建帐户。
- Visual Studio
注意
MSAL.NET 版本 4.61.0 及更高版本不支持通用 Windows 平台 (UWP)、Xamarin Android 和 Xamarin iOS。 建议将 UWP 应用程序迁移到 WINUI 等新式框架。 阅读宣布即将弃用 MSAL.NET for Xamarin 和 UWP 中有关弃用的详细信息。
注册并下载快速入门应用
可以使用两个选项来启动快速入门应用程序:
选项 1:注册并自动配置应用,然后下载代码示例
- 转到 Microsoft Entra 管理中心 - 应用注册快速入门体验。
- 输入应用程序的名称并选择“注册”。
- 遵照说明下载内容,系统会自动配置新应用程序。
选项 2:注册并手动配置应用程序和代码示例
步骤 1:注册应用程序
提示
本文中的步骤可能因开始使用的门户而略有不同。
若要注册应用程序并将应用的注册信息添加到解决方案,请执行以下步骤:
- 登录到 Microsoft Entra 管理中心。
- 如果你有权访问多个租户,请使用顶部菜单中的“设置”图标
,通过“目录 + 订阅”菜单切换到你希望在其中注册应用程序的租户。
- 浏览至“标识”>“应用程序”>“应用注册”,然后选择“新建注册”。
- 输入应用程序的名称(例如
UWP-App-calling-MsGraph
)。 应用的用户可能会看到此名称,你稍后可对其进行更改。 - 在“支持的帐户类型”部分,选择“任何组织目录中的帐户和个人 Microsoft 帐户(例如 Skype、Xbox、Outlook.com)”。
- 选择“注册”创建应用程序,然后记录“应用程序(客户端) ID”,以供在后面的步骤中使用 。
- 在“管理”下,选择“身份验证”。
- 选择“添加平台”>“移动和桌面应用程序” 。
- 在“重定向 URI”下选择“Web”。
https://login.microsoftonline.com/common/oauth2/nativeclient
- 选择“配置” 。
步骤 2:下载项目
提示
若要避免由于 Windows 中路径长度限制导致的错误,我们建议将存档提取或克隆到驱动器根目录附近的目录中。
步骤 3:配置项目
将 .zip 存档解压缩到驱动器根附近的本地文件夹中。 例如,解压缩到 C:\Azure-Samples。
在 Visual Studio 中打开项目。 如果出现提示,请安装“通用 Windows 平台开发”工作负载和任何单独的 SDK 组件。
在 MainPage.Xaml.cs 中,将
ClientId
变量的值更改为先前注册的应用程序的“应用程序(客户端) ID”。private const string ClientId = "Enter_the_Application_Id_here";
可以在 Microsoft Entra 管理中心中应用的“概述”窗格上找到应用程序(客户端)ID(“标识”>“应用程序”>“应用注册”>“{你的应用注册}”)。
针对该包创建并选择一个新的自签名测试证书:
- 在“解决方案资源管理器”中,双击 Package.appxmanifest 文件。
- 选择“打包”>“选择证书...”>“创建...” 。
- 输入密码,然后选择“确定”。 创建一个名为 Native_UWP_V2_TemporaryKey.pfx 的证书。
- 选择“确定”来关闭“选择证书”对话框,然后验证解决方案资源管理器中是否有“Native_UWP_V2_TemporaryKey.pfx” 。
- 在“解决方案资源管理器”中,右键单击 Native_UWP_V2 项目,并选择“属性” 。
- 选择“签名”,然后在“选择强名称密钥文件”下拉列表中选择你创建的 .pfx 。
步骤 4:运行应用程序
在本地计算机上运行示例应用程序:
在 Visual Studio 工具栏中,选择适当的平台(可能为 x64 或 x86,不是 ARM)。 目标设备应从“设备”更改为“本地计算机” 。
选择“调试”>“在不调试的情况下启动”。
如果系统提示你执行此操作,你可能首先需要启用“开发人员模式”,然后再次执行“启动(不调试)”以启动该应用 。
出现应用的窗口时,可以选择“调用 Microsoft Graph API”按钮,输入凭据,并同意应用程序请求的权限。 如果成功,应用程序会显示从对 Microsoft Graph API 的调用中获取的一些令牌信息和数据。
示例工作原理
MSAL.NET
MSAL (Microsoft.Identity.Client) 是一个库,用于用户登录和请求安全令牌。 安全令牌用于访问受 Microsoft 标识平台保护的 API。 可在 Visual Studio 的包管理器控制台中运行以下命令,以便安装 MSAL:
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 管理中心中注册的应用的应用程序(客户端) ID。 可以在 Microsoft Entra 管理中心中应用的“概述”页上找到此值。
请求令牌
MSAL 有两种在 UWP 应用中获取令牌的方法:AcquireTokenInteractive
和 AcquireTokenSilent
。
以交互方式获取用户令牌
在某些情况下,需要强制用户通过弹出窗口来与 Microsoft 标识平台进行交互,以验证其凭据或授予同意。 示例包括:
- 用户首次登录应用程序
- 由于密码已过期,用户可能需要重新输入凭据的情况
- 应用程序正在请求访问需要用户同意的资源时
- 需要双重身份验证的情况
authResult = await PublicClientApp.AcquireTokenInteractive(scopes)
.ExecuteAsync();
scopes
参数包含所请求的范围,例如 { "user.read" }
(针对 Microsoft Graph)或 { "api://<Application ID>/access_as_user" }
(针对自定义 Web 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" }
(针对自定义 Web API)。firstAccount
指定缓存中的第一个用户帐户(MSAL 在单个应用中支持多个用户)。
帮助和支持
如果需要帮助、需要报告问题,或者需要详细了解支持选项,请参阅面向开发人员的帮助和支持。
后续步骤
试用 Windows 桌面教程,了解有关构建应用程序和新功能的完整分布指南,包括本快速入门的完整说明。