Document

.net core 3.1 Identity Server4 (Swagger UI授权)

.net core 3.1 Identity Server4 (Swagger UI授权)

Identity Server 4的目录：https://www.tnblog.net/hb/article/details/5458
项目地址：https://gitee.com/zuxiazijiahebo/IdentityServer4

前言

Swagger是一个有用的工具，用于使用标准JSON格式即时创建基本的API文档，该文档可以使用对开发人员友好的UI进行呈现。这些UI通常允许您开始通过浏览器发出演示请求。但是，一旦您开始使用OAuth保护此API，该如何保持Swagger文档的功能？

Swagger与OAuth授权服务器的集成已有相对完善的文档，因此在本文中，您将了解使用Swagger将IdentityServer支持添加到ASP.NET Core API的基础，然后了解这种方法的局限性以及也许值得探索。

本文将演示Swashbuckle。

准备API

首先，您需要使用IdentityServer保护的API。这里我们就创建一个ApIDemo2的API。在ConfigureServices中注册身份验证。

  1. services.AddAuthentication("Bearer")
  2. .AddJwtBearer("Bearer", options =>
  3. {
  4. options.Authority = "https://localhost:7200"; // 授权服务器地址
  5. //确定自己是哪个资源(资源名称)
  6. options.Audience = "ApiTwo";
  7. options.RequireHttpsMetadata = false; // 是否使用https进行通信
  8. //取消验证用户以及验证角色
  9. options.TokenValidationParameters = new Microsoft.IdentityModel.Tokens.TokenValidationParameters()
  10. {
  11. ValidateIssuer = false,
  12. ValidateAudience = false
  14. };
  15. });

tn然后通过更新Configure方法使其类似于以下内容，在HTTP管道中启用它：

  1. app.UseAuthentication();
  2. app.UseAuthorization();

然后，您可以通过使用AuthorizeAttribute动作或控制器来触发此操作。现在，您应该从这些受保护的端点获取401未经授权。这里我们在默认的WeatherForecastController下添加一个POST请求方法并添加授权标签Authorize。

  1. [Authorize]
  2. [HttpPost]
  3. public IEnumerable<WeatherForecast> Post()
  4. {
  5. var rng = new Random();
  6. return Enumerable.Range(1, 5).Select(index => new WeatherForecast
  7. {
  8. Date = DateTime.Now.AddDays(index),
  9. TemperatureC = rng.Next(-20, 55),
  10. Summary = Summaries[rng.Next(Summaries.Length)]
  11. })
  12. .ToArray();
  13. }

IdentityServer授权服务器配置

在GetApiResources方法中添加ApiScope。通过这种方法，你仅使用一个scope就能表示完全访问这个作用域的权限。

  1. new ApiScope("ApiTwo", "Full access to API #1")

要将Swagger UI配置为IdentityServer实现中的客户端应用程序（Client），您需要在IdentityServer中添加一个类似于以下内容的客户端条目。您正在使用授权码流PKCE和路径为的重定向URI /oauth2-redirect.html，这是Swagger UI的默认路径。如果您的Swagger UI具有基本路径，则还应将其包含在重定向URI中（即，如果Swagger UI处于/swagger，则重定向URI应该为/swagger/oauth2-redirect.html）。

  1. new Client
  2. {
  3. ClientId = "apidemo2_swagger",
  4. ClientName = "Swagger UI for ApIDemo2",
  5. ClientSecrets = {new Secret("secret".Sha256())}, // 这个自己整吧
  6. AllowedGrantTypes = GrantTypes.Code,
  7. // 启动Pkce
  8. RequirePkce = true,
  9. RequireClientSecret = false,
  10. RedirectUris = {"http://localhost:9001/swagger/oauth2-redirect.html"},
  11. AllowedCorsOrigins = {"http://localhost:9001"},
  12. AllowedScopes = { "ApiTwo" }
  13. },

Swashbuckle添加OAuth支持

