快速入门：使用 Microsoft 标识平台保护 ASP.NET Core Web API

项目
02/14/2024

欢迎使用！这可能不是你期望看到的页面。在修复时，此链接应会将你转至正确的文章：

快速入门：调用受 Microsoft 标识平台保护的 ASP.NET Core Web API

对此造成你的不便，我们深表歉意；感谢你的耐心等待，我们正在努力解决此问题。

以下快速入门使用 ASP.NET Core Web API 代码示例来演示如何限制对授权帐户的资源访问。该示例支持对个人 Microsoft 帐户和任何 Microsoft Entra 组织中的帐户进行授权。

先决条件

具有活动订阅的 Azure 帐户。免费创建帐户。
Microsoft Entra 租户
最低要求 .NET 6.0 SDK
Visual Studio 2022 或 Visual Studio Code

步骤 1：注册应用程序

首先，在 Microsoft Entra 租户中注册 Web API，并通过执行以下步骤来添加范围：

至少以应用程序管理员的身份登录到 Microsoft Entra 管理中心。
浏览到“标识”>“应用程序”>“应用注册”。
选择“新注册”。
对于“名称”，请输入应用程序的名称。例如，输入 AspNetCoreWebApi-Quickstart。应用用户会看到此名称，以后可以更改此名称。
选择“注册” 。
在“管理”下，选择“公开 API”>“添加范围” 。针对应用程序 ID URI，通过选择保存并继续来接受默认，然后输入以下信息：

范围名称：access_as_user
谁能同意？ ：管理员和用户
管理员许可显示名称：Access AspNetCoreWebApi-Quickstart
管理员许可说明：Allows the app to access AspNetCoreWebApi-Quickstart as the signed-in user.
用户同意显示名称：Access AspNetCoreWebApi-Quickstart
用户同意说明：Allow the application to access AspNetCoreWebApi-Quickstart on your behalf.
状态：已启用

选择“添加范围”以完成范围添加。

步骤 2：下载 ASP.NET Core 项目

从 GitHub 下载 ASP.NET Core 解决方案。

注意

该代码示例当前面向 ASP.NET Core 3.1。该示例可以更新为使用 .NET Core 6.0，在以下步骤中进行了介绍：将示例代码更新为 ASP.NET Core 6.0。本快速入门将在不久后弃用，并将更新为使用 .NET 6.0。

步骤 3：配置 ASP.NET Core 项目

在此步骤中，示例代码会被配置为使用之前创建的应用注册。

将 .zip 文件解压缩到靠近磁盘根目录的本地文件夹中，以避免因 Windows 路径长度限制而导致错误。例如，解压到 C:\Azure-Samples。
在代码编辑器的 webapi 文件夹中打开解决方案。
在 appsettings.json 中，替换 ClientId 和 TenantId 的值。
```
"ClientId": "Enter_the_Application_Id_here",
"TenantId": "Enter_the_Tenant_Info_Here"
```
- Enter_the_Application_Id_Here 是已注册应用程序的应用程序（客户端）ID。
- 将 Enter_the_Tenant_Info_Here 替换为以下其中一项：
  - 如果应用程序仅支持此组织目录中的帐户，请将此值替换为目录（租户）ID（GUID）或租户名称（例如 contoso.onmicrosoft.com）。可以在应用的“概述”页上找到目录（租户）ID。
  - 如果应用程序支持任何组织目录中的帐户，请将此值替换为 organizations。
  - 如果应用程序支持所有 Microsoft 帐户用户，请将此值保留为 common。

在此快速入门中，请不要更改 appsettings.json 文件中的任何其他值。

步骤 4：将示例代码更新为 ASP.NET Core 6.0

若要将此代码示例更新为面向 ASP.NET Core 6.0，请执行以下步骤：

打开 webapi.csproj
删除以下行：

<TargetFramework>netcoreapp3.1</TargetFramework>

在其位置添加以下行：

<TargetFramework>netcoreapp6.0</TargetFramework>

此步骤将确保该示例面向 .NET Core 6.0 框架。

步骤 5：运行示例

打开终端，将目录更改为项目文件夹。
```
cd webapi
```
运行以下命令以生成解决方案：

dotnet run

如果生成成功，将显示以下输出：

Building...
info: Microsoft.Hosting.Lifetime[0]
    Now listening on: https://localhost:{port}
info: Microsoft.Hosting.Lifetime[0]
    Now listening on: http://localhost:{port}
info: Microsoft.Hosting.Lifetime[0]
    Application started. Press Ctrl+C to shut down.
...

示例工作原理

Startup 类

Microsoft.AspNetCore.Authentication 中间件使用托管进程启动时执行的 Startup 类。在其 ConfigureServices 方法中，调用了 Microsoft.Identity.Web 提供的 AddMicrosoftIdentityWebApi 扩展方法。

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
                .AddMicrosoftIdentityWebApi(Configuration, "AzureAd");
    }

AddAuthentication() 方法配置服务以添加基于 JwtBearer 的身份验证。

包含 .AddMicrosoftIdentityWebApi 的行会向 Web API 添加 Microsoft 标识平台授权。然后对其进行配置，使其根据 appsettings.json 配置文件的 AzureAD 部分中的信息来验证 Microsoft 标识平台颁发的访问令牌：

appsettings.json 密钥	说明
`ClientId`	已注册应用程序的应用程序（客户端）ID。
`Instance`	用户进行身份验证时使用的安全令牌服务 (STS) 终结点。此值通常为 `https://login.microsoftonline.com/`，指示 Azure 公有云。
`TenantId`	租户的名称或其租户 ID (GUID)，或使用工作帐户或学校帐户或 Microsoft 个人帐户进行用户登录时常用的名称。

Configure() 方法包含两个重要的方法 app.UseAuthentication() 和 app.UseAuthorization()，这些方法实现了命名功能：

// The runtime calls this method. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    // more code
    app.UseAuthentication();
    app.UseAuthorization();
    // more code
}

保护控制器、控制器的方法或 Razor 页

可以使用 [Authorize] 属性保护控制器或控制器方法。此属性只允许经过身份验证的用户，从而限制对控制器或方法的访问。如果用户尚未通过身份验证，可以启动身份验证质询来访问控制器。

namespace webapi.Controllers
{
    [Authorize]
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase

验证控制器中的范围

API 中的代码通过使用 HttpContext.VerifyUserHasAnyAcceptedScope> (scopeRequiredByApi); 来验证令牌中是否涵盖了所需范围：

namespace webapi.Controllers
{
    [Authorize]
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase
    {
        // The web API will only accept tokens 1) for users, and 2) having the "access_as_user" scope for this API
        static readonly string[] scopeRequiredByApi = new string[] { "access_as_user" };

        [HttpGet]
        public IEnumerable<WeatherForecast> Get()
        {
            HttpContext.VerifyUserHasAnyAcceptedScope(scopeRequiredByApi);

            // some code here
        }
    }
}

帮助和支持

如果需要帮助、需要报告问题，或者需要详细了解支持选项，请参阅面向开发人员的帮助和支持。

后续步骤

以下 GitHub 存储库包含 ASP.NET Core Web API 代码示例说明，以及更多演示如何实现以下目的的示例：

向新的 ASP.NET Core Web API 添加身份验证。
从桌面应用程序调用 Web API。
调用下游 API，如 Microsoft Graph 和其他 Microsoft API。

GitHub 上的 ASP.NET Core Web API 教程

通过