快速入門：在 ASP.NET Core 網頁應用程式中登入使用者

在這個快速入門中，你會建立一個 ASP.NET Core 網頁應用程式，並使用 Microsoft.Identity.Web 透過 Microsoft Entra ID 登入使用者。你可以從範本搭建新專案，或是為現有應用程式加裝認證。

如果你沒有Microsoft Entra租戶，開始前請先建立一個free帳號。

先決條件

.NET 9 SDK
Microsoft Entra ID 租用戶
在你的 Microsoft Entra 租戶中進行應用程式註冊。如果你需要建立申請表，請參見「註冊你的申請」。

從範本建立專案

最快的開始方式是先搭建一個預先設定好認證的新專案。

執行以下指令建立一個新的網頁應用程式，支援單一組織認證，並進入專案目錄：

dotnet new webapp --auth SingleOrg --name MyWebApp
cd MyWebApp

範本會產生一個已經設定好 Microsoft.Identity.Web 的專案。你只需要提供你的應用程式註冊資料。

打開 appsettings.json 並替換應用程式註冊中的 應用程式（客戶端）ID 和 目錄（租戶）ID：

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",
    "CallbackPath": "/signin-oidc"
  }
}

啟動應用程式以確認登入功能正常：

dotnet run

請前往 https://localhost:5001，然後選擇登入。如果出現 Microsoft 登入提示，表示設定正確。

為現有的網頁應用程式新增認證

如果你已有 ASP.NET Core 應用程式，請依照以下步驟新增 Microsoft Entra 登入功能。

安裝 NuGet 套件

加上 Microsoft.Identity.Web 程式庫。 Microsoft.Identity.Web 套件負責驗證，Microsoft.Identity.Web.UI 提供預先建置的登入與登出介面元件：

dotnet add package Microsoft.Identity.Web
dotnet add package Microsoft.Identity.Web.UI

設定認證服務

打開 Program.cs 並新增認證服務。以下程式碼用於註冊 OpenID Connect 與 Microsoft Entra 的認證，啟用下游 API 呼叫的憑證取得，並新增登入/登出介面功能：

using Microsoft.Identity.Web;
using Microsoft.Identity.Web.UI;

var builder = WebApplication.CreateBuilder(args);

// Add authentication
builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
                .AddMicrosoftIdentityWebApp(builder.Configuration, "AzureAd")
                .EnableTokenAcquisitionToCallDownstreamApi() // Optional: if calling APIs
                .AddInMemoryTokenCaches(); // For production, use distributed cache

// Add Razor Pages or MVC
builder.Services.AddRazorPages()
    .AddMicrosoftIdentityUI(); // Adds sign-in/sign-out UI

var app = builder.Build();

// Configure middleware
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();

app.UseAuthentication(); //  Add authentication middleware
app.UseAuthorization();

app.MapRazorPages();
app.MapControllers();

app.Run();

將 Microsoft Entra 配置新增

打開 appsettings.json 並新增該 AzureAd 區段。將佔位符值替換為你應用程式註冊的 應用程式（客戶端）ID。設定 TenantId 為應用程式的適當受眾：

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "common",
    "ClientId": "your-client-id-from-app-registration",
    "CallbackPath": "/signin-oidc"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.Identity.Web": "Information"
    }
  }
}

該 TenantId 數值決定哪些帳號可以登入：

價值	接受的帳戶
`common`	工作/學校與個人 Microsoft 帳號
`organizations`	僅限工作/學校帳號
`consumers`	僅限個人 Microsoft 帳戶
`<your-tenant-id>`	單一租戶 — 僅限您的組織

保護你的頁面

將該屬性加 [Authorize] 到需要登入的頁面或控制器上。

對於 Razor Pages，該 [Authorize] 屬性會將未經認證的使用者重新導向到登入頁面。登入後，像 Name 和 preferred_username 這類的使用者宣告可透過 User 物件取得。

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc.RazorPages;