回到我们的ApIDemo2中，让我们引入Swashbuckle：

  1. Install-Package Swashbuckle -Version 5.6.0
  2. Install-Package Swashbuckle.AspNetCore.Swagger -Version 5.6.3

我们在ConfigureServices方法中添加以下内容进行注册,使用一些描述性信息配置基本的Swagger文档。

  1. services.AddSwaggerGen(options =>
  2. {
  3. options.SwaggerDoc("v1", new OpenApiInfo { Title = "Protected API", Version = "v1" });
  4. // 我们会在这下面添加更多东西...
  5. });

接下来，您想将有关授权服务器的一些信息添加到swagger文档中。由于您的UI将在最终用户的浏览器中运行，并且在该浏览器中运行的JavaScript将需要访问令牌，因此您将使用授权代码流（code的授权方式）（PKCE））。

同时您需要告诉Swashbuckle授权和令牌端点的位置（请检查IdentityServer4文档），以及它将使用的作用域（其中键是作用域本身，而值是显示名称） ）。

  1. services.AddSwaggerGen(options =>
  2. {
  3. options.SwaggerDoc("v1", new OpenApiInfo { Title = "Protected API", Version = "v1" });
  5. options.AddSecurityDefinition("oauth2", new OpenApiSecurityScheme
  6. {
  7. Type = SecuritySchemeType.OAuth2,
  8. Flows = new OpenApiOAuthFlows
  9. {
  10. AuthorizationCode = new OpenApiOAuthFlow
  11. {
  12. AuthorizationUrl = new Uri("https://localhost:7200/connect/authorize"),
  13. TokenUrl = new Uri("https://localhost:7200/connect/token"),
  14. Scopes = new Dictionary<string, string>
  15. {
  16. {"ApiTwo", "Swagger UI for ApIDemo2"}
  17. }
  18. }
  19. }
  20. });
  21. options.OperationFilter<AuthorizeCheckOperationFilter>();
  22. });

现在，您需要告诉您的庞大文档，哪些端点需要访问令牌才能工作，并且它们可以返回401和403响应。您可以使用来执行此操作IOperationFilter，您可以在下面看到（已从EShopOnContainers示例存储库中的过滤器改编而成）。

  1. public class AuthorizeCheckOperationFilter : IOperationFilter
  2. {
  3. public void Apply(OpenApiOperation operation, OperationFilterContext context)
  4. {
  5. var hasAuthorize = context.MethodInfo.DeclaringType.GetCustomAttributes(true).OfType<AuthorizeAttribute>().Any()
  6. || context.MethodInfo.GetCustomAttributes(true).OfType<AuthorizeAttribute>().Any();
  8. if (hasAuthorize)
  9. {
  10. operation.Responses.Add("401", new OpenApiResponse { Description = "Unauthorized" });
  11. operation.Responses.Add("403", new OpenApiResponse { Description = "Forbidden" });
  13. operation.Security = new List<OpenApiSecurityRequirement>
  14. {
  15. new OpenApiSecurityRequirement
  16. {
  17. [
  18. new OpenApiSecurityScheme {Reference = new OpenApiReference
  19. {
  20. Type = ReferenceType.SecurityScheme,
  21. Id = "oauth2"}
  22. }
  23. ] = new[] { "ApiTwo" }
  24. }
  25. };
  26. }
  27. }
  28. }

然后，您可以像这样注册：

  1. options.OperationFilter<AuthorizeCheckOperationFilter>();

现在，您可以通过在Configure方法中添加以下内容，在管道中同时配置Swagger文档端点和Swagger UI ：

  1. app.UseSwagger();
  2. app.UseSwaggerUI(options =>
  3. {
  4. options.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
  6. options.OAuthClientId("apidemo2_swagger");
  7. options.OAuthAppName("Demo API - Swagger");
  8. options.OAuthUsePkce();
  9. });

运行测试





 

posted @ 2021-04-10 23:43  从未被超越  阅读(440)  评论(0)    收藏  举报