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(1, 5).Select(index => new WeatherForecast
            {
                Date = DateTime.Now.AddDays(index),
                TemperatureC = rng.Next(-20, 55),
                Summary = Summaries[rng.Next(Summaries.Length)]
            })
            .ToArray();
        }
    }
}

2、修改项目文件

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

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

  <PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);1591</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代码生成器自动生成客户端代码。