Keycloak & Asp.net core webapi 整合跳坑之旅

前言

之前，一直使用IdentityServer4作为.net core程序的外部身份认证程序，ID4的优点自不必说了，缺点就是缺乏完善的管理界面。

后来，学习java quarkus框架时，偶然遇到了keycloak，具备完善的管理界面，并且支持多个realms，和quarkus oidc结合非常完美，于是就思考能否用keycloak来控制.net core程序的身份认证。

准备工作

dotnet new webapi，创建一个默认的webapi项目

安装keycloak的docker版本，我这里使用mariadb来持久化keycloak的数据，贴出docker-compose文件如下：

version: '3'
services:
  keycloak:
    image: jboss/keycloak:9.0.3
    environment:
      KEYCLOAK_USER: admin
      KEYCLOAK_PASSWORD: admin
      DB_USER: keycloak
      DB_PASSWORD: password
    ports:
      - 8180:8080

  mariadb:
    image: mariadb:10.4
    command: ['--character-set-server=utf8','--collation-server=utf8_general_ci','--default-time-zone=+8:00']
    environment:
      MYSQL_ROOT_PASSWORD: example
      MYSQL_DATABASE: keycloak
      MYSQL_USER: keycloak
      MYSQL_PASSWORD: password
    volumes:
      - mariadata:/var/lib/mysql

volumes:
  mariadata:

docker-compose up 启动keycloak，然后可以在 http://localhost:8180 访问管理界面。

不要使用默认的realm，新建一个realm，比如“test2”。

然后新建client，比如“webapi”，地址填写 http://localhost:5000, 就是asp.net core webapi程序即将运行的地址。

然后创建角色和用户。

代码编写

修改Controllers/WeatherForcastController.cs

在控制器类前面增加[Authorize], 并且修改反馈的内容，方便调试。

 using System;
 using System.Collections.Generic;
 using System.Linq;
 using System.Security.Claims;
 using System.Threading.Tasks;
 using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.Extensions.Logging;

 namespace WebApi1.Controllers
 {
     [Authorize]
     [ApiController]
     [Route("[controller]")]
     public class WeatherForecastController : ControllerBase
     {
         private static readonly string[] Summaries = new[]
         {
             "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
         };

         private readonly ILogger<WeatherForecastController> _logger;

         public WeatherForecastController(ILogger<WeatherForecastController> logger)
         {
             _logger = logger;
         }

         [HttpGet]
         public IEnumerable<string> Get()
         {
             var result = new List<string>();
             foreach (var claim in User.Claims)
                 result.Add(claim.Type+": "+claim.Value);

             result.Add("username: " + User.Identity.Name);
             result.Add("IsAdmin: " + User.IsInRole("admin").ToString());
             return result;
         }
     }
 }

注意12行。

修改startup.cs

 namespace WebApi1
 {
     public class Startup
     {
         public Startup(IConfiguration configuration)
         {
             Configuration = configuration;
         }

         public IConfiguration Configuration { get; }

         // This method gets called by the runtime. Use this method to add services to the container.
         public void ConfigureServices(IServiceCollection services)
         {
             services.AddControllers();

             services.AddAuthentication(options =>
             {
                 options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
                 options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
             }).AddJwtBearer(options =>
                 {
                     options.Authority = "http://localhost:8180/auth/realms/test2";
                     options.RequireHttpsMetadata = false;
                     options.Audience = "account";
                     options.TokenValidationParameters = new TokenValidationParameters{
                         NameClaimType = "preferred_username"
                     };

                     options.Events = new JwtBearerEvents{
                         OnTokenValidated = context =>{
                             var identity = context.Principal.Identity as ClaimsIdentity;
                             var access = context.Principal.Claims.FirstOrDefault(p => p.Type == "realm_access");
                             var jo = JObject.Parse(access.Value);
                             foreach (var role in jo["roles"].Values()){
                                 identity.AddClaim(new Claim(ClaimTypes.Role, role.ToString()));
                             }
                             return Task.CompletedTask;
                         }
                     };
                 });
         }

         // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
         public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
         {
             if (env.IsDevelopment())
             {
                 app.UseDeveloperExceptionPage();
             }

             //app.UseHttpsRedirection();

             IdentityModelEventSource.ShowPII = true;

             app.UseRouting();

             app.UseAuthentication();
             app.UseAuthorization();

             app.UseEndpoints(endpoints =>
             {
                 endpoints.MapControllers();
             });
         }
     }
 }

这里的代码是遇到几个坑并解决之后的结果，下面列举遇到的坑和解决方法：

1、使用postman获取token之后，访问资源仍提示401，查看具体错误信息是audience=account，但是我们根据各种教程设置为webapi（同client-id）

第25行，设置audience=account后解决。

到现在也不知道为啥keycloak返回的是account而不是client-id。

2、控制器中User.Identity.Name=null

这主要源于ClaimType名称的问题，keycloak返回的claims中，使用preferred_username来表示用户名，和asp.net core identity默认的不同

第26行，修改默认的Claim名称后，User.Identity.Name可以正常返回用户名。

3、控制器中无法获取角色信息

和用户名类似，也是因为ClaimType问题，keycloak返回的角色信息claim名称是realm_access，而且内容是一段json文本，需要解析处理。

第30行，OnTokenValidated 事件中对角色Claim进行转换，然后角色信息正常。

修改后就可以使用[Authorize(Roles="admin")]来保护控制器或者方法了。

最后列举WeatherForecastController 的Get方法返回的各种claims和其他信息

[
    "exp: 1587544810",
    "iat: 1587544510",
    "jti: 72648e7f-3bb4-4db1-b866-33cc26a5e5a1",
    "iss: http://localhost:8180/auth/realms/test2",
    "aud: account",
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier: 8811d051-52a6-40fc-b7f3-15d949fb25cd",
    "typ: Bearer",
    "azp: webapi",
    "session_state: a9fb6a90-368b-4619-8789-43e26c7f2b85",
    "http://schemas.microsoft.com/claims/authnclassreference: 1",
    "allowed-origins: http://localhost:5000",
    "realm_access: {\"roles\":[\"offline_access\",\"admin\",\"uma_authorization\"]}",
    "resource_access: {\"account\":{\"roles\":[\"manage-account\",\"manage-account-links\",\"view-profile\"]}}",
    "scope: email profile",
    "email_verified: false",
    "preferred_username: admin",
    "http://schemas.microsoft.com/ws/2008/06/identity/claims/role: offline_access",
    "http://schemas.microsoft.com/ws/2008/06/identity/claims/role: admin",
    "http://schemas.microsoft.com/ws/2008/06/identity/claims/role: uma_authorization",
    "username: admin",
    "IsAdmin: True"
]