mirror of
https://github.com/halo-dev/docs.git
synced 2025-10-20 01:17:19 +00:00
refactor: update permission control docs for plugin (#443)
### What this PR does? 重构权限控制部分文档并调整相应结构 ```release-note None ```
This commit is contained in:
guqing
@@ -52,7 +52,7 @@ public interface ExtensionGetter {
|
||||
|
||||
通过使用 `ExtensionGetter`，开发者可以轻松地在插件中访问和管理各种扩展点，提升插件的功能和灵活性。
|
||||
|
||||
如果想了解 Halo 提供的扩展点请参考：[扩展点](./extension-points/index.md)。
|
||||
如果想了解 Halo 提供的扩展点请参考：[扩展点](../../extension-points/server/index.md)。
|
||||
:::
|
||||
|
||||
### 示例
|
||||
|
||||
@@ -123,4 +123,4 @@ export interface PluginModule {
|
||||
- `components`：组件列表，key 为组件名称，value 为组件对象，在此定义之后，加载插件时会自动注册到 Vue App 全局。
|
||||
- `routes`：Console 控制台路由定义，详细文档可参考 [路由定义](../../api-reference/ui/route.md)
|
||||
- `ucRoutes`：UC 个人中心路由定义，详细文档可参考 [路由定义](../../api-reference/ui/route.md)
|
||||
- `extensionPoints`：扩展点定义，详细文档可参考 [扩展点](../../api-reference/ui/extension-points/index.md)
|
||||
- `extensionPoints`：扩展点定义，详细文档可参考 [扩展点](../../extension-points/ui/index.md)
|
||||
|
||||
@@ -26,7 +26,7 @@ public interface CommentSubject<T extends Extension> extends ExtensionPoint {
|
||||
- `getSubjectDisplay` 方法用于获取评论主体的展示信息，返回值为 `Mono<SubjectDisplay>`，其中 `SubjectDisplay` 为评论主体的展示信息，包含标题、链接和类型名称，用于在主题端展示评论主体的信息。
|
||||
- `supports` 方法用于判断是否支持该评论主体，返回值为 `boolean`，如果支持则返回 `true`，否则返回 `false`。
|
||||
|
||||
实现该扩展点后，评论列表会通过 `get` 方法将主体的自定义模型对象带到评论列表中，可以配置前端的扩展点来决定如何展示评论主体的信息，参考：[UI 评论来源显示](../../ui/extension-points//comment-subject-ref-create.md)
|
||||
实现该扩展点后，评论列表会通过 `get` 方法将主体的自定义模型对象带到评论列表中，可以配置前端的扩展点来决定如何展示评论主体的信息，参考：[UI 评论来源显示](../ui/comment-subject-ref-create.md)
|
||||
|
||||
例如对于文章是支持评论的，所以文章的评论主体扩展点实现如下：
|
||||
|
||||
@@ -54,7 +54,7 @@ spec:
|
||||
单实例或多实例扩展点的实现也必须声明一个对应的 `ExtensionDefinition` 自定义模型对象被称之为扩展定义，用于描述该扩展的信息，例如：扩展的名称、描述、对应扩展点的对象名称等。
|
||||
:::
|
||||
|
||||
关于如何在插件中声明自定义模型对象请参考：[自定义模型](../../server/extension.md#declare-extension-object)
|
||||
关于如何在插件中声明自定义模型对象请参考：[自定义模型](../../api-reference/server/extension.md#declare-extension-object)
|
||||
|
||||
以下是目前已支持的扩展点列表：
|
||||
|
||||
@@ -34,7 +34,7 @@ spec:
|
||||
```
|
||||
|
||||
- `notifierExtName` 为通知器扩展的自定义模型对象名称
|
||||
- `senderSettingRef` 用于声明通知器的发送者配置，例如：邮件通知器的发送者配置为：SMTP 服务器地址、端口、用户名、密码等，如果没有可以不配置，参考：[表单定义](../../../../form-schema.md)
|
||||
- `senderSettingRef` 用于声明通知器的发送者配置，例如：邮件通知器的发送者配置为：SMTP 服务器地址、端口、用户名、密码等，如果没有可以不配置，参考：[表单定义](../../../form-schema.md)
|
||||
- `name` 为发送者配置的名称，它是一个 `Setting` 自定义模型对象的名称。
|
||||
- `group` 用于引用到一个具体的配置 Schema 组，它是一个 `Setting` 自定义模型对象中描述的 `formSchema` 的 `group`，由于 `Setting` 可以声明多个配置分组但通知器的发送者配置只能有在一个组，因此需要指定一个组。
|
||||
- `receiverSettingRef` 用于声明通知器的接收者配置，例如：邮件通知器的接收者配置为：接收者邮箱地址，如果没有可以不配置，`name` 和 `group` 配置同 `senderSettingRef`。
|
||||
@@ -5,7 +5,7 @@ description: 扩展附件数据列表操作菜单 - attachment:list-item:operati
|
||||
|
||||
此扩展点用于扩展附件数据列表的操作菜单项。
|
||||
|
||||
|
||||
|
||||
|
||||
## 定义方式
|
||||
|
||||
@@ -5,7 +5,7 @@ description: 扩展附件选择组件的选项卡 - attachment:selector:create
|
||||
|
||||
此扩展点用于扩展附件选择组件的选项卡，目前 Halo 仅包含内置的附件库，你可以通过此扩展点添加自定义的选项卡。
|
||||
|
||||
|
||||
|
||||
|
||||
## 定义方式
|
||||
|
||||
@@ -5,7 +5,7 @@ description: 扩展备份数据列表操作菜单 - backup:list-item:operation:c
|
||||
|
||||
此扩展点用于扩展备份数据列表的操作菜单项。
|
||||
|
||||
|
||||
|
||||
|
||||
## 定义方式
|
||||
|
||||
@@ -5,7 +5,7 @@ description: 扩展备份页面选项卡 - backup:tabs:create
|
||||
|
||||
此扩展点可以针对备份页面扩展更多关于 UI 的功能，比如定时备份设置、备份到第三方云存储等。
|
||||
|
||||
|
||||
|
||||
|
||||
## 定义方式
|
||||
|
||||
@@ -5,7 +5,7 @@ description: 扩展评论数据列表操作菜单 - comment:list-item:operation:
|
||||
|
||||
此扩展点用于扩展评论数据列表的操作菜单项。
|
||||
|
||||
|
||||
|
||||
|
||||
## 定义方式
|
||||
|
||||
@@ -6,10 +6,10 @@ description: 扩展评论来源显示 - comment:subject-ref:create
|
||||
Console 的评论管理列表的评论来源默认仅支持显示来自文章和页面的评论，如果其他插件中的业务模块也使用了评论，那么就可以通过该拓展点来扩展评论来源的显示。
|
||||
|
||||
:::info 提示
|
||||
此扩展点需要后端配合使用，请参考 [评论主体展示](../../server/extension-points/comment-subject.md)。
|
||||
此扩展点需要后端配合使用，请参考 [评论主体展示](../server/comment-subject.md)。
|
||||
:::
|
||||
|
||||
|
||||
|
||||
|
||||
## 定义方式
|
||||
|
||||
@@ -58,7 +58,7 @@ export interface ExtensionOptions {
|
||||
|
||||
编辑器顶部功能区域内容的扩展，通常用于增加用户常用操作，例如文本加粗、变更颜色等。
|
||||
|
||||
|
||||
|
||||
|
||||
在 [https://github.com/halo-sigs/richtext-editor/pull/16](https://github.com/halo-sigs/richtext-editor/pull/16) 中，我们实现了对顶部工具栏的扩展，如果需要添加额外的功能，只需要在具体的 Tiptap Extension 中的 `addOptions` 中定义 `getToolbarItems` 函数即可，如：
|
||||
|
||||
@@ -128,7 +128,7 @@ addOptions() {
|
||||
|
||||
编辑器工具箱区域的扩展，可用于增加编辑器附属操作，例如插入表格，插入第三方组件等功能。
|
||||
|
||||
|
||||
|
||||
|
||||
在 [https://github.com/halo-sigs/richtext-editor/pull/27](https://github.com/halo-sigs/richtext-editor/pull/27) 中，我们实现了对编辑器工具箱区域的扩展，如果需要添加额外的功能，只需要在具体的 Tiptap Extension 中的 `addOptions` 中定义 `getToolboxItems` 函数即可，如：
|
||||
|
||||
@@ -199,7 +199,7 @@ addOptions() {
|
||||
|
||||
Slash Command （斜杠命令）的扩展，可用于在当前行快捷执行功能操作，例如转换当前行为标题、在当前行添加代码块等功能。
|
||||
|
||||
|
||||
|
||||
|
||||
在 [https://github.com/halo-sigs/richtext-editor/pull/16](https://github.com/halo-sigs/richtext-editor/pull/16) 中，我们实现了对 Slash Command 指令的扩展，如果需要添加额外的功能，只需要在具体的 Tiptap Extension 中的 `addOptions` 中定义 `getCommandMenuItems` 函数即可，如：
|
||||
|
||||
@@ -261,7 +261,7 @@ addOptions() {
|
||||
|
||||
编辑器悬浮菜单的扩展。可用于支持目标元素组件的功能扩展及操作简化。例如 `Table` 扩展中的添加下一列、添加上一列等操作。
|
||||
|
||||
|
||||
|
||||
|
||||
在 [https://github.com/halo-sigs/richtext-editor/pull/38](https://github.com/halo-sigs/richtext-editor/pull/38) 中，我们重构了对编辑器悬浮区域的扩展，如果需要对某个块进行支持，只需要在具体的 Tiptap Extension 中的 `addOptions` 中定义 `getBubbleMenu` 函数即可，如：
|
||||
|
||||
@@ -371,7 +371,7 @@ addOptions() {
|
||||
|
||||
拖拽功能的扩展，可用于支持当前块元素的拖拽功能。
|
||||
|
||||
|
||||
|
||||
|
||||
在 [https://github.com/halo-sigs/richtext-editor/pull/48](https://github.com/halo-sigs/richtext-editor/pull/48) 中，我们实现了对所有元素的拖拽功能，如果需要让当前扩展支持拖拽，只需要在具体的 Tiptap Extension 中的 `addOptions` 中定义 `getDraggable` 函数，并让其返回 true 即可。如：
|
||||
|
||||
@@ -5,7 +5,7 @@ description: 通过实现扩展点为文章提供新的编辑器 - editor:create
|
||||
|
||||
此扩展点可以为文章提供新的独立编辑器。
|
||||
|
||||
|
||||
|
||||
|
||||
## 定义方式
|
||||
|
||||
@@ -5,7 +5,7 @@ description: 扩展插件安装界面选项卡 - plugin:installation:tabs:create
|
||||
|
||||
目前 Halo 原生支持本地上传和远程下载的方式安装插件，此扩展点用于扩展插件安装界面的选项卡，以支持更多的安装方式。
|
||||
|
||||
|
||||
|
||||
|
||||
## 定义方式
|
||||
|
||||
@@ -5,7 +5,7 @@ description: 扩展插件数据列表显示字段 - plugin:list-item:field:creat
|
||||
|
||||
此扩展点用于扩展插件数据列表的显示字段。
|
||||
|
||||
|
||||
|
||||
|
||||
## 定义方式
|
||||
|
||||
@@ -5,7 +5,7 @@ description: 扩展插件数据列表操作菜单 - plugin:list-item:operation:c
|
||||
|
||||
此扩展点用于扩展插件数据列表的操作菜单项。
|
||||
|
||||
|
||||
|
||||
|
||||
## 定义方式
|
||||
|
||||
@@ -5,7 +5,7 @@ description: 扩展当前插件的详情选项卡 - plugin:self:tabs:create
|
||||
|
||||
此扩展点用于在 Console 的插件详情页面中添加自定义选项卡，可以用于自定义插件的配置页面。
|
||||
|
||||
|
||||
|
||||
|
||||
## 定义方式
|
||||
|
||||
@@ -5,7 +5,7 @@ description: 扩展文章数据列表显示字段 - plugin:list-item:field:creat
|
||||
|
||||
此扩展点用于扩展文章数据列表的显示字段。
|
||||
|
||||
|
||||
|
||||
|
||||
## 定义方式
|
||||
|
||||
@@ -5,7 +5,7 @@ description: 扩展文章数据列表操作菜单 - post:list-item:operation:cre
|
||||
|
||||
此扩展点用于扩展文章数据列表的操作菜单项。
|
||||
|
||||
|
||||
|
||||
|
||||
## 定义方式
|
||||
|
||||
@@ -5,7 +5,7 @@ description: 扩展回复数据列表操作菜单 - reply:list-item:operation:cr
|
||||
|
||||
此扩展点用于扩展回复数据列表的操作菜单项。
|
||||
|
||||
|
||||
|
||||
|
||||
## 定义方式
|
||||
|
||||
@@ -5,7 +5,7 @@ description: 扩展主题数据列表操作菜单 - theme:list-item:operation:cr
|
||||
|
||||
此扩展点用于扩展主题数据列表的操作菜单项。
|
||||
|
||||
|
||||
|
||||
|
||||
## 定义方式
|
||||
|
||||
@@ -5,7 +5,7 @@ description: 扩展主题管理界面选项卡 - theme:list:tabs:create
|
||||
|
||||
目前在 Halo 的主题管理中原生支持本地上传和远程下载的方式安装主题，此扩展点用于扩展主题管理界面的选项卡，以支持更多的安装方式。
|
||||
|
||||
|
||||
|
||||
|
||||
## 定义方式
|
||||
|
||||
@@ -5,7 +5,7 @@ description: 扩展个人中心的个人资料选项卡 - uc:user:profile:tabs:c
|
||||
|
||||
此扩展点用于扩展个人中心的个人资料选项卡。
|
||||
|
||||
|
||||
|
||||
|
||||
## 定义方式
|
||||
|
||||
@@ -5,7 +5,7 @@ description: 扩展用户详情选项卡 - user:detail:tabs:create
|
||||
|
||||
此扩展点用于扩展用户详情页面的选项卡。
|
||||
|
||||
|
||||
|
||||
|
||||
## 定义方式
|
||||
|
||||
@@ -7,7 +7,7 @@ description: 了解如何与我们的社区分享你的插件
|
||||
|
||||
## 创建 Release
|
||||
|
||||
当你完成了你的插件并进行充分测试后，就可以在 GitHub 上创建新的 Release，其中版本规范可以参考[版本控制](./introduction.md#版本控制)。
|
||||
当你完成了你的插件并进行充分测试后，就可以在 GitHub 上创建新的 Release，其中版本规范可以参考[版本控制](#版本控制)。
|
||||
|
||||
## 自动构建
|
||||
|
||||
|
||||
253
docs/developer-guide/plugin/security/rbac.md
Normal file
253
docs/developer-guide/plugin/security/rbac.md
Normal file
@@ -0,0 +1,253 @@
|
||||
---
|
||||
title: 基于角色的权限控制
|
||||
description: 了解 Halo 的基于角色的权限控制机制。
|
||||
---
|
||||
|
||||
基于角色的权限控制（Role-Based Access Control，RBAC）是一种广泛应用的访问控制机制，旨在通过定义用户的角色来简化和增强权限管理。
|
||||
在 Halo 中，RBAC 通过限制对系统资源的访问来确保系统的安全性和可管理性。
|
||||
|
||||
## RBAC 的基本概念
|
||||
|
||||
RBAC 通过三个核心概念来管理权限：
|
||||
|
||||
1. **角色（Role）** ：角色定义了一组操作权限，这些操作可以包括对某些资源的“读”、“写”或“执行”等权限。在 Halo 中，角色可以绑定到用户，从而赋予它们相应的权限，同时角色可以依赖于其他角色，从而实现权限的继承以简化权限管理。
|
||||
|
||||
2. **用户（User）** ：用户是实际使用 Halo 资源的实体。
|
||||
|
||||
3. **角色绑定（RoleBinding）** ：角色绑定是将用户与特定的角色关联起来。通过角色绑定，某个用户可以获得与角色相关的权限。
|
||||
|
||||
通过上述三者的结合，RBAC 可以灵活地控制用户对 Halo 资源的访问权限。
|
||||
|
||||
## 什么是基于角色的权限控制
|
||||
|
||||
RBAC 的核心思想是将权限分配给角色，而不是直接分配给用户。用户通过被分配一个或多个角色来获得相应的权限。每个角色都定义了可以执行的操作，如读取、写入、删除等操作。这种设计具有以下几个优点：
|
||||
|
||||
1. 简化权限管理：管理员可以通过管理少数角色来控制大量用户的权限，而不需要为每个用户单独配置权限。
|
||||
2. 权限最小化：用户只会被赋予完成工作所需的最低权限，减少了安全风险。
|
||||
3. 易于扩展：新增用户或变更权限只需要调整角色，无需修改大量的用户配置。
|
||||
|
||||
## Role 和 RoleBinding
|
||||
|
||||
在 Halo 中，Role 是通过自定义模型来定义的。一个典型的 Role 的 YAML 配置如下：
|
||||
|
||||
```yaml
|
||||
apiVersion: v1alpha1
|
||||
kind: Role
|
||||
metadata:
|
||||
name: example-role
|
||||
rules:
|
||||
- apiGroups: [""]
|
||||
resources: ["menus"]
|
||||
verbs: ["get", "list"]
|
||||
```
|
||||
|
||||
上面的例子定义了一个名为 example-role 的角色。该角色允许用户对菜单资源执行 get 和 list 操作。
|
||||
|
||||
- `apiGroups` 定义了资源所属的 API 组，`""` 表示核心 API 组。
|
||||
- `resources` 是指定角色可以操作的资源类型。
|
||||
- `verbs` 表示可以执行的操作，比如 get、create、delete 等。
|
||||
|
||||
## RoleBinding 与角色的关联
|
||||
|
||||
定义好角色后，我们需要通过 `RoleBinding` 将其与某个用户关联，`RoleBinding` 绑定了 `Role` 并指定了哪些用户可以获得该角色的权限。
|
||||
在 Halo 为用户分配角色也是通过 `RoleBinding` 来实现的。一个典型的 RoleBinding 的 YAML 配置如下：
|
||||
|
||||
```yaml
|
||||
apiVersion: v1alpha1
|
||||
kind: RoleBinding
|
||||
metadata:
|
||||
name: fake-user-binding
|
||||
subjects:
|
||||
# 绑定的用户，这是一个数组，可以绑定多个用户
|
||||
- kind: User
|
||||
name: fake-user
|
||||
apiGroup: ""
|
||||
roleRef:
|
||||
kind: Role
|
||||
name: example-role
|
||||
apiGroup: ""
|
||||
```
|
||||
|
||||
## 角色模板
|
||||
|
||||
虽然角色已经定义了一组操作权限，但是粒度太细的角色会导致权限管理复杂，如文章管理的角色可能需要包含了文章、分类、标签、用户等多个资源的操作权限才能提供完整的功能，而这些操作权限可能会被多个角色共享。
|
||||
为了简化权限管理，Halo 提供了角色模板的功能，角色模板是一组操作权限的集合，可以被多个角色共享。同时，角色模板也可以继承其他角色模板，从而实现权限的继承。
|
||||
|
||||
### 创建角色模板
|
||||
|
||||
角色模板是通过一个特殊的 label 来标识 Role 对象实现的，一个典型的角色模板的 YAML 配置如下：
|
||||
|
||||
```yaml
|
||||
apiVersion: v1alpha1
|
||||
kind: Role
|
||||
metadata:
|
||||
name: example-role
|
||||
labels:
|
||||
# 通过 halo.run/role-template: "true" 标识为角色模板
|
||||
halo.run/role-template: "true"
|
||||
rules:
|
||||
- apiGroups: [""]
|
||||
resources: ["menus"]
|
||||
verbs: ["get", "list"]
|
||||
```
|
||||
|
||||
Halo 在用户界面只会显示非模板角色，这样可以避免用户误操作角色模板，同时也可以简化用户对角色的管理。
|
||||
用户创建角色时通过选择`角色模板`来创建角色，角色模板在用户界面以`权限`的概念展示，比如`文章管理`、`用户管理`等。
|
||||
|
||||
## 继承角色/角色模板
|
||||
|
||||
可以在角色的 `annotations` 中添加 `rbac.authorization.halo.run/dependencies` 来声明角色间的依赖关系，例如菜单管理必须要依赖菜单查看，以避免分配了管理权限却没有查看权限的情况。
|
||||
当角色依赖于其他角色时，Halo 会自动将依赖的角色的权限合并到当前角色中以实现权限的继承。
|
||||
|
||||
```yaml
|
||||
apiVersion: v1alpha1
|
||||
kind: Role
|
||||
metadata:
|
||||
name: example-role
|
||||
labels:
|
||||
halo.run/role-template: "true"
|
||||
annotations:
|
||||
rbac.authorization.halo.run/dependencies: |
|
||||
[ "view-menu" ]
|
||||
rules:
|
||||
- apiGroups: [""]
|
||||
resources: ["menus"]
|
||||
verbs: [ "create", "update", "delete" ]
|
||||
---
|
||||
apiVersion: v1alpha1
|
||||
kind: Role
|
||||
metadata:
|
||||
name: view-menu
|
||||
labels:
|
||||
halo.run/role-template: "true"
|
||||
rules:
|
||||
- apiGroups: [""]
|
||||
resources: ["menus"]
|
||||
verbs: ["get", "list"]
|
||||
```
|
||||
|
||||
## 聚合角色
|
||||
|
||||
角色定义依赖关系适合于定义角色模板时复用 `rules` 或者用户创建角色时绑定其他角色，但是如果想要将一个角色的权限合并到另一个已有的角色中（如 Halo 提供的），这种情况下角色依赖关系就无法满足需求了。
|
||||
例如，当插件开发者想要将自己插件的角色权限合合并到 Halo 的角色中时，无法修改 Halo 的角色定义，这时可以通过聚合角色来实现。
|
||||
|
||||
聚合角色通过 `rbac.authorization.halo.run/aggregate-to-{role-name}` 的 `annotations` 来声明，其中的 `{role-name}` 占位符表示要聚合到的角色名。
|
||||
|
||||
例如插件开发者想要将插件的某些 API 资源公开给所有人访问即不需要授权，可以通过将角色聚合到 `anonymous` 角色来实现。
|
||||
|
||||
```yaml
|
||||
apiVersion: v1alpha1
|
||||
kind: Role
|
||||
metadata:
|
||||
name: template-moment-anonymous-resrouces
|
||||
labels:
|
||||
halo.run/role-template: "true"
|
||||
annotations:
|
||||
rbac.authorization.halo.run/aggregate-to-anonymous: "true"
|
||||
rules:
|
||||
- apiGroups: ["api.moment.halo.run"]
|
||||
resources: ["moments"]
|
||||
verbs: ["get", "list"]
|
||||
```
|
||||
|
||||
上述配置将 `template-moment-anonymous-resrouces` 角色聚合到 `anonymous` 角色中，用户无需登录即可访问 `api.moment.halo.run` 下的 `moments` 资源。
|
||||
|
||||
`rbac.authorization.halo.run/aggregate-to-editor` 表示将 `role-template-view-categories` 角色聚合到 `editor` 角色中，这样所有拥有 `editor` 角色的用户都会拥有 `role-template-view-categories` 角色的权限。
|
||||
|
||||
在 Halo 中，`anonymous` 角色是一个特殊的角色，表示未登录的匿名访客。
|
||||
|
||||
## 隐藏角色模板
|
||||
|
||||
Halo 提供了隐藏角色模板的功能，隐藏的角色模板不会在用户界面的权限列表中显示，对于聚合角色来说，隐藏角色模板是非常有用的，它可以避免用户在权限列表中看到不应该看到的角色模板。
|
||||
|
||||
隐藏角色模板通过 `halo.run/hidden: "true"` 的 `labels` 来标识，**它必须是一个角色模板**。
|
||||
|
||||
```yaml
|
||||
apiVersion: v1alpha1
|
||||
kind: Role
|
||||
metadata:
|
||||
name: template-moment-anonymous-resrouces
|
||||
labels:
|
||||
# 声明为角色模板
|
||||
halo.run/role-template: "true"
|
||||
# 声明为隐藏
|
||||
halo.run/hidden: "true"
|
||||
annotations:
|
||||
# 聚合到 anonymous 角色
|
||||
rbac.authorization.halo.run/aggregate-to-anonymous: "true"
|
||||
rules:
|
||||
- apiGroups: ["api.moment.halo.run"]
|
||||
resources: ["moments"]
|
||||
verbs: ["get", "list"]
|
||||
```
|
||||
|
||||
## Halo 中的特殊角色
|
||||
|
||||
### anonymous 角色
|
||||
|
||||
在 Halo 中，任何访问者都会被赋予一个特殊的角色，这个角色是 `anonymous`，表示未登录的匿名访客。`anonymous` 角色是一个特殊的角色，它不需要绑定到用户，用户无需登录即可获得 `anonymous` 角色的权限。
|
||||
|
||||
`anonymous` 角色的定义参考 [anonymous 角色](https://github.com/halo-dev/halo/blob/main/application/src/main/resources/extensions/role-template-anonymous.yaml)。
|
||||
|
||||
### authenticated 角色
|
||||
|
||||
`authenticated` 角色表示已登录的用户，用户登录后会被赋予 `authenticated` 角色。`authenticated` 角色的权限是 Halo 中所有用户的最小权限，即所有登录用户都会获得 `authenticated` 角色的权限。
|
||||
|
||||
如果开发插件时但凡登录用户都需要具备的权限集合，可以通过将角色聚合到 `authenticated` 角色来实现。这样便不需要为每个用户单独配置权限，只需要将角色聚合到 `authenticated` 角色即可。
|
||||
|
||||
`authenticated` 角色的定义参考 [authenticated 角色](https://github.com/halo-dev/halo/blob/main/application/src/main/resources/extensions/role-template-authenticated.yaml)。
|
||||
|
||||
## Halo 中的内置角色
|
||||
|
||||
Halo 中内置了一些角色，管理员可以在创建用户时直接分配这些角色。内置角色的权限是固定的，不可修改。
|
||||
|
||||
### 超级管理员
|
||||
|
||||
超级管理员的角色名为 `super-role`，它包含了 Halo 中所有资源的所有权限。超级管理员可以访问 Halo 中的所有资源，包括系统资源和插件资源。
|
||||
|
||||
```yaml
|
||||
apiVersion: v1alpha1
|
||||
kind: Role
|
||||
metadata:
|
||||
name: super-role
|
||||
labels:
|
||||
rbac.authorization.halo.run/system-reserved: "true"
|
||||
annotations:
|
||||
rbac.authorization.halo.run/display-name: "超级管理员"
|
||||
rbac.authorization.halo.run/ui-permissions: |
|
||||
["*"]
|
||||
rules:
|
||||
- apiGroups: ["*"]
|
||||
resources: ["*"]
|
||||
nonResourceURLs: ["*"]
|
||||
verbs: ["*"]
|
||||
```
|
||||
|
||||
### 访客角色
|
||||
|
||||
访客角色的角色名为 `guest`，它没有任何权限，当用户被分配了访客角色时，用户只具有 `anonymous` 和 `authenticated` 角色的权限，由于 `anonymous` 和 `authenticated` 角色是不可分配的，因此访客角色用来表示用户的这种状态。
|
||||
|
||||
```yaml
|
||||
apiVersion: v1alpha1
|
||||
kind: Role
|
||||
metadata:
|
||||
name: guest
|
||||
labels:
|
||||
rbac.authorization.halo.run/system-reserved: "true"
|
||||
annotations:
|
||||
rbac.authorization.halo.run/display-name: "访客"
|
||||
rbac.authorization.halo.run/disallow-access-console: "true"
|
||||
rules: []
|
||||
```
|
||||
|
||||
### 文章内置角色
|
||||
|
||||
文章是 Halo 的核心功能之一，因此 Halo 内置了一些文章相关的角色，以便个人中心功能的正常运行。
|
||||
|
||||
- 文章作者：文章作者允许用户管理自己的文章，包括投稿、创建、修改、发布、删除等操作。
|
||||
- 投稿者：投稿者允许用户投稿文章，但是不能直接发布文章，需要管理员审核后才能发布。
|
||||
- 文章管理员：文章管理员允许用户管理所有文章，包括修改、发布、删除等文章关联的所有操作。
|
||||
|
||||
## 参考
|
||||
|
||||
关于角色模板的配置详解请参考[API 权限控制](./role-template.md)。
|
||||
@@ -4,7 +4,7 @@ description: 了解如何对插件中的 API 定义角色模板以接入权限
|
||||
---
|
||||
|
||||
插件中的 APIs 无论是自定义模型自动生成的 APIs 或者是通过 `@Controller` 自定义的 APIs 都只有超级管理员能够访问，如果想将这些 APIs 授权给其他用户访问，
|
||||
则需要定义一些[角色模板](../../basics/framework.md#rbac)的资源以便可以在用户界面上将其分配给其他角色使用。
|
||||
则需要定义一些[角色模板](../basics/framework.md#rbac)的资源以便可以在用户界面上将其分配给其他角色使用。
|
||||
|
||||
## 角色模板定义
|
||||
|
||||
@@ -127,11 +127,11 @@ rules:
|
||||
verbs: [ "get", "list" ]
|
||||
```
|
||||
|
||||
上述便是根据 [自定义模型](./extension.md) 章节中定义的 Person 自定义模型来配置角色模板的示例。
|
||||
上述便是根据 [自定义模型](../api-reference/server/extension.md) 章节中定义的 Person 自定义模型来配置角色模板的示例。
|
||||
|
||||
1. 定义了一个用于管理 Person 自定义模型对象的角色模板 `my-plugin-role-manage-persons`，它具有所有权限。
|
||||
2. 定义了一个只允许查询 Person 资源的角色模板 `my-plugin-role-view-persons`。
|
||||
3. `metadata.name` 的命名规则参考 [metadata name 命名规范](../server/extension.md#metadata-name)。
|
||||
3. `metadata.name` 的命名规则参考 [metadata name 命名规范](../api-reference/server/extension.md#metadata-name)。
|
||||
|
||||
下面让我们回顾一下这些配置：
|
||||
|
||||
@@ -151,38 +151,7 @@ rules:
|
||||
|
||||
### UI 权限控制 {#ui-permissions}
|
||||
|
||||
通过在角色模板的 `metadata.annotations` 中定义 `rbac.authorization.halo.run/ui-permissions` 来控制 UI 权限，这样可以在前端界面通过这个权限来控制菜单或者页面按钮是否展示。
|
||||
|
||||
值的规则为 `plugin:{your-plugin-name}:scope-name`, `scope-name` 为你自定义的权限名称，如上面的示例中的 `plugin:my-plugin:person:view` 和 `plugin:my-plugin:person:manage`。
|
||||
|
||||
你可以在 UI 层面使用这个权限来控制菜单是否展示：
|
||||
|
||||
```javascript
|
||||
{
|
||||
path: "",
|
||||
name: "HelloWorld",
|
||||
component: DefaultView,
|
||||
meta: {
|
||||
permissions: ["plugin:my-plugin:person:view"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> 该配置示例为在插件前端部分入口文件 `index.ts`。
|
||||
|
||||
或者在按钮或页面组件中使用这个权限来控制是否展示：
|
||||
|
||||
```html
|
||||
<template>
|
||||
<!-- HasPermission 组件不需要导入，直接使用即可 -->
|
||||
<HasPermission :permissions="['plugin:my-plugin:person:view']">
|
||||
<UserFilterDropdown
|
||||
v-model="selectedUser"
|
||||
label="用户"
|
||||
/>
|
||||
</HasPermission>
|
||||
</template>
|
||||
```
|
||||
参考 [UI 权限控制](./ui-permission.md)。
|
||||
|
||||
### Verbs 详解 {#verbs}
|
||||
|
||||
@@ -212,23 +181,6 @@ rules:
|
||||
| `delete` | DELETE | 删除单个资源 |
|
||||
| `deletecollection` | DELETE | 删除资源集合 |
|
||||
|
||||
## 默认角色
|
||||
|
||||
在 Halo 中，每个访问者都至少有一个角色，包括未登录的用户（被称为匿名用户）它们会拥有角色为 `anonymous` 的角色，而已登录的用户则会至少拥有一个角色名为 `authenticated` 的角色，
|
||||
但这两个角色不会显示在角色列表中。
|
||||
|
||||
`anonymous` 角色的定义参考 [anonymous 角色](https://github.com/halo-dev/halo/blob/main/application/src/main/resources/extensions/role-template-anonymous.yaml)。
|
||||
|
||||
`authenticated` 角色的定义参考 [authenticated 角色](https://github.com/halo-dev/halo/blob/main/application/src/main/resources/extensions/role-template-authenticated.yaml)。
|
||||
|
||||
进入角色列表页面，你会看到一些内置角色，用于方便你快速的分配权限给用户，并可以基于这些角色来创建新的角色：
|
||||
|
||||
- 超级管理员：拥有所有权限，不可删除，不可编辑。
|
||||
- 访客：拥有默认的 `anonymous` 和 `authenticated` 角色的权限。
|
||||
- 投稿者：拥有“允许投稿”的权限。
|
||||
- 作者：拥有“允许管理自己的文章”和”允许发布自己的文章“的权限。
|
||||
- 文章管理员：拥有“允许管理所有文章”的权限。
|
||||
|
||||
## 角色绑定
|
||||
|
||||
角色绑定用于将角色中定义的权限授予一个或一组用户。它包含主体列表（用户）以及对所授予角色的引用。
|
||||
@@ -257,51 +209,3 @@ subjects:
|
||||
```
|
||||
|
||||
在 Halo 中，当你给一个用户分配角色后，实际上就是创建了一个 ”RoleBinding” 对象来完成的。
|
||||
|
||||
## 聚合角色
|
||||
|
||||
你可以聚合角色来将多个角色的权限聚合到一个已有的角色中，这样你就不需要再为每个用户分配多个角色了。
|
||||
|
||||
聚合角色是通过在你定义的角色模板中添加 `"rbac.authorization.halo.run/aggregate-to-` 开头的 label 来实现的，例如
|
||||
|
||||
```yaml
|
||||
apiVersion: v1alpha1
|
||||
kind: "Role"
|
||||
metadata:
|
||||
name: role-template-view-categories
|
||||
labels:
|
||||
halo.run/role-template: "true"
|
||||
rbac.authorization.halo.run/aggregate-to-editor: "true"
|
||||
annotations:
|
||||
rbac.authorization.halo.run/ui-permissions: |
|
||||
[ "system:categories:view", "uc:categories:view" ]
|
||||
rules:
|
||||
- apiGroups: [ "content.halo.run" ]
|
||||
resources: [ "categories" ]
|
||||
verbs: [ "get", "list" ]
|
||||
```
|
||||
|
||||
`rbac.authorization.halo.run/aggregate-to-editor` 表示将 `role-template-view-categories` 角色聚合到 `editor` 角色中，这样所有拥有 `editor` 角色的用户都会拥有 `role-template-view-categories` 角色的权限。
|
||||
|
||||
如果你想将你写的资源型 APIs 公开给所有用户访问，这时你可以通过聚合角色来将你的资源型 APIs 的角色聚合到 `anonymous` 角色中，这样所有用户都可以访问你的资源型 APIs 了。
|
||||
|
||||
```yaml
|
||||
apiVersion: v1alpha1
|
||||
kind: Role
|
||||
metadata:
|
||||
name: my-plugin-role-view-persons
|
||||
labels:
|
||||
halo.run/role-template: "true"
|
||||
rbac.authorization.halo.run/aggregate-to-anonymous: "true"
|
||||
annotations:
|
||||
rbac.authorization.halo.run/module: "Persons Management"
|
||||
rbac.authorization.halo.run/display-name: "Person Manage"
|
||||
rbac.authorization.halo.run/ui-permissions: |
|
||||
["plugin:my-plugin:person:view"]
|
||||
rules:
|
||||
- apiGroups: ["my-plugin.halo.run"]
|
||||
resources: ["my-plugin/persons"]
|
||||
verbs: ["*"]
|
||||
```
|
||||
|
||||
`rbac.authorization.halo.run/aggregate-to-anonymous` 的写法就表示将 `my-plugin-role-view-persons` 角色聚合到 `anonymous` 角色中。
|
||||
101
docs/developer-guide/plugin/security/ui-permission.md
Normal file
101
docs/developer-guide/plugin/security/ui-permission.md
Normal file
@@ -0,0 +1,101 @@
|
||||
---
|
||||
title: UI 权限控制
|
||||
description: 了解如何控制用户界面的操作权限。
|
||||
---
|
||||
UI（用户界面）权限控制是指在应用程序中，通过用户角色或身份的不同，控制用户界面上可见和可操作的元素。
|
||||
这种权限控制的目的是根据用户的权限等级和角色，动态调整他们在应用中的操作权限，从而确保系统的安全性和功能的正确使用。
|
||||
|
||||
## 什么是 UI 权限控制
|
||||
|
||||
UI 权限控制基于后端的权限系统，将不同用户分组或分角色，并根据这些分组或角色，决定用户在界面中能够看到哪些内容、进行哪些操作。
|
||||
与传统的后端权限控制相比，UI 权限控制侧重于前端展示层面的权限管理，例如隐藏按钮、禁用功能、调整界面元素等，以防止未经授权的用户误操作或访问敏感数据。
|
||||
|
||||
## UI 权限控制的核心概念
|
||||
|
||||
1. 用户角色（User Role）：UI 权限控制通常基于用户角色。例如，管理员可能拥有对系统所有模块的访问权限，而普通用户只能访问某些特定模块或功能。
|
||||
|
||||
2. 权限模型：权限模型规定了每个角色能够执行的操作以及能访问的资源。UI 权限控制根据这个模型，动态调整界面上展示的内容。
|
||||
|
||||
3. 可见性控制：UI 控制权限的一个常见方式是调整某些界面元素的可见性。例如，一个普通用户可能看不到“管理用户”或“高级设置”选项，而这些选项对管理员是可见的。
|
||||
|
||||
4. 操作控制：除了控制可见性外，UI 权限控制还可以控制用户能执行的操作。例如，某个表单中的提交按钮可能在用户没有相应权限时被禁用或移除。
|
||||
|
||||
5. 动态渲染：基于用户权限动态渲染 UI，是指前端应用在加载时会根据用户的权限信息来渲染不同的界面元素。这样确保用户只能看到和操作与其权限相符的部分。
|
||||
|
||||
## Halo 的 UI 权限控制
|
||||
|
||||
Halo 的 UI 权限控制是通过与角色模板结合来实现的，在角色模板的 `metadata.annotations` 中定义 `rbac.authorization.halo.run/ui-permissions` 来控制 UI 权限，这样可以在前端界面通过这个权限来控制菜单或者页面按钮是否展示。
|
||||
|
||||
值的规则为 `plugin:{your-plugin-name}:scope-name`, `scope-name` 为你自定义的权限名称，如下面的示例中的 `plugin:my-plugin:person:view`。
|
||||
|
||||
```yaml
|
||||
apiVersion: v1alpha1
|
||||
kind: Role
|
||||
metadata:
|
||||
name: my-plugin-role-view-persons
|
||||
labels:
|
||||
halo.run/role-template: "true"
|
||||
annotations:
|
||||
# UI 权限控制
|
||||
rbac.authorization.halo.run/ui-permissions: |
|
||||
["plugin:my-plugin:person:view"]
|
||||
rules:
|
||||
- apiGroups: ["my-plugin.halo.run"]
|
||||
resources: ["my-plugin/persons"]
|
||||
verbs: ["*"]
|
||||
```
|
||||
|
||||
当用户被分配了拥有 `my-plugin-role-view-persons` 权限的角色时，前端界面便会根据这个权限来控制菜单或者页面按钮是否展示。
|
||||
|
||||
### 菜单权限控制
|
||||
|
||||
你可以在 UI 层面使用这个权限来控制菜单是否展示：
|
||||
|
||||
```vue
|
||||
export default definePlugin({
|
||||
components: {},
|
||||
routes: [
|
||||
{
|
||||
parentName: "Root",
|
||||
route: {
|
||||
path: "/example",
|
||||
name: "Example",
|
||||
component: HomeView,
|
||||
meta: {
|
||||
title: "示例页面",
|
||||
searchable: true,
|
||||
// 菜单权限控制
|
||||
permissions: ["plugin:my-plugin:person:view"],
|
||||
menu: {
|
||||
name: "示例页面",
|
||||
group: "示例分组",
|
||||
icon: markRaw(IconPlug),
|
||||
priority: 0,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
],
|
||||
extensionPoints: {},
|
||||
});
|
||||
```
|
||||
|
||||
参考：[plugin-starter](https://github.com/halo-dev/plugin-starter/blob/5a4a25db252a7986900368a5fbf35e8d27f5257f/ui/src/index.ts#L6-L29)
|
||||
|
||||
> 该配置示例为在插件前端部分入口文件 `index.ts`
|
||||
|
||||
### 按钮或页面组件权限控制
|
||||
|
||||
在按钮或页面组件中使用 `HasPermission` 组件来控制组件的渲染，它不需要导入可以直接使用。
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<!-- HasPermission 组件不需要导入，直接使用即可 -->
|
||||
<HasPermission :permissions="['plugin:my-plugin:person:view']">
|
||||
<UserFilterDropdown
|
||||
v-model="selectedUser"
|
||||
label="用户"
|
||||
/>
|
||||
</HasPermission>
|
||||
</template>
|
||||
```
|
||||
Reference in New Issue
Block a user