你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

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

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

快速入门:保护 ASP.NET Core Web API

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

在本快速入门中,我们将下载一个 ASP.NET Core Web API 代码示例并查看其对资源的访问权限限制为仅授权帐户的方式。 该示例支持对任何 Azure Active Directory (Azure AD) 组织中的个人 Microsoft 帐户和帐户进行授权。

先决条件

步骤 1:注册应用程序

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

  1. 登录 Azure 门户
  2. 如果有权访问多个租户,请使用顶部菜单中的“目录 + 订阅”筛选器 ,以切换到要在其中注册应用程序的租户。
  3. 搜索并选择“Azure Active Directory” 。
  4. 在“管理”下,选择“应用注册”>“新建注册” 。
  5. 对于“名称”,请输入应用程序名称。 例如,输入 AspNetCoreWebApi-Quickstart。 应用的用户会看到此名称,你稍后可对其进行更改。
  6. 选择“注册” 。
  7. 在“管理”下,选择“公开 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.
    • 状态已启用
  8. 选择“添加范围”以完成范围添加。

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

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

提示

若要避免由于 Windows 中路径长度限制导致的错误,我们建议将存档提取或克隆到驱动器根目录附近的目录中。

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

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

  1. 将 .zip 存档提取到驱动器根附近的文件夹中。 例如,解压到 C:\Azure-Samples。

    建议将存档解压到驱动器根附近的目录中,以避免在 Windows 上出现路径长度限制导致的错误。

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

  3. 打开 appsettings.json 文件,并修改以下代码:

    "ClientId": "Enter_the_Application_Id_here",
    "TenantId": "Enter_the_Tenant_Info_Here"
    
    • Enter_the_Application_Id_here 替换为在 Azure 门户中注册的应用程序的应用程序(客户端)ID。 可以在应用的“概述”页上找到应用程序(客户端)ID。
    • Enter_the_Tenant_Info_Here 替换为以下其中一项:
      • 如果应用程序支持“仅限此组织目录中的帐户”,请将此值替换为目录(租户)ID(GUID)或租户名称(例如,contoso.onmicrosoft.com)。 你可以在应用的“概述”页上找到目录(租户)ID。
      • 如果应用程序支持“任何组织目录中的帐户”,请将该值替换为 organizations
      • 如果应用程序支持“所有 Microsoft 帐户用户”,请将该值保留为 common

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

示例工作原理

Web API 从客户端应用程序接收令牌,Web API 中的代码验证该令牌。 方案:受保护的 Web API 中详细说明了此方案。

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 Azure 门户中注册的应用程序的“应用程序(客户端) 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
        }
    }
}

帮助和支持

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

后续步骤

包含此 ASP.NET Core Web API 代码示例的 GitHub 存储库包含说明和更多代码示例,这些示例向你展示如何:

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