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

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

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

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

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

先决条件

步骤 1:注册应用程序

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

  1. 至少以应用程序管理员的身份登录到 Microsoft Entra 管理中心
  2. 浏览到“标识”>“应用程序”>“应用注册”。
  3. 选择“新注册”。
  4. 对于“名称”,请输入应用程序的名称。 例如,输入 AspNetCoreWebApi-Quickstart。 应用用户会看到此名称,以后可以更改此名称。
  5. 选择“注册” 。
  6. 在“管理”下,选择“公开 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.
  • 状态已启用
  1. 选择“添加范围”以完成范围添加。

步骤 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 项目

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

  1. 将 .zip 文件解压缩到靠近磁盘根目录的本地文件夹中,以避免因 Windows 路径长度限制而导致错误。 例如,解压到 C:\Azure-Samples。

  2. 在代码编辑器的 webapi 文件夹中打开解决方案。

  3. 在 appsettings.json 中,替换 ClientIdTenantId 的值。

    "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,请执行以下步骤:

  1. 打开 webapi.csproj
  2. 删除以下行:
<TargetFramework>netcoreapp3.1</TargetFramework>
  1. 在其位置添加以下行:
<TargetFramework>netcoreapp6.0</TargetFramework>

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

步骤 5:运行示例

  1. 打开终端,将目录更改为项目文件夹。

    cd webapi
    
  2. 运行以下命令以生成解决方案:

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。