5.7. 安全

从版本 7.2.0 开始，除了在运行时创建角色和分组之外，CUBA 中可以定义设计时角色和访问组。目前 Studio 能支持设计时角色定义。

Studio 在 CUBA 项目树的 Security 部分显示用于定义设计时角色的类：

security section

5.7.1. 创建角色定义

右键点击 Security 部分，选择 New → Role 菜单项即可创建新的设计时角色。点击后弹出 New Role 对话框：

create role

  • Role Name - 角色名称。这是一个代码级别的名称，可以用在代码中。

  • Class - 定义角色的类名。填写了角色名称后会自动填写该字段。

  • Security Scope - 选择客户端角色权限的类型：

点击 OK 创建角色定义类。接下来，您可以按照开发者手册的 相应章节 介绍的规则，在源代码中添加角色权限。激活 CUBA Studio 订阅的用户可以使用可视化设计器设计角色权限。

5.7.2. 使用角色设计器

设计时角色定义的代码编辑器还集成了可视化的 Role Designer - 角色设计器。角色设计器支持可视化的配置角色和必要的角色权限。可以直接编辑代码，也可以用角色设计器生成代码。

角色设计器 是以标签页的形势展示，在代码编辑器底部有切换控制。标签页如下：

  • Text - 展示并可以编辑 Java/Kotlin 源代码。

  • Definition - 定义基本的角色属性。

  • Screens - 定义菜单项和界面权限。

  • Entities - 定义实体和实体属性的 CRUD 权限。

  • Specific - 定义角色的特殊权限以及修改项目的特殊权限配置。

Tip

角色设计器只有激活 CUBA Studio 订阅才能使用。

role designer tabs

5.7.2.1. Definition 标签页

Definition 标签页可以编辑角色基本属性。

role tab definition

  • Name - 角色的唯一名称。是代码级别名称，可以用在编码中。

  • Scope - 客户端角色权限类型：

  • Default Role - 是否默认角色，默认角色会在创建新用户时自动为用户分配。用这个选项可以为新用户默认体用一组权限许可。

  • Super Role - 是否超级角色，有该角色的用户会是具有所有权限的超级用户。

  • Description - 角色描述。会显示在角色浏览界面和编辑界面。

Warning

注意，识别设计时角色是通过数据库角色名称进行识别的，因此，在为任何用户分配了设计时角色之后，就不要再修改角色名称了（否则需要手动更新数据库）。

5.7.2.2. Screens 标签页

角色设计器的 Screens 标签页可以编辑以下应用程序元素的权限：

  • 主菜单项

  • 其他界面（无法从主菜单直接访问的界面）

  • 界面中的 UI 组件。

role tab screens

左侧的树结构展示主菜单项以及项目定义的界面和从平台或扩展插件继承的界面。树中的 Other Screens 分组展示项目中不能通过主菜单直接访问的界面。界面列表可以用顶部的搜索框对名称进行过滤。如果为界面定义了任何组件权限，则组件以子节点的形式展示在界面节点下。

默认拒绝所有菜单项和界面的访问。通过在左侧选择界面、右侧点击 Allow 即可为角色添加能打开对应菜单项或者界面的许可权限。

界面树的顶部有工具栏，包含以下操作：

  • Add Component Permission (+) - 为选中的界面创建组件权限。

  • Delete Component Permission (-) - 删除之前定义的组件权限。

  • Expand All, Collapse All - 收起或展开所有的树节点。

  • Settings → Show Assigned Only - 显示没有配置权限的所有界面和菜单项的开关。

组件权限

组件权限能用来隐藏界面中的特定 UI 组件或将其标记为只读，不论这些组件是否绑定实体。默认用户能使用所有组件。如需添加组件权限，选中组件所在的界面节点，然后点击 + (Add Component Permission) 按钮，会弹出 Create Component Permission 对话框：

