快速入門:在 Windows 傳統型應用程式中登入使用者並呼叫 Microsoft Graph
在本快速入門中,您會下載並執行程式碼範例,該範例會示範 Windows Presentation Foundation (WPF) 應用程式如何登入使用者,並取得存取權杖來呼叫 Microsoft Graph API。 您組建的桌面應用程式會使用與 Proof Key for Code Exchange (PKCE) 標準配對的授權碼流程。
如需圖例,請參閱此範例的運作方式。
必要條件
- 已安裝包含通用 Windows 平台開發工作負載的 Visual Studio
註冊並下載快速入門應用程式
有兩個選項可用來啟動快速入門應用程式:
選項 1:註冊和自動設定您的應用程式,然後下載程式碼範例
- 移至 AMicrosoft Entra 系統管理中心 - 應用程式註冊快速入門體驗。
- 輸入應用程式的名稱,並選取 [註冊]。
- 依照指示按一下滑鼠,即可下載並自動設定新的應用程式。
選項 2:註冊並手動設定您的應用程式和程式碼範例
步驟 1:註冊您的應用程式
提示
根據您開始使用的入口網站,本文中的步驟可能略有不同。
若要手動註冊您的應用程式,並將應用程式註冊資訊新增到您的解決方案,請執行下列步驟:
- 登入 Microsoft Entra 系統管理中心。
- 如果您有多個租用戶的存取權,請使用頂端功能表中的 [設定] 圖示
,從 [目錄 + 訂用帳戶] 功能表來切換至您要在其中註冊應用程式的租用戶。
- 瀏覽至 [身分識別]>[應用程式]>[應用程式註冊],選取 [新增註冊]。
- 輸入應用程式的名稱,例如
Win-App-calling-MsGraph
。 您的應用程式使用者可能會看到此名稱,而且您稍後可以加以變更。 - 在 [支援的帳戶類型] 區段中,選取 [任何組織目錄中的帳戶及個人的 Microsoft 帳戶],例如 Skype、Xbox、Outlook.com。
- 選取 [暫存器] 以建立應用程式。
- 在 [管理] 底下,選取 [驗證]。
- 選取 [新增平台]>[行動和傳統應用程式]。
- 在 [重新導向 URI] 區段中選取
https://login.microsoftonline.com/common/oauth2/nativeclient
,並且在 [自訂重新導向 URI] 中新增ms-appx-web://microsoft.aad.brokerplugin/{client_id}
,其中{client_id}
是應用程式的應用程式 (用戶端) 識別碼 (與msal{client_id}://auth
核取方塊中顯示的 GUID 相同)。 - 選取設定。
步驟 2:下載專案
提示
為了避免 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
如果您的應用程式支援 [任何組織目錄中的帳戶及個人的 Microsoft 帳戶],請將此值取代為
common
。若要尋找 [目錄 (租用戶) 識別碼] 和 [支援的帳戶類型] 的值,請移至 Microsoft Entra 系統管理中心中應用程式的 [概觀] 頁面。
步驟 4:執行應用程式
若要在 Visual Studio 中建置和執行範例應用程式,請選取 [偵錯] 功能表 > [開始偵錯],或按 F5 鍵。 應用程式的 MainWindow 隨即顯示。
應用程式的主要視窗出現時,請選取 [呼叫 Microsoft Graph API] 按鈕。 系統將會提示您使用 Microsoft Entra 帳戶 (公司或學校帳戶) 或 Microsoft 帳戶 (live.com、outlook.com) 認證進行登入。
如果您是第一次執行應用程式,則系統會提示您提供同意,以允許應用程式存取使用者設定檔,並將您登入。 同意所要求的權限之後,應用程式會顯示您已成功登入。 您應該會看到取自 Microsoft Graph API 呼叫的一些基本權杖資訊和使用者資料。
其他相關資訊
此範例的運作方式
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 系統管理中心註冊之應用程式的應用程式 (用戶端) 識別碼。 您可以在 Microsoft Entra 系統管理中心的應用程式 [概觀] 頁面中找到這個值。 |
要求權杖
MSAL 有兩種取得權杖的方法:AcquireTokenInteractive
與 AcquireTokenSilent
。
以互動方式取得使用者權杖
有些情況需要強制使用者透過快顯視窗與 Microsoft 身分識別平台進行互動,以驗證其認證或取得同意。 這些範例包含:
- 使用者首次登入應用程式
- 使用者因為密碼已過期而可能需要重新輸入其認證時
- 您的應用程式要求存取的資源需要使用者同意時
- 需要雙因素驗證時
authResult = await app.AcquireTokenInteractive(_scopes)
.ExecuteAsync();
其中: | 描述 |
---|---|
_scopes |
包含所要求的範圍,例如適用於 Microsoft Graph 的 { "user.read" } 或適用於自訂 Web API 的 { "api://<Application ID>/access_as_user" } 。 |
以無訊息方式取得使用者權杖
您不應該在每次使用者需要存取資源時都要求使用者驗證其認證。 在大部分情況下,您應該以不需要與使用者進行任何互動的方式處理權杖取得和更新作業。 在初始 AcquireTokenInteractive
方法之後,您可以使用 AcquireTokenSilent
方法取得權杖以存取受保護的資源:
var accounts = await app.GetAccountsAsync();
var firstAccount = accounts.FirstOrDefault();
authResult = await app.AcquireTokenSilent(scopes, firstAccount)
.ExecuteAsync();
其中: | 描述 |
---|---|
scopes |
包含所要求的範圍,例如適用於 Microsoft Graph 的 { "user.read" } 或適用於自訂 Web API 的 { "api://<Application ID>/access_as_user" } 。 |
firstAccount |
指定快取中的第一個使用者 (MSAL 在單一應用程式中支援多個使用者)。 |
說明與支援
如果您需要協助、想要回報問題,或想要深入了解您的支援選項,請參閱 開發人員的協助與支援。
下一步
嘗試 Windows Desktop 教學課程以取得建置應用程式與新功能的完整逐步指南,包括此快速入門的完整說明。