快速入门：在 ASP.NET Core Web 应用中登录用户

在本快速入门中，你将创建一个使用 Microsoft.Identity.Web 通过 Microsoft Entra ID 让用户登录的 ASP.NET Core Web 应用。 可以从模板搭建新项目基架，也可以向现有应用添加身份验证。

如果没有Microsoft Entra租户，请在开始前创建免费帐户。

先决条件

• .NET 9 SDK
• Microsoft Entra ID租户
• Microsoft Entra 租户中的应用注册。 如果需要创建一个应用程序，请参阅 “注册应用程序”。

从模板创建项目

最快速的入门方法是使用预配置身份验证搭建新项目。

运行以下命令，使用单组织身份验证创建新的 Web 应用，并导航到项目目录：

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登录提示，则配置正确。

将身份验证添加到现有 Web 应用

如果你有现有的 ASP.NET Core应用，请按照下列步骤添加Microsoft Entra登录。

安装 NuGet 包

添加Microsoft。Identity.Web 库。 Microsoft.Identity.Web 包处理身份验证，Microsoft.Identity.Web.UI提供预生成的登录和注销 UI 组件：

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

配置身份验证服务

打开 Program.cs 并添加身份验证服务。 以下代码向 Microsoft Entra 注册 OpenID Connect 身份验证，启用令牌以用于下游 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 值确定了可以登录的帐户。

保护页面

将 [Authorize] 属性添加到需要登录的页面或控制器。

对于 Razor Pages，该属性会将 [Authorize] 未经身份验证的用户重定向到登录页。 登录后，用户声明Namepreferred_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 门户中创建一个。

1. 登录到 Azure 门户。
2. 导航到 Microsoft Entra ID>应用注册>新注册。
3. 输入显示名称（例如“我的 Web 应用”）。
4. 选择支持的帐户类型：
   • 单租户 - 仅供组织内部用户
   • 多租户 - 任何组织中的用户
   • 多租户 + 个人 — 所有 Microsoft 帐户
5. 在 “重定向 URI”下，将平台设置为 Web 并输入 https://localhost:5001/signin-oidc。
6. 选择注册。
7. 在概述页上，复制 应用程序（客户端）ID 和 目录（租户）ID。 需要这些值用于appsettings.json中的ClientId和TenantId字段。

配置可选设置

你的方案可能需要这些附加设置。

启用 ID 令牌颁发 - 某些混合身份验证方案要求直接从授权终结点颁发 ID 令牌。 授权代码流（Microsoft.Identity.Web 使用的）是推荐的方法。 仅当方案特别需要此设置时，才启用此设置：

1. 在应用注册中，转到 “身份验证”。
2. 在 “隐式授予和混合流”下，选择“ ID 令牌”。
3. 选择保存。

配置前端通道注销 URL — 确保用户在注销 Microsoft Entra 时，同时也会注销您的应用程序。

1. 在应用注册中，转到 “身份验证”。
2. 在 “前端通道注销 URL”下，输入 https://localhost:5001/signout-oidc。
3. 选择保存。

解决常见问题

如果在登录过程中遇到问题，请检查这些常见错误。

相关内容

• 从 Web 应用调用下游 API
• 授权
• 令牌缓存概述
• 快速入门：Web API