ASP.NET Core Web API项目使用Azure AD保护API

xubzhlin

2019-10-23

关注关注

如果您正在构建一个由Azure AD保护的Web API，那么您需要进行身份验证来测试该API。在Swagger中配置OAuth 2允许您使用Swagger UI进行身份验证，并使用必要的身份验证头测试API。

配置的步骤是:

创建一个Web API项目
为Web API注册一个Azure AD (AAD)应用程序
更新Web API项目以使用Azure AD身份验证
为Swagger注册一个AAD应用程序
为Swagger AAD应用程序授予访问Web API AAD应用程序的权限
为Swagger AAD应用程序生成一个客户端秘密
在Swagger AAD应用程序上启用OAuth2隐式流
在Web API项目中添加Swagger

下面的例子是一个使用Swashbuckle.AspNetCore 3.0.0:的 Net Core 2.1 Web API应用程序。

1. 创建一个Web API项目

第一步是使用Visual Studio或通过命令行创建一个新的Web API项目:

md AspNetCore.AzureAd.Swagger
cd AspNetCore.AzureAd.Swagger
dotnet new webapi

如果您在Visual Studio中打开并运行项目，您应该会看到从默认控制器返回的值。

ASP.NET Core Web API项目使用Azure AD保护API

2. 在Azure AD中注册一个应用（Web API）

要对Azure AD进行身份验证，您需要添加一个Azure AD应用程序注册。这可以通过Azure门户http://portal.azure.com完成。

http://portal.azure.com > Azure Active Directory > App Registrations > New application registration

ASP.NET Core Web API项目使用Azure AD保护API

当应用程序注册完成后，将应用程序ID复制到记事本中，因为我们稍后会用到它

ASP.NET Core Web API项目使用Azure AD保护API

3. 更改Web API项目以使用 Azure AD authentication

添加以下 nuget package

Microsoft.AspNetCore.Authentication.AzureAD.UI

在 Startup.cs 文件中，将以下代码加入到ConfigureServices 方法中

services.AddAuthentication(AzureADDefaults.JwtBearerAuthenticationScheme)
           .AddAzureADBearer(options => Configuration.Bind("AzureAd", options));
services.AddMvc(config =>
{
    var policy = new AuthorizationPolicyBuilder()
        .RequireAuthenticatedUser()
        .Build();
    config.Filters.Add(new AuthorizeFilter(policy));
}).SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

这将需要对所有请求进行身份验证。

另外在 Startup.cs 文件中添加以下代码到Configure 方法中(在 app.UseMvc() 之前):

app.UseAuthentication();

在 appsettings.json 文件中，添加以下信息 (在使用源代码控制之前，请记住将敏感信息移出此处，例如使用管理用户机密):

国际版：

"AzureAd": {
  "Instance": "https://login.microsoftonline.com/",
  "Domain": "<Domain>",
  "TenantId": "<Directory ID>",
  "ClientId": "<Application ID>"
},
"Swagger": {
  "ClientId": "<Swagger:Application ID>",
  "ClientSecret": "<Swagger:Key Value>"
}

大陆版：

"AzureAd": {
  "Instance": "https://login.chinacloud.cn/",
  "Domain": "<Domain>",
  "TenantId": "<Directory ID>",
  "ClientId": "<Application ID>"
},
"Swagger": {
  "ClientId": "<Swagger:Application ID>",
  "ClientSecret": "<Swagger:Key Value>"
}

将步骤2中的应用程序ID复制到ClientId值中，并从Azure门户获取域和目录，如下所示:

ASP.NET Core Web API项目使用Azure AD保护API

在 ValuesController.cs 文件中，修改 Get 请求方法包含用户名，以便我们可以验证请求已经过身份验证。

public ActionResult<IEnumerable<string>> Get()
{
  return new string[] { "value1", User.Identity.Name };
}

运行应用程序并验证它返回一个401未经授权的错误(因为浏览器没有提供身份验证令牌):

ASP.NET Core Web API项目使用Azure AD保护API

4. 注册一个Azure AD应用程序（Swagger）

现在，我们将为Swagger web站点添加一个AAD应用程序，并授予它向web API应用程序发出请求的权限。

http://portal.azure.com > Azure Active Directory > App Registrations > New application registration.

在URL字段中输入在步骤1中创建的项目的基本URL，然后输入/swagger/ oaut2 -redirect.html。

ASP.NET Core Web API项目使用Azure AD保护API

将应用程序ID复制到appsettings中的Swagger:ClientId设置中。在步骤3中创建的json

ASP.NET Core Web API项目使用Azure AD保护API

Settings > Reply URLs > 确保重定向URL 为 https://localhost:<web api port>/swagger/oauth2-redirect.html

5. 为Swagger AAD应用程序授予访问Web API AAD应用程序的权限

Settings > Required Permissions > Add > Select an API > My Api

ASP.NET Core Web API项目使用Azure AD保护API

选中 ‘Access Web API’, 点击完成

ASP.NET Core Web API项目使用Azure AD保护API

6. 为Swagger AAD应用程序生成一个客户端密钥

Settings > Keys >

在appsettings.config中复制key值到Swagger:ClientSecret设置中。

7.在Swagger AAD应用程序上启用OAuth2隐式流

编辑清单文件并将oauth2AllowImplicitFlow更改为true

ASP.NET Core Web API项目使用Azure AD保护API

8. 在Web API项目中添加Swagger

添加以下NuGet包

swashbuckle.aspnetcore (测试使用3.0.0)

在 Startup.cs 文件中添加以下代码到 ConfigureServices 方法中:

services.AddSwaggerGen(c =>
{
  c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
  c.AddSecurityDefinition("oauth2", new OAuth2Scheme
  {
    Type = "oauth2",
    Flow = "implicit",
    AuthorizationUrl = $"https://login.microsoftonline.com/{Configuration["AzureAD:TenantId"]}/oauth2/authorize",
    Scopes = new Dictionary<string, string>
    {
      { "user_impersonation", "Access API" }
    }
  });
  c.AddSecurityRequirement(new Dictionary<string, IEnumerable<string>>
  {
    { "oauth2", new[] { "user_impersonation" } }
  });
});

添加以下代码到 Configure 方法中:

app.UseSwagger();
app.UseSwaggerUI(c =>
{
  c.OAuthClientId(Configuration["Swagger:ClientId"]);
  c.OAuthClientSecret(Configuration["Swagger:ClientSecret"]);
  c.OAuthRealm(Configuration["AzureAD:ClientId"]);
  c.OAuthAppName("My API V1");
  c.OAuthScopeSeparator(" ");
  c.OAuthAdditionalQueryStringParams(new { resource = Configuration["AzureAD:ClientId"] });
  c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});

在Visual Studio中更改开始页面以打开swagger

ASP.NET Core Web API项目使用Azure AD保护API