ionic + asp.net core webapi + keycloak实现前后端用户认证和自动生成客户端代码

概述

本文使用ionic/angular开发网页前台，asp.net core webapi开发restful service，使用keycloak保护前台页面和后台服务，并且利用open api自动生成代码功能，减少了重复代码编写。

准备工作

1、使用docker搭建并启动keycloak服务器，新建名称为test的realm，并建立几个测试用户，并且建立1个名称为my_client的客户端，注意客户端的回调url要正确。

2、安装ionic，使用 ionic start myApp tabs，初始化一个tabs格式的前端应用。

3、使用dotnet new webapi命令创建一个webapi。

WebApi设置

1、控制器使用[Authorize]保护

namespace WebApi1.Controllers
{
    /// <summary>
    /// 天气预报服务
    /// </summary>
    [Authorize]
    [ApiController]
    [Route("[controller]")]
    [Produces("application/json")]
    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;
        }

        /// <summary>
        /// 获取全部天气预报信息
        /// </summary>
        /// <returns></returns>
        [HttpGet]
        public IEnumerable<WeatherForecast> Get()
        {
            var rng = new Random();
            return Enumerable.Range(, ).Select(index => new WeatherForecast
            {
                Date = DateTime.Now.AddDays(index),
                TemperatureC = rng.Next(-, ),
                Summary = Summaries[rng.Next(Summaries.Length)]
            })
            .ToArray();
        }
    }
}

2、修改项目文件

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>netcoreapp3.</TargetFramework>
  </PropertyGroup>

  <PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);</NoWarn>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="3.1.4" />
    <PackageReference Include="Swashbuckle.AspNetCore" Version="5.4.1" />
  </ItemGroup>

</Project>

1591那一段主要是为了编译时生成xml格式的注释文档，该文档给OpenApi使用，用来给方法和属性添加注释。

JwtBearer用于实现基于JWT的身份认证，Swashbuckle.AspNetCore用于自动生成OpenApi文档以及图形界面。

