本文將引導(dǎo)你運(yùn)行Util權(quán)限管理模塊,并對(duì)UI按鈕和API操作進(jìn)行訪問控制.

Util平臺(tái)介紹

Util應(yīng)用框架是一組類庫(kù),它們提供了有用的功能.

雖然Util配套代碼生成器能夠幫助你創(chuàng)建項(xiàng)目基架,但直接使用它們的成本依然高昂.

第一個(gè)擋在前面的障礙是權(quán)限功能,它是任何業(yè)務(wù)項(xiàng)目的基石.

為了減輕使用Util應(yīng)用框架的負(fù)擔(dān),我們創(chuàng)建了該項(xiàng)目, 名為 Util Platform, 即 Util平臺(tái).

Util平臺(tái)處于起步階段,目前提供了基于資源和角色的權(quán)限模塊,可以控制前端菜單和按鈕,并能同時(shí)控制API的訪問.

后續(xù)將持續(xù)更新,添加更多基礎(chǔ)功能.

開源協(xié)議: MIT

可以在商業(yè)項(xiàng)目隨意使用.

歡迎參與貢獻(xiàn)

你如果感興趣,可以參與該項(xiàng)目的開發(fā), 共同創(chuàng)建基礎(chǔ)業(yè)務(wù)功能,為 .NET 生態(tài)添磚加瓦.

• Util應(yīng)用框架交流QQ群(24791014)

Util平臺(tái)項(xiàng)目介紹

為了滿足單體架構(gòu)和微服務(wù)架構(gòu)的需求, Util平臺(tái)分為三套項(xiàng)目.

• Util.Platform.Single

  Util.Platform.Single 是Util平臺(tái)單體架構(gòu)版本.

• Util.Platform.Dapr

  Util.Platform.Dapr 是Util平臺(tái)微服務(wù)架構(gòu)版本.

• Util.Platform.Share

  Util.Platform.Share 是Util平臺(tái)的共享庫(kù),抽取單體架構(gòu)版本和微服務(wù)架構(gòu)版本的共享代碼,并發(fā)布到Nuget供兩個(gè)版本使用.

Util平臺(tái)功能列表

• 系統(tǒng)功能

  • 登錄
  • 退出登錄

• 權(quán)限管理模塊

  • 應(yīng)用程序管理
  • 聲明管理
  • 資源管理
    • 模塊資源管理
    • 操作資源管理
    • 身份資源管理
    • Api資源管理
  • 用戶管理
  • 角色管理
    • 將用戶添加到角色
    • 從角色移除用戶
  • 權(quán)限管理
    • 授予角色操作權(quán)限
    • 拒絕角色操作權(quán)限
    • 授予角色API權(quán)限
    • 拒絕角色API權(quán)限

準(zhǔn)備

拉取 Util.Platform.Single 項(xiàng)目代碼.

git clone https://gitee.com/util-core/Util.Platform.Single.git

如果已拉取,請(qǐng)更新到最新代碼.

運(yùn)行項(xiàng)目

打開 Util.Platform.Single.sln 解決方案.

數(shù)據(jù)遷移

設(shè)置 Util.Platform.Api 為啟動(dòng)項(xiàng)目.

打開 appsettings.Development.json 開發(fā)配置文件.

DatabaseType 配置項(xiàng)用于指定當(dāng)前使用的數(shù)據(jù)庫(kù)類型,可選值為:

• SqlServer
• PgSql
• MySql

Util.Platform.Single 目前支持以上三種數(shù)據(jù)庫(kù),如果需要支持其它數(shù)據(jù)庫(kù),請(qǐng)告知.

檢查你使用的數(shù)據(jù)庫(kù)連接字符串是否正確.

按 F5 鍵,啟動(dòng) Util.Platform.Api 項(xiàng)目.

啟動(dòng)時(shí),會(huì)自動(dòng)運(yùn)行 EntityFrameworkCore 遷移命令,創(chuàng)建遷移文件目錄.

會(huì)同時(shí)創(chuàng)建三種數(shù)據(jù)庫(kù)項(xiàng)目遷移文件目錄.

如果沒有配置MySql連接字符串,或 MySql 連接失敗, 則無法創(chuàng)建MySql遷移文件目錄,并會(huì)產(chǎn)生一個(gè)異常,不用理會(huì)它.

查看數(shù)據(jù)庫(kù),可以看到數(shù)據(jù)庫(kù)已創(chuàng)建.