[Authorize] //  Require authentication
public class IndexModel : PageModel
{
    public void OnGet()
    {
        var userName = User.Identity?.Name;
        var userEmail = User.FindFirst("preferred_username")?.Value;
    }
}

對於 MVC 控制器，同樣 [Authorize] 的屬性也適用於控制器或動作層級：

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

[Authorize] //  Require authentication
public class HomeController : Controller
{
    public IActionResult Index()
    {
        var userName = User.Identity?.Name;
        return View();
    }
}

在你的版面中加入導覽連結，讓使用者能登入或退出。MicrosoftIdentity 區域路由由 Microsoft.Identity.Web.UI 套件提供。以下 Razor 標記會根據使用者的認證狀態，有條件地呈現登出或登入：

<ul class="navbar-nav">
    @if (User.Identity?.IsAuthenticated == true)
    {
        <li class="nav-item">
            <span class="nav-link">Hello @User.Identity.Name!</span>
        </li>
        <li class="nav-item">
            <a class="nav-link" asp-area="MicrosoftIdentity" asp-controller="Account" asp-action="SignOut">Sign out</a>
        </li>
    }
    else
    {
        <li class="nav-item">
            <a class="nav-link" asp-area="MicrosoftIdentity" asp-controller="Account" asp-action="SignIn">Sign in</a>
        </li>
    }
</ul>

執行及測試

啟動應用程式以驗證認證是否有效：

dotnet run

導航至 https://localhost:5001。你應該會看到登入連結。選擇它以確認 Microsoft 登入流程是否成功完成。

註冊應用程式

如果你還沒有應用程式註冊，請依照以下步驟在 Azure 入口網站建立一個。

登入 Azure 入口網站。
流覽至 Microsoft Entra ID>應用程式註冊>[新註冊]。
輸入顯示名稱（例如「我的網頁應用程式」）。
選擇支援的帳號類型：
- 單一租戶 — 僅限組織內使用者
- 多租戶 — 任何組織中的使用者
- 多租戶 + 個人 — 所有Microsoft帳號
在 Redirect URI 中，將平台設為 Web ，並輸入 https://localhost:5001/signin-oidc。
選擇登記。
在概覽頁面複製 應用程式（用戶端）ID 與 目錄（租戶）ID。你需要在 appsettings.json 中的 ClientId 和 TenantId 欄位使用這些值。

設定選擇性設定

你的情況可能需要這些額外設定。

啟用 ID 憑證發放 — 某些混合認證情境要求 ID 憑證必須直接由授權端點發出。授權碼流程（由 Microsoft.Identity.Web 使用）是推薦的做法。只有在你的情境特別需要時才啟用此設定：

在你的應用程式註冊中，請點選認證。
在隱性授予與混合流程中，選擇 ID 標記。
選擇儲存。

Note

隱含補助金流是遺留流。 Microsoft 建議所有新應用都使用 PKCE 的授權碼流程。欲了解更多資訊，請參閱Microsoft 身分識別平台文件。

設定前端通道登出網址 — 當使用者從 Microsoft Entra 登出時，確保他們也從您的應用程式登出。

在你的應用程式註冊中，請點選認證。
在 前通路登出網址下，輸入 https://localhost:5001/signout-oidc。
選擇儲存。

解決常見錯誤

如果您在登入時遇到問題，請檢查這些常見錯誤。

錯誤	成因	解法
AADSTS50011：未註冊回應地址	重新導向程式碼與應用程式註冊間的 URI 不匹配	確認你的應用程式註冊中的重定向 URI 是否符合 `CallbackPath` （`/signin-oidc` 預設值）
AADSTS700016：找不到申請表	配置中的錯誤`ClientId`	確認應用程式`appsettings.json` 是否與你的應用程式註冊相符
權限設定錯誤	缺失或無效 `Instance` ，或 `TenantId`	設定 `Instance` 為 `https://login.microsoftonline.com/` ，確認 `TenantId` 有效

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-04-29