3、修改Startup

 namespace WebApi1
 {
     public class Startup
     {
         readonly string MyAllowSpecificOrigins = "_myAllowSpecificOrigins";

         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.AddCors(options =>
             {
                 options.AddPolicy(name: MyAllowSpecificOrigins,
                                 builder =>
                                 {
                                     builder.WithOrigins("http://localhost:8100").AllowAnyHeader().AllowAnyMethod();
                                 });
             });

             services.AddControllers();

             services.AddSwaggerGen(c =>
             {
                 c.SwaggerDoc("v1", new OpenApiInfo { Title = "一个测试用的天气预报服务", Version = "v1" });

                 var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                 var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
                 c.IncludeXmlComments(xmlPath);
             });

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

         // 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();

             // Enable middleware to serve generated Swagger as a JSON endpoint.
             app.UseSwagger();

             // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),
             // specifying the Swagger JSON endpoint.
             app.UseSwaggerUI(c =>
             {
                 c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
                 c.RoutePrefix = string.Empty;
             });

             app.UseRouting();

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

             app.UseCors(MyAllowSpecificOrigins);

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

17行代码添加CORS支持，此处只允许来自我的客户端的访问。

28行配置OpenApi文档生成逻辑。

68行生成OpenApi文档界面，使用c.RoutePrefix使得一打开网站就能看到文档界面，而不是打开404.

37行配置JWT参数，连接到keycloak服务的test realm。

4、修改侦听端口

为了方便配置回调接口，在lauchSettings.json中将侦听地址改为http://localhost:5000

5、dotnet run启动

使用浏览器打开http://localhost:5000，看到如下文档界面。

ionic配置keycloak支持

使用keyclock-angular快速添加对于keyclock的支持，https://github.com/mauriciovigolo/keycloak-angular。

npm i --save keycloak-angular

npm i --save keycloak-js@version

这里的version我设置的是9.0.3，最新的是10，但是keyclock-angular安装时明确指定要求版本小于10，不知道是不是一个bug。

安装完毕后，修改app.module.ts,

 import { BASE_PATH } from './../../services/variables';
 import { NgModule, APP_INITIALIZER} from '@angular/core';
 import { BrowserModule } from '@angular/platform-browser';
 import { RouteReuseStrategy } from '@angular/router';

 import { IonicModule, IonicRouteStrategy } from '@ionic/angular';
 import { SplashScreen } from '@ionic-native/splash-screen/ngx';
 import { StatusBar } from '@ionic-native/status-bar/ngx';

 import { AppRoutingModule } from './app-routing.module';
 import { AppComponent } from './app.component';
 import { KeycloakAngularModule, KeycloakService } from 'keycloak-angular';
 import { HttpClientModule }  from '@angular/common/http';

 @NgModule({
   declarations: [AppComponent],
   entryComponents: [],
   imports: [BrowserModule, IonicModule.forRoot(), AppRoutingModule, KeycloakAngularModule, HttpClientModule],
   providers: [
     StatusBar,
     SplashScreen,
     { provide: RouteReuseStrategy, useClass: IonicRouteStrategy },
     {
       provide: APP_INITIALIZER,
       useFactory: initializer,
       multi: true,
       deps: [KeycloakService]
     },
     {
       provide: BASE_PATH, useValue: 'http://localhost:5000'
     }
   ],
   bootstrap: [AppComponent]
 })

 export class AppModule {}

 function initializer(keycloak: KeycloakService): () => Promise<any> {
   return (): Promise<any> => {
     return new Promise(async (resolve, reject) => {
       try {
         await keycloak.init({
           config: {
             url: 'http://localhost:8180/auth',
             realm: 'test',
             clientId: 'my-client'
           },
           initOptions: {
             onLoad: 'login-required',
             checkLoginIframe: false
           },
           bearerExcludedUrls: []
         });
         resolve();
       } catch (error) {
         reject(error);
       }
     });
   };
 }

首先，第2行增加引入APP_INITIALIZER;

然后，12行引入keyclock相关组件；

然后，23行增加provider，其实就是指定程序启动时执行的脚本为initializer；

最后，38行编写initializer方法，配置keyclock启动参数，并且配置了应用启动时直接调用登录（可选）

接下来，实现如下的CanAuthenticationGuard，用来控制路由。

import { Injectable } from '@angular/core';
import { CanActivate, ActivatedRouteSnapshot, RouterStateSnapshot, Router } from '@angular/router';
import { KeycloakAuthGuard, KeycloakService } from 'keycloak-angular';

@Injectable({
  providedIn: 'root'
})
export class CanAuthenticationGuard extends KeycloakAuthGuard implements CanActivate {
  constructor(protected router: Router, protected keycloakAngular: KeycloakService) {
    super(router, keycloakAngular);
  }

  isAccessAllowed(route: ActivatedRouteSnapshot, state: RouterStateSnapshot): Promise<boolean> {
    return new Promise((resolve, reject) => {
      if (!this.authenticated) {
        this.keycloakAngular.login()
          .catch(e => console.error(e));
        return reject(false);
      }

      const requiredRoles: string[] = route.data.roles;
      if (!requiredRoles || requiredRoles.length === 0) {
        return resolve(true);
      } else {
        if (!this.roles || this.roles.length === 0) {
          resolve(false);
        }
        resolve(requiredRoles.every(role => this.roles.indexOf(role) > -1));
      }
    });
  }
}

在app-routing.module.ts中引用该guard，并且在需要控制的路由如下处理

const routes: Routes = [
  {
    path: '',
    loadChildren: () => import('./tabs/tabs.module').then(m => m.TabsPageModule)
  },
  {
    path: 'hero/list',
    canActivate: [CanAuthenticationGuard],
    loadChildren: () => import('./hero/list/list.module').then( m => m.ListPageModule)
  },

主要是canActive一行。

配置keyclock

略去如何安装以及运行keyclock的详细说明，我是通过docker安装运行的。

首先，新建realm = test

然后，新建client = my-client，url = http://localhost:8100，也就是ionic app调试运行的地址

然后，建立一个用户并配置密码。

浏览器打开http://localhost:8100，如果配置正确，会看到请求被重定向到keycloak的登陆界面，输入用户名密码后跳转回ionic app。

至此，inoic集成keycloak的工作基本完成。

特别要说明的，集成keycloak之后，不仅能控制路由的访问，而且所有的http请求都会自动加上登陆时获取的token，方便了webapi的调用。你可以在app.module.ts的52行，添加例外。

调用WebApi

如果不使用OpenApi代码自动生成，调用WebApi的套路无非是编写interface，然后编写service，使用http调用webapi，有许多重复的代码和机械步骤。

OpenApi代码生成器解决了这一问题，可以替代我们生成这些代码，很方便。

首先，安装全局工具 https://github.com/OpenAPITools/openapi-generator

该工具提供了npm包，但只是一个封装，还是需要系统有java环境的。

npm install @openapitools/openapi-generator-cli -g

使用如下命令生成代码：

openapi-generator -i {swagger文件url} -g typescript-angular -o {代码存放目录}

运行完毕后，看到代码目录下生成了一堆文件，暂时不必理会这些文件，也不要修改这些文件。

找到任意一个page的ts文件，添加代码，使用生成的客户端：

import { WeatherForecast } from './../../../../services/model/weatherForecast';
import { WeatherForecastService } from './../../../../services/api/weatherForecast.service';
import { Component, OnInit } from '@angular/core';

@Component({
  selector: 'app-list',
  templateUrl: './list.page.html',
  styleUrls: ['./list.page.scss'],
})
export class ListPage implements OnInit {
  weathers: WeatherForecast[];

  constructor(private weatherforcastService: WeatherForecastService) { }

  ngOnInit() {
    this.weatherforcastService.weatherForecastGet()
      .subscribe(data => this.weathers = data);
  }

}

代码相当简单，WeatherForcast和WeatherForecastService已经帮我们自动生成了，直接使用就可以，是不是很cool呢？！

接下来，你可能有疑问了，光看到service，也不能修改生成的源码，那么去哪儿修改service的地址呢？很简单，翻看前面的app.module.ts，第1行引入BASE_PATH，然后在provider中替换它的内容即可。

总结

至此，我们实现了在angular/ionic中使用keycloak进行oauth认证并且访问webapi资源，还实现了使用openapi代码生成器自动生成客户端代码。