使用 Swagger 測(cè)試 Web Api 訪問控制

啟動(dòng)完成, 彈出 Swagger 頁面.

下面選擇一個(gè)最簡(jiǎn)單的操作進(jìn)行測(cè)試,執(zhí)行 Application 的 /api/Application/enabled 操作.

返回消息 code 為 2.

Code 是 Util 應(yīng)用框架約定的返回結(jié)果代碼, 2 代表未授權(quán) .

Util.Platform.Api 項(xiàng)目默認(rèn)開啟了API訪問控制,需要先進(jìn)行登錄認(rèn)證.

Util.Platform.Api 項(xiàng)目的 Swagger 已經(jīng)配置好 OAuth 認(rèn)證.

點(diǎn)擊 Swagger Authorize 按鈕.

彈出 Available authorizations 對(duì)話框,點(diǎn)擊 Authorize 按鈕.

進(jìn)入登錄頁面,如下所示.

數(shù)據(jù)遷移默認(rèn)創(chuàng)建兩個(gè)用戶: admin 和 test .

admin用戶是管理員,test是普通用戶.

輸入用戶 test , 密碼 test ,使用普通用戶登錄.

登錄成功,跳回 Swagger 頁面,點(diǎn)擊 Close 按鈕關(guān)閉對(duì)話框.

重新執(zhí)行 Application 的 /api/Application/enabled 操作.

可以看到,成功返回?cái)?shù)據(jù),說明已經(jīng)授權(quán)成功.

那么是不是只要登錄,就能操作所有API接口?

下面執(zhí)行 Application 的 POST /api/Application 操作,它表示創(chuàng)建應(yīng)用程序.

返回結(jié)果代碼為 2,表明未授權(quán),無法訪問 API,因?yàn)闆]有給 test 用戶設(shè)置創(chuàng)建應(yīng)用程序的權(quán)限.

運(yùn)行管理后臺(tái)UI

進(jìn)入 Util.Platform.Single\src\Util.Platform.Ui.Identity\ClientApp 目錄.

執(zhí)行命令,還原 npm 并啟動(dòng) Angular 開發(fā)服務(wù)器.

.\start.ps1

設(shè)置 Util.Platform.Ui.Identity 和 Util.Platform.Api 為啟動(dòng)項(xiàng)目.

按 F5 鍵啟動(dòng)項(xiàng)目.

彈出 Api Swagger 和 Angular UI 頁面.

Angular UI 已經(jīng)開啟了授權(quán)路由守衛(wèi),未授權(quán)則跳轉(zhuǎn)到登錄頁面.

使用 admin 用戶名登錄,密碼 admin.

登錄成功,進(jìn)入管理后臺(tái)UI,如下所示.

查看權(quán)限管理模塊

查看應(yīng)用程序

應(yīng)用程序用于支持多個(gè)業(yè)務(wù)子系統(tǒng)的訪問控制.

點(diǎn)擊左側(cè) 應(yīng)用程序 菜單項(xiàng),如下所示.

數(shù)據(jù)遷移默認(rèn)創(chuàng)建的應(yīng)用程序,名為 管理系統(tǒng).

你可以添加新的應(yīng)用程序,點(diǎn)擊 創(chuàng)建 按鈕,打開 創(chuàng)建應(yīng)用程序 對(duì)話框.

應(yīng)用程序還用于管理 Identity Server 身份服務(wù)器客戶端信息.

查看聲明

聲明是登錄認(rèn)證后可以在用戶會(huì)話中訪問的信息項(xiàng).

聲明非常簡(jiǎn)單,使用表格列表進(jìn)行編輯.

查看資源

資源是任何需要訪問控制的東西.

它是權(quán)限管理模塊的核心.

點(diǎn)擊左側(cè) 資源 菜單項(xiàng),如下所示.

查看模塊資源

模塊資源 用于按功能模塊進(jìn)行分層設(shè)置, 同時(shí)也顯示為前端的 菜單.

UI 左側(cè)菜單即是由模塊資源配置的.

并不是所有的模塊資源都會(huì)在菜單上顯示,比如資源菜單下的內(nèi)部導(dǎo)航菜單,也可以在模塊資源中配置,但不會(huì)在菜單上顯示.

點(diǎn)擊 創(chuàng)建 按鈕,彈出 創(chuàng)建模塊 對(duì)話框.

父模塊是一個(gè)下拉樹組件,如下所示.

我們順便看看 Util UI對(duì)下拉樹綁定這類常見需求提供的支持.

首先查看 html 代碼.

打開 Util.Platform.Ui.Identity/Pages/Routes/Identity/Module/Edit.cshtml 文件,如下所示.

Razor TagHelper 標(biāo)簽設(shè)置url直接發(fā)起web api請(qǐng)求.

這并非 Angular 推薦用法, 而是從之前 EasyUI 保留下來的經(jīng)驗(yàn),對(duì)于常規(guī)項(xiàng)目,這樣能大幅提升開發(fā)效率.

對(duì)于更復(fù)雜的場(chǎng)景,你可以使用 Angular 標(biāo)準(zhǔn)玩法,創(chuàng)建獨(dú)立的服務(wù),使用服務(wù)加載數(shù)據(jù),并綁定到組件上.

<util-tree-select for="ParentId" query-param="queryParam" load-mode="Sync" url="module/tree" default-expand-all="true"
    sort="SortId" label-text="identity.module.parentId" control-span="8">
</util-tree-select>

下面來查看 Angular 組件 typescript 腳本代碼.

打開 Util.Platform.Ui.Identity/ClientApp/src/app/routes/identity/module/module-edit.component.ts 文件,如下所示.

可以看到,代碼非常簡(jiǎn)單,沒有加載父模塊下拉樹組件的代碼.

/**
 * 模塊編輯頁
 */
@Component({
    selector: 'module-edit',
    templateUrl: environment.production ? './html/edit.component.html' : '/view/routes/identity/module/edit'
})
export class ModuleEditComponent extends TreeEditComponentBase<ModuleViewModel> {
    /**
     * 查詢參數(shù)
     */
    queryParam: ResourceQuery;
    /**
     * 應(yīng)用程序標(biāo)識(shí)
     */
    @Input() applicationId;
    /**
     * 應(yīng)用程序名稱
     */
    @Input() applicationName;

    /**
     * 初始化模塊編輯頁
     * @param injector 注入器
     */
    constructor(injector: Injector) {
        super(injector);
        let param = this.util.dialog.getData<any>();
        if (param) {
            this.applicationId = param.applicationId;
            this.applicationName = param.applicationName;
        }
    }

    /**
     * 初始化
     */
    ngOnInit() {
        super.ngOnInit();
        this.model.applicationId = this.applicationId;
        this.queryParam = this.createQuery();
    }

    /**
     * 創(chuàng)建模型
     */
    createModel() {
        let result = new ModuleViewModel();
        result.enabled = true;
        return result;
    }

    /**
     * 創(chuàng)建查詢參數(shù)
     */
    protected createQuery() {
        let result = new ResourceQuery();
        result.applicationId = this.applicationId;
        return result;
    }

    /**
     * 獲取基地址
     */
    protected getBaseUrl() {
        return "module";
    }

    /**
     * 選擇圖標(biāo)
     */
    selectIcon(icon) {
        this.model.icon = icon;
    }
}

最后,查看 Web Api 控制器的代碼.

打開 Util.Platform.Api/Controllers/Identity/ModuleController.cs 文件,如下所示.

模塊控制器從 NgZorroTreeControllerBase 基類繼承,已經(jīng)封裝將樹形數(shù)據(jù)轉(zhuǎn)換成 Ng Zorro 樹形組件需要的數(shù)據(jù)格式.

NgZorroTreeControllerBase 基類提供的 QueryAsync 方法用于為樹形表格提供數(shù)據(jù),TreeQueryAsync 方法為樹形或下拉樹形提供數(shù)據(jù).

查看操作資源

點(diǎn)擊 模塊資源 列表 資源設(shè)置 按鈕,打開 操作資源 列表, 如下所示.

操作資源 列表是一個(gè)內(nèi)嵌表格,為模塊資源提供細(xì)粒度訪問控制,比如控制頁面上的按鈕.

資源還有兩種常見類型, 列 資源和 行集 資源.

列 資源用來控制顯示的字段.

行集 資源用來控制不同角色顯示不同的內(nèi)容,俗稱數(shù)據(jù)權(quán)限.

行集資源需要使用規(guī)約對(duì)象封裝查詢條件,并接入 Util 授權(quán)體系.

這兩種資源尚未實(shí)現(xiàn),待基礎(chǔ)功能完善以后提供,如果你的項(xiàng)目對(duì)數(shù)據(jù)權(quán)限控制有需求,可以告知,我們將提前實(shí)現(xiàn)它.

點(diǎn)擊 操作資源 創(chuàng)建 按鈕,打開 創(chuàng)建操作權(quán)限 對(duì)話框.

操作名稱輸入框提示常用操作,可以從中選擇,或手工輸入.

資源最重要的屬性是標(biāo)識(shí).

對(duì)于UI按鈕的控制,可以使用有意義的標(biāo)識(shí), 比如 application.create, 表示創(chuàng)建應(yīng)用程序.

資源的定義由開發(fā)人員根據(jù)控制粒度決定,除了在管理系統(tǒng)添加資源數(shù)據(jù),還需要修改相應(yīng)代碼.

設(shè)置操作權(quán)限

下面以 創(chuàng)建應(yīng)用程序 操作為例,介紹控制 UI 按鈕和 API 需要的步驟.

• 添加 創(chuàng)建應(yīng)用程序 操作資源.

  數(shù)據(jù)遷移已經(jīng)創(chuàng)建了該資源,標(biāo)識(shí)為 application.create.

• UI 按鈕訪問控制

  打開 Util.Platform.Ui.Identity/Pages/Routes/Identity/Application/Index.cshtml 文件,如下所示.

只需要把 application.create 操作資源標(biāo)識(shí)設(shè)置到 acl 屬性即可.

acl 屬性是 Ng Alain 提供的訪問控制指令 *aclIf, 已經(jīng)將 acl 屬性全局添加到 Util UI所有 TagHelper 標(biāo)簽.

• Api 訪問控制

  打開 Util.Platform.Api/Controllers/Identity/ApplicationController.cs 文件,代碼簡(jiǎn)化如下.

  /// <summary>
  /// 應(yīng)用程序控制器
  /// </summary>
  [Acl( "application.view" )]
  public class ApplicationController : CrudControllerBase<ApplicationDto, ApplicationQuery> {
    /// <summary>
    /// 初始化應(yīng)用程序控制器
    /// </summary>
    /// <param name="service">應(yīng)用程序服務(wù)</param>
    public ApplicationController( IApplicationService service ) : base( service ) {
        ApplicationService = service;
    }
  
    /// <summary>
    /// 應(yīng)用程序服務(wù)
    /// </summary>
    protected IApplicationService ApplicationService { get; }
  
    /// <summary>
    /// 創(chuàng)建
    /// </summary>
    /// <param name="request">創(chuàng)建參數(shù)</param>
    [HttpPost]
    [Acl( "application.create" )]
    public new async Task<IActionResult> CreateAsync( ApplicationDto request ) {
        return await base.CreateAsync( request );
    }
  }
  

  注意 ApplicationController 控制器上面的 [Acl( "application.view" )] 特性.

  Asp.Net Core 自帶了一個(gè)授權(quán)特性 [Authorize] ,它默認(rèn)的行為是只要登錄認(rèn)證成功,就能進(jìn)行任何操作.

  Authorize 特性可以設(shè)置 Roles 屬性, 設(shè)置硬編碼的角色列表,這不太靈活.

  Authorize 特性還能設(shè)置 Policy 自定義授權(quán)策略, 這是一種靈活的授權(quán)方式,但每個(gè)需要授權(quán)的API都要設(shè)置 Policy 很費(fèi)力.

  Util Acl 特性從 Authorize 繼承,并封裝了特定的授權(quán)策略.

  與 Authorize 的 Roles 不同的是, Acl 并不設(shè)置角色,因?yàn)榻巧莿?dòng)態(tài)的,可能隨時(shí)增加減少,所以設(shè)置角色是一種不太靠譜的方法,只適合角色固定的項(xiàng)目.

  Acl 特性設(shè)置的是資源標(biāo)識(shí), 資源標(biāo)識(shí)是固定不變的,理解這一點(diǎn)是將權(quán)限從業(yè)務(wù)邏輯中剝離出來的關(guān)鍵.

  application.view 是查看應(yīng)用程序操作資源.

  任何功能頁面都需要查看權(quán)限,如果沒有細(xì)粒度控制需求,對(duì)整個(gè)頁面和API進(jìn)行控制即可.

  現(xiàn)在只要某個(gè)角色擁有 application.view 操作資源,他就能對(duì)控制器中所有方法進(jìn)行訪問.

  當(dāng)需要進(jìn)行更加細(xì)粒度的控制時(shí),只需要在某個(gè)控制器方法上添加 [Acl] 特性,并設(shè)置相應(yīng)的資源標(biāo)識(shí)即可.

  CreateAsync 方法添加了 [Acl( "application.create" )] 特性,這說明只有擁有 application.create 資源的角色才能進(jìn)行創(chuàng)建操作.

  統(tǒng)一 UI 按鈕與 API 操作的資源標(biāo)識(shí)是權(quán)限設(shè)置的最佳實(shí)踐.

  另一種方法是UI按鈕與API操作使用不同的資源標(biāo)識(shí),再將API資源綁定到UI按鈕,這種方式更復(fù)雜且容易出錯(cuò).

  如果僅對(duì) Web Api 進(jìn)行訪問控制, 可以使用API資源, 資源標(biāo)識(shí)為 Api 地址,不需要在每個(gè)控制器打上 [Acl] 特性,Util 還提供了Acl過濾器,可以全局啟用訪問控制.

  擁有細(xì)粒度操作資源的角色必須擁有查看資源.

  對(duì)于本例,如果需要訪問 CreateAsync 操作,Asp.Net Core首先驗(yàn)證 application.view 資源是否能訪問,如果通過才會(huì)繼續(xù)驗(yàn)證 application.create 資源.

• 授予權(quán)限

  一旦創(chuàng)建操作資源,并在 UI 和 API 進(jìn)行了Acl設(shè)置,就可以為角色授權(quán).

  數(shù)據(jù)遷移默認(rèn)創(chuàng)建了兩個(gè)角色,admin 和 test,并已將用戶 test 關(guān)聯(lián)到 test 角色,以及將用戶 admin 關(guān)聯(lián)到 admin角色.

  點(diǎn)擊左側(cè) 角色 菜單,打開角色列表.

  角色列表中點(diǎn)擊 test 角色 權(quán)限設(shè)置 鏈接,如下所示.

  

  彈出 角色權(quán)限設(shè)置對(duì)話框,如下所示.

  

  默認(rèn) test 角色只能查看應(yīng)用程序.

驗(yàn)證操作權(quán)限

下面來驗(yàn)證權(quán)限控制是否生效.

驗(yàn)證 UI 按鈕權(quán)限

鼠標(biāo)移到右上方頭像,彈出菜單點(diǎn)擊 退出登錄 鏈接.

使用 test 用戶登錄,密碼 test .

可以看到,只有一個(gè)應(yīng)用程序菜單,并且操作按鈕也消失了.

為 test 角色授予創(chuàng)建權(quán)限

退出登錄,使用 admin 用戶登錄.

打開 test 角色 權(quán)限設(shè)置 窗口,勾選 授予 應(yīng)用程序 的 創(chuàng)建 復(fù)選框,點(diǎn)擊確定按鈕,如下所示.

還支持拒絕權(quán)限,如果用戶的某個(gè)角色擁有拒絕資源,則無法訪問該資源.

退出登錄,使用 test 用戶登錄.

打開應(yīng)用程序頁面,可以看到創(chuàng)建按鈕已經(jīng)顯示出來.

驗(yàn)證 Api 權(quán)限

打開 Swagger ,之前已經(jīng)測(cè)試過創(chuàng)建應(yīng)用程序 API 接口無法訪問,下面再來試試.

提交下面的數(shù)據(jù).

{
  "code": "test",
  "name": "test",
  "enabled": true
}

提交返回操作成功消息,說明權(quán)限設(shè)置生效.

全局關(guān)閉訪問控制

一旦 Web Api 控制器添加了 [Acl] 特性,權(quán)限就已經(jīng)啟用.

對(duì)于某些場(chǎng)景可能相當(dāng)麻煩,比如 Web Api 集成測(cè)試.

權(quán)限是由 Identity Server 提供的,你的集成測(cè)試需要從 Identity Server 獲取令牌,這造成了不必要的負(fù)擔(dān).

Util應(yīng)用框架支持全局關(guān)閉訪問控制,如下所示.

.AddAcl( t => t.AllowAnonymous = true )

AddAcl 配置 Util訪問控制相關(guān)的服務(wù)依賴,AllowAnonymous讓所有添加了 [Acl] 的方法跳過權(quán)限檢測(cè),無需登錄,無需授權(quán).