create component permission

  • Component - 组件 ID。该字段提供了自动完成功能，按下 Ctrl+Enter 查看所有选项。

  • Permission - 指定组件权限：

    • Modify - 组件可查看、可编辑。

    • Deny - 组件隐藏。

    • View - 组件可见，但是不能编辑（比如一些表单字段）

点击 OK 完成设置后，组件以子节点的形式展示在界面节点下。

5.7.2.3. Entities 标签页

角色设计器的 Entities 标签页用来编辑实体和实体属性的权限。

role tab entities

面板左侧的表格展示项目中定义的实体以及从平台或者扩展插件中继承的实体。实体列表可以用表格上方的过滤器对名称进行过滤。

实体表格上方还有一个工具栏，包含如下操作：

  • Show Inherited from Platform and Add-Ons - 隐藏或显示继承实体的开关。

  • Show Assigned Only - 隐藏或显示所有实体、包括那些没有权限实体的开关。

默认所有的实体操作都是拒绝的。通过表格中的复选框可以为指定实体允许特定的操作（Create，Read，Update，Delete）。

右侧的表格展示所选实体的属性权限。默认拒绝查看和修改所有实体的属性。勾选 View 和 Modify 复选框可以为选中的属性配置需要的权限。

属性表格的通配符 wildcard 可以用来标记所有的属性都可以 View 和 Modify，包括实体将来可能增加的属性。注意，也可以在一个实体中这么组合：用通配符配置大部分属性都可以 Modify，但是勾选少数几个属性可以 View。

Warning

属性权限的通配符配置是很方便，但是需要小心使用。因为一旦使用，将来无法为该实体的新属性添加权限控制，比如新属性不希望当前角色查看或编辑。

实体表格中的 Allow All 选项允许实体的所有 CRUD 操作，并且也允许对实体属性的 Modify，因此，勾选此项则允许角色对该实体的完全访问。

5.7.2.4. Specific 标签页

角色设计器的 Specific 标签页提供下列功能：

  • 为当前编辑的角色设置特殊权限。

  • 编辑项目中特殊权限及其分类的配置。

特殊权限是定义在任意功能上的权限，不必关联至界面或实体 CRUD。特殊权限分类是将语义上相关的权限放在一组。参阅开发者手册中 特殊权限 ， permissions.xml 了解更多细节。

role tab specific

面板左侧的树展示特殊权限及其分类，包含项目中定义的以及从平台和扩展插件继承的。鼠标选中树节点后，直接按键盘输入搜索文本可以在树中查找权限。

面板右侧包含下列配置：

  • Permission Id - 权限的唯一标识符。

  • Caption - 权限的本地化显示标题。可以为本项目的权限分类和权限设置。

  • Allow 和 Deny - 为当前角色赋予或收回权限。

所有特殊权限默认都是拒绝。

表格上方的工具栏提供下列操作：

  • New → Permission - 声明项目内的新特殊权限。

  • New → Category - 声明一个新的分类。

  • Delete - 删除选中的权限或分类。

  • Expand All, Collapse All - 展开或收起权限树。

定义新特殊权限

如需为项目定义新的特殊权限，首先需要创建一个分类。使用工具栏的 + → Category 操作添加。会弹出 Create Specific Category 对话框：

create specific category

  • Id - 分类的唯一 ID。推荐为嵌套的分类使用组合标识符，比如，sales → sales.audit → sales.audit.bills。

  • Permissions Config - 定义分类的配置文件。

  • Parent Category - 父分类，如无父分类则留空。

点击 OK 之后，新的分类会添加到树中。选择新分类，用右边面板的 Caption 字段定义本地化标题。

如需创建新权限，使用工具栏的 + → Permission 操作添加。会弹出 Create Specific Permission 对话框：

create specific permission

  • Id - 权限的唯一标识符。代码中会用这个 ID 检查权限。

点击 OK 之后，权限会添加到树中。选择新权限，用右边面板的 Caption 字段定义本地化标题。

项目中定义的分类和权限会在 web-permissions.xml 注册。可以在树中右键点击然后选择 Jump to Source 跳转至源代码：

specific context menu