快速入門:從 ASP.NET 應用程式 Web 應用程式登入使用者並呼叫 Microsoft Graph API
在本快速入門中,您會下載並執行程式碼範例,此範例會示範可使用 Microsoft Entra 帳戶登入使用者的 ASP.NET Web 應用程式。
如需圖例,請參閱此範例的運作方式。
必要條件
- 具有有效訂用帳戶的 Azure 帳戶。 免費建立帳戶。
- Visual Studio 2022
- .NET Framework 4.7.2+
註冊並下載應用程式
提示
本文中的步驟可能略有不同,具體取決於您從哪個入口網站展開作業。
您有兩個選項可開始建立您的應用程式:自動或手動設定。
自動組態
如果您想要自動設定應用程式,然後下載程式碼範例,請遵循下列步驟:
- 以至少雲端應用程式管理員身分登入 Microsoft Entra 系統管理中心快速入門體驗。
- 輸入應用程式的名稱,並選取 [註冊]。
- 依照指示按一下滑鼠,即可下載並自動設定新的應用程式。
手動設定
如果您想要手動設定應用程式和程式碼範例,請使用下列程序。
步驟 1:註冊您的應用程式
- 以至少 雲端應用程式系統管理員 的身分登入 Microsoft Entra 系統管理中心。
- 如有多個租用戶的存取權,請使用頂端功能表中的 [設定] 圖示 ,從 [目錄 + 訂用帳戶] 功能表來切換至您要在其中註冊應用程式的租用戶。
- 瀏覽至 [身分識別] > [應用程式] > [應用程式註冊],然後選取 [新增註冊]。
- 針對 [名稱],輸入您的應用程式名稱。 例如,輸入 ASPNET-Quickstart。 您的應用程式使用者將會看到此名稱,您後續可加以變更。
- 將 [重新導向 URI] 類型設定為 [Web],並將值設定為
https://localhost:44368/
。 - 選取註冊。
- 在 [管理] 底下,選取 [驗證]。
- 在 [隱含授與和混合式流程] 區段中,選取 [識別碼權杖]。
- 選取 [儲存]。
步驟 2:下載專案
提示
為了避免 Windows 中路徑長度限制所造成的錯誤,建議您將封存解壓縮或將存放庫複製到磁碟機根目錄附近的目錄中。
步驟 3:執行專案
將 .zip 檔案解壓縮至接近根資料夾的本機資料夾。 例如,將解壓縮至 C:\Azure-Samples。
建議您將封存解壓縮到磁碟機根目錄附近的目錄中,以避免因 Windows 的路徑長度限制而造成錯誤。
在 Visual Studio 中開啟解決方案 (AppModelv2-WebApp-OpenIDConnect-DotNet.sln)。
視 Visual Studio 的版本而定,您可能需要以滑鼠右鍵按一下專案 AppModelv2-WebApp-OpenIDConnect-DotNet,然後選取 [還原 NuGet 套件]。
選取 [檢視]>[其他視窗]>[套件管理員主控台],以開啟套件管理員主控台。 接著,執行
Update-Package
。編輯 appsettings.json,並將參數
ClientId
、Tenant
和redirectUri
取代為以下內容:"ClientId" :"Enter_the_Application_Id_here" /> "TenantId": "Enter_the_Tenant_Info_Here" /> "RedirectUri" :"https://localhost:44368/" />
在該程式碼中:
Enter_the_Application_Id_here
是您先前建立之應用程式註冊的應用程式 (用戶端) 識別碼。 在 Microsoft Entra 系統管理中心 [應用程式註冊] 的應用程式 [概觀] 頁面上尋找應用程式 (用戶端) 識別碼。Enter_the_Tenant_Info_Here
是下列其中一個選項:- 如果您的應用程式支援 [僅限我的組織],請將此值取代為目錄 (租用戶) 識別碼或租用戶名稱 (例如
contoso.onmicrosoft.com
)。 在 Microsoft Entra 系統管理中心 [應用程式註冊] 的應用程式 [概觀] 頁面上尋找目錄 (租用戶) 識別碼。 - 如果您的應用程式支援 [任何組織目錄中的帳戶],請將此值取代為
organizations
。 - 如果您的應用程式支援 [所有 Microsoft 帳戶使用者],請將此值取代為
common
。
- 如果您的應用程式支援 [僅限我的組織],請將此值取代為目錄 (租用戶) 識別碼或租用戶名稱 (例如
redirectUri
是您在 Microsoft Entra 系統管理中心的 [應用程式註冊] 中稍早輸入的重新導向 URI。
其他相關資訊
本節會概述登入使用者所需的程式碼。 本概觀有助於了解程式碼的運作方式、主要引數為何,以及如何將登入新增至現有的 ASP.NET 應用程式。
此範例的運作方式
OWIN 中介軟體 NuGet 套件
您可以使用 OWIN 中介軟體套件在 ASP.NET 中搭配 OpenID Connect,設定具 Cookie 型驗證的驗證管線。 您可以在 Visual Studio 內的套件管理員主控台執行下列命令,以安裝這些套件:
Install-Package Microsoft.Identity.Web.Owin
Install-Package Microsoft.Identity.Web.GraphServiceClient
Install-Package Microsoft.Owin.Security.Cookies
OWIN 啟動類別
OWIN 中介軟體使用啟動類別,此類別會在裝載程序啟動時執行。 在本快速入門中,startup.cs 檔案位於根資料夾中。 下列程式碼顯示此快速入門所使用的參數:
public void Configuration(IAppBuilder app)
{
app.SetDefaultSignInAsAuthenticationType(CookieAuthenticationDefaults.AuthenticationType);
app.UseCookieAuthentication(new CookieAuthenticationOptions());
OwinTokenAcquirerFactory factory = TokenAcquirerFactory.GetDefaultInstance<OwinTokenAcquirerFactory>();
app.AddMicrosoftIdentityWebApp(factory);
factory.Services
.Configure<ConfidentialClientApplicationOptions>(options => { options.RedirectUri = "https://localhost:44368/"; })
.AddMicrosoftGraph()
.AddInMemoryTokenCaches();
factory.Build();
}
其中 | 描述 |
---|---|
ClientId |
來自註冊於 Azure 入口網站中之應用程式的應用程式識別碼。 |
Authority |
使用者進行驗證的 Security Token Service (STS) 端點。 這通常是用於公用雲端的 https://login.microsoftonline.com/{tenant}/v2.0 。 在該 URL 中,{tenant} 是您租用戶的名稱、您的租用戶識別碼,或通用端點之參考的 common 。 (通用端點用於多租用戶應用程式。) |
RedirectUri |
在使用者針對 Azure 身分識別平台完成驗證之後,會被送往的 URL。 |
PostLogoutRedirectUri |
在使用者登出之後,會被送往的 URL。 |
Scope |
所要求之範圍的清單 (以空格分隔)。 |
ResponseType |
要求驗證的回應包含授權碼和識別碼權杖。 |
TokenValidationParameters |
用於權杖驗證的參數清單。 在此案例中,ValidateIssuer 是設為 false ,以表示它可以接受來自任何個人或公司或學校帳戶類型的登入。 |
Notifications |
可在 OpenIdConnect 訊息上執行的委派清單。 |
驗證挑戰
您可在控制器中要求驗證挑戰,以強制使用者登入:
public void SignIn()
{
if (!Request.IsAuthenticated)
{
HttpContext.GetOwinContext().Authentication.Challenge(
new AuthenticationProperties{ RedirectUri = "/" },
OpenIdConnectAuthenticationDefaults.AuthenticationType);
}
}
提示
使用此方法要求驗證挑戰是選擇性的。 通常,您會在想要讓已驗證和未驗證的使用者都能存取檢視時,加以使用。 或者,您可以透過下一節所描述的方法來保護控制器。
保護控制器或控制器動作的屬性
您可以使用 [Authorize]
屬性來保護控制器或控制器動作。 此屬性會藉由僅允許已驗證的使用者存取控制器中的動作,來限制對控制器或動作的存取。 未驗證的使用者嘗試存取由 [Authorize]
屬性裝飾的其中一個動作或控制器時,就會自動發生驗證挑戰。
從控制器呼叫 Microsoft Graph
您可以從控制器呼叫 Microsoft Graph,方法是使用控制器上的 GetGraphServiceClient
擴充方法取得 GraphServiceClient 的執行個體,如下列程式碼所示:
try
{
var me = await this.GetGraphServiceClient().Me.GetAsync();
ViewBag.Username = me.DisplayName;
}
catch (ServiceException graphEx) when (graphEx.InnerException is MicrosoftIdentityWebChallengeUserException)
{
HttpContext.GetOwinContext().Authentication.Challenge(OpenIdConnectAuthenticationDefaults.AuthenticationType);
return View();
}
說明與支援
如果您需要協助、想要回報問題,或想要深入了解您的支援選項,請參閱 開發人員的協助與支援。
下一步
若要取得建置應用程式和新功能的完整逐步指南,包括本快速入門的完整說明,請嘗試 ASP.NET 教學課程。