跳到主要内容

自定义权限点

适用环境SaaS
私有部署

要求​

ONES
v3.10.14+

概述​

有时候插件自定义的内容也需要控制访问权限，只依赖 ONES 已有的权限校验无法满足插件自定义内容的权限控制。因此我们提供自定义权限点能力，使用该能力可以对插件自定义内容进行访问限制。例如：当插件的前端需要实现分"级别"的页面，不同的用户（群组）具备不同的访问范围时，可以使用该能力进行权限控制。

备注

使用该能力添加的权限点只在插件内生效，即只能控制插件添加内容的访问权限。

能力表现​

使用能力添加了权限之后，在插件详情的权限配置页有相关权限配置。

使用​

自定义权限能力支持通过 自定义的标准权限配置、自定义权限点 API 和 自定义权限点能力 三种方式使用自定义权限点。自定义的权限点目前只能配合前端插槽使用，具体使用方法请参照：permission

警告

只有通过能力添加的权限点才能由插件自定义权限校验逻辑，其他都是使用 ONES 原有权限校验逻辑。

自定义的标准权限配置​

在插件的配置文件中添加自定义的标准权限点配置项数组

参数：

参数说明类型必填默认值
name权限名称string是-
field权限唯一标识string是-
desc权限描述string否-

示例：

config/plugin.yaml
service:
  permission:
    - name: My custom read permission
      field: my-custom-read-permission-key
      desc: This is an example of custom read permission

自定义权限点 API - 后端​

提供非声明式的权限点定义和配置方法，在插件后端中可以使用这些 API 来管理自定义权限。

备注

示例中均通过 ONES 接口注册 能力添加 addition 接口进行调试

添加权限点​

入参：

参数说明类型必填
path路由，固定值: AddPermissionInfostring是
headers请求头，固定值: { "AbilityName": ["AddPermissionInfo"] }any是
method请求方法，固定值:POSTstring是
body请求体，包含权限点信息。any是

body

参数说明类型必填
permission_name权限点名称string是
permission_field权限点标识string是
permission_desc权限点描述string是

返回内容：response.body['data']中的内容

  • 正常

    参数说明类型备注
    instance_uuid插件示例 idstring
    permission_name权限点名称string
    permission_desc权限点描述string
    permission_field权限点唯一标识string
    permission_id权限点 idstring
    check_mode校验类型string
    ability_id能力 idstring

  • 错误

    当添加的权限点已经存在时返回：permission_field of plugin already exists

示例：

export async function addPermission(request: PluginRequest): Promise<PluginResponse> {
  const response = await fetchONES({
    path: `AddPermissionInfo`,
    headers: {
      AbilityName: ['AddPermissionInfo'],
    },
    method: 'POST',
    body: {
      permission_name: 'api_add_permission', // 权限点名称
      permission_field: 'api_add_permission123', // 权限点唯一标识
      permission_desc: 'test', // 插件点描述
    },
  })
  const body = response?.body as any
  const data = JSON.parse(body.toString())['data']
  Logger.info(data)
  return {
    body: {
      data: data,
    },
  }
}

获取权限点​

入参：

参数说明类型必填
path路由，固定值: PermissionInfoListstring是
headers请求头，固定值: { "AbilityName": ["PermissionInfoList"] }any是
method请求方法，固定值:POSTstring是
teamUUID团队idstring是

返回内容: response.body['data']中的内容，包含权限点信息数组，每个权限点包含以下内容

permission​
参数说明类型
instance_uuid插件示例 idstring
permission_name权限点名称string
permission_desc权限点描述string
permission_field权限点唯一标识string
permission_id权限点 idstring
check_mode校验类型string
rule_info已配置规则的信息rule[]
rule​
参数说明类型
id权限规则 idstring
permission_id权限点 idstring
context_type上下文类型string
context_param_1上下文参数string
context_param_2上下文参数string
user_domain_type用户域类型string
user_domain_param用户域参数string
position位置string

示例：

export async function listPermission(request: PluginRequest): Promise<PluginResponse> {
  const { team_uuid } = request.body as any
  const response = await fetchONES({
    path: `PermissionInfoList`,
    headers: {
      AbilityName: ['PermissionInfoList'],
    },
    method: 'POST',
    body: {},
    teamUUID: team_uuid,
  })
  const body = response?.body as any
  const data = JSON.parse(body.toString())['data']
  Logger.info(data)
  return {
    body: {
      data: data,
    },
  }
}

删除权限点​

入参：

参数说明类型必填
path路由，固定值: DeletePermissionInfostring是
headers请求头，固定值: { "AbilityName": ["DeletePermissionInfo"] }any是
method请求方法，固定值:POSTstring是
body请求体，包含权限点唯一标识any是

body

参数说明类型必填
permission_field权限点标识string是

示例：

export async function deletePermission(request: PluginRequest): Promise<PluginResponse> {
  const response = await fetchONES({
    path: `DeletePermissionInfo`,
    headers: {
      AbilityName: ['DeletePermissionInfo'],
    },
    method: 'POST',
    body: {
      permission_field: 'api_add_permission123',
    },
  })
  const body = response?.body as any
  const data = JSON.parse(body.toString())['data']
  Logger.info(data)
  return {
    body: {
      data: data,
    },
  }
}

添加权限规则​

入参：

参数说明类型必填
path路由，固定值: AddPermissionRulestring是
headers请求头，固定值: { "AbilityName": ["AddPermissionRule"] }any是
method请求方法，固定值:POSTstring是
body请求体，包含权限点规则信息any是
teamUUID团队uuidstring是

body

参数说明类型必填
permission_id权限点 idstring是
user_domain_type用户域种类，可选值：
所有人-everyone
用户-single_user
部门-department
用户组-group
团队负责人-team_owner		string是
user_domain_param用户领域的唯一标示，例如当用户域是single_user时，该参数的值表示user_uuidstring是

返回内容：response.body['data']中的内容

  • 正常

    包含本次添加权限规则的信息

    参数说明类型
    org_uuid组织 uuidstring
    team_uuid团队 uuidstring
    id权限规则 idstring
    deleted是否删除Bool
    permission_id权限点 idstring
    context_type上下文类型string
    context_param_1上下文参数string
    context_param_2上下文参数string
    user_domain_type用户域类型string
    user_domain_param用户域参数string
    position位置string

  • 错误

    当添加的权限点规则用户域类型不对时返回：<UserDomainNotExist> UserDomainNotExist

示例：

export async function addRule(request: PluginRequest): Promise<PluginResponse> {
  const { user_uuid, permission_id, team_uuid } = request.body as any
  const response = await fetchONES({
    path: `AddPermissionRule`,
    headers: {
      AbilityName: ['AddPermissionRule'],
    },
    method: 'POST',
    body: {
      permission_id: permission_id, // permission唯一id，在add_permission_info时返回
      user_domain_type: 'single_user', // 用户域种类，现有：everyone,single_user,department,group,team_owner
      user_domain_param: user_uuid, // 用户领域的唯一标示，例如当user_domain_type是single_user时，user_domain_param就是标示user_uuid
      teamUUID: team_uuid, // 团队uuid
    },
    teamUUID: team_uuid, // 团队uuid
  })
  const body = response?.body as any
  const data = JSON.parse(body.toString())['data']
  Logger.info(data)
  return {
    body: {
      data: data,
    },
  }
}

删除权限规则​

入参：

参数说明类型必填
path路由，固定值: DeletePermissionRulestring是
headers请求头，固定值: { "AbilityName": ["DeletePermissionRule"] }any是
method请求方法，固定值:POSTstring是
body请求体，包含权限规则唯一标识any是

body

参数说明类型必填
id权限点规则标识string是

示例：

export async function deleteR(request: PluginRequest): Promise<PluginResponse> {
  const { rule_id, user_uuid } = request.body as any
  const response = await fetchONES({
    path: `DeletePermissionRule`,
    headers: {
      AbilityName: ['DeletePermissionRule'],
    },
    method: 'POST',
    body: {
      id: rule_id, // permission_rule唯一id，在add_permission_rule时会返回
    },
  })
  const body = response?.body as any
  const data = JSON.parse(body.toString())['data']
  Logger.info(data)
  return {
    body: {
      data: data,
    },
  }
}

权限点校验​

入参：

参数说明类型必填
path路由，固定值: CheckPermissionRulestring是
headers请求头，固定值: { "AbilityName": ["CheckPermissionRule"] }any是
method请求方法，固定值:POSTstring是
body请求体，包含检验相关信息any是
teamUUID团队uuidstring是

body

参数说明类型必填
permission_field权限点标识string是
user_uuid用户的uuidstring是

返回内容：response.body['data']中的内容

参数说明类型
is_permission是否有权限bool

示例：

export async function checkPermission(request: PluginRequest): Promise<PluginResponse> {
  const { user_uuid, permission_field, team_uuid } = request.body as any
  const response = await fetchONES({
    path: `CheckPermissionRule`,
    headers: {
      AbilityName: ['CheckPermissionRule'],
    },
    method: 'POST',
    body: {
      permission_field: permission_field,
      user_uuid: user_uuid,
      teamUUID: team_uuid,
    },
    teamUUID: team_uuid,
  })
  const body = response?.body as any
  const data = JSON.parse(body.toString())['data']
  Logger.info(data)
  return {
    body: {
      data: data,
    },
  }
}

批量权限点校验​

入参：

参数说明类型必填
path路由，固定值: BatchCheckPermissionstring是
headers请求头，固定值: { "AbilityName": ["BatchCheckPermission"] }any是
method请求方法，固定值:POSTstring是
body请求体，包含所有的校验信息any是

body

参数说明类型必填
organization_uuid组织的uuidstring是
permission_field权限的唯一标识string是
team_uuid团队的uuidstring是
instance_id插件实例 idstring是
user_uuid用户的uuidstring是

返回内容：response.body['data']中的内容

参数说明类型
is_permission每个权限检查的结果bool[]

示例：

export async function checkBatch(request: PluginRequest): Promise<PluginResponse> {
  const { user_uuid, permission_field, user_uuid2 } = request.body as any
  const response = await fetchONES({
    path: `BatchCheckPermission`,
    headers: {
      AbilityName: ['BatchCheckPermission'],
    },
    method: 'POST',
    body: {
      permission_rules: [
        {
          organization_uuid: global.onesEnv.organizationUUID,
          permission_field: permission_field,
          team_uuid: global.onesEnv.teamUUID,
          instance_id: global.onesEnv.instanceId,
          user_uuid: user_uuid,
        },
        {
          organization_uuid: global.onesEnv.organizationUUID,
          permission_field: permission_field,
          team_uuid: global.onesEnv.teamUUID,
          instance_id: global.onesEnv.instanceId,
          user_uuid: user_uuid2,
        },
      ],
    },
  })
  const body = response?.body as any
  const data = JSON.parse(body.toString())['data']
  Logger.info(data)
  return {
    body: {
      data: data,
    },
  }
}

自定义权限点 API - 前端​

获取权限点列表​

获取自定义权限点列表及其规则

URL​

https://your-host-name/project/api/project/team/:team_uuid/plugin/permissioninfo/list

HTTP Method​

POST

传值方式​

json

请求参数列表​
参数名是否必须值类型说明
instance_uuid是string插件实例 ID
team_uuid是string团队uuid
organization_uuid是string组织uuid
返回参数列表​
参数名值类型说明
datapermission[]自定义权限点数组
请求示例​
curl --location 'https://your-host-name/project/api/project/team/:team_uuid/plugin/permissioninfo/list' \
--header 'Ones-User-Id: N5tnQP1D' \
--header 'Content-Type: application/json;charset=utf-8' \
--header 'Ones-Auth-Token: 9iiqA0As7UldZ61aOSpzaMAQclSRWXCAGOwNK2D3yolDYodoJGr764bpOVm2QVLp' \
--header 'Ones-Plugin-Id: built_in_apis' \
--data '{
    "instance_uuid": "994af1e3",
    "team_uuid": "E1r1oDP1",
    "organization_uuid": "9qcEhFjy"
}'
返回示例​
{
  "data": [
    {
      "instance_uuid": "994af1e3",
      "permission_name": "Permission",
      "permission_field": "my_permission",
      "permission_id": "1646758032098463744",
      "permission_desc": "Custom permission",
      "check_mode": "standard",
      "rule_info": [
        {
          "id": "1646758267080151040",
          "permission": "1646758032098463744",
          "context_type": "plugin",
          "context_param_1": "994af1e3",
          "context_param_2": "",
          "user_domain_type": "single_user",
          "user_domain_param": "N5tnQP1D",
          "position": 1
        }
      ]
    }
  ]
}

权限点校验​

检验用户是否有某个自定义权限点的权限

URL​

https://your-host-name/project/api/project/team/:team_uuid/plugin/permissionrule/check

HTTP Method​

POST

传值方式​

json

请求参数列表​
参数名是否必须值类型说明
instance_id是string插件实例 ID
team_uuid是string团队uuid
organization_uuidSaaS 模式非必填string组织uuid
permission_field是string自定义权限点配置的field
返回参数列表​
参数名值类型说明
is_permissionbool是否有权限
请求示例​

请求头中的Ones-User-Id 参数的值为本次校验的用户

curl --location 'http://your-host-name/project/api/project/team/E1r1oDP1/plugin/permissionrule/check' \
--header 'Ones-User-Id: 6wFTfuTt' \
--header 'Content-Type: application/json;charset=utf-8' \
--header 'Ones-Plugin-Id: built_in_apis' \
--data '{
    "instance_id": "994af1e3",
    "team_uuid": "E1r1oDP1",
    "organization_uuid": "9qcEhFjy",
    "permission_field": "table_view_permission"
}'
返回示例​
{
  "data": {
    "is_permission": true
  }
}

自定义权限点能力​

第一步：添加配置​

使用npx op add ability 添加 custom-permission@1.0.0类型的能力，生成backend/src/custom-permission.ts文件并在插件的配置文件中生成能力配置。

能力配置中的参数的作用：

参数作用类型
name权限点名称string
field权限点标识string
desc权限点描述string
is_plugin_custom_check是否采用插件自定义权限校验bool

示例：

abilities:
  - id: WIXJvPcd
    name: CustomPermission
    version: 1.0.0
    abilityType: CustomPermission
    function:
      customPermissionCheckFunc: customPermissionCheck
    config:
      - key: name
        value: Permission
        label: Permission name
        show: false
      - key: field
        value: my_permission
        label: Permission field
        show: false
      - key: desc
        value: Custom permission
        label: Permission description
        show: false
      - key: is_plugin_custom_check
        value: false
        label: Plugin custom permission verification
        show: false

第二步：编写权限校验函数​

根据能力配置中function.customPermissionCheckFunc配置的函数名称，在backend/src/custom-permission.ts添加对应的权限校验函数，当使用的是插件自定义权限校验时，会调用该函数进行权限校验。

入参:

参数说明类型
user_uuid用户的uuidstring
permission_field权限点标识string
context权限上下文参数PermissionContext
interface PermissionContext {
  project_uuid?: string // 项目管理 -> 项目ID
  filter_view_uuid?: string // 我的工作台 -> 筛选器 -> 筛选器视图ID
  program_uuid?: string // 项目集管理 -> 项目集ID
  product_uuid?: string // 产品管理 -> 产品ID
  testcase_library_uuid?: string // 测试管理 -> 测试用例库ID
  test_plan_uuid?: string // 测试管理 -> 测试计划ID
  wiki_space_uuid?: string // 知识管理 -> 页面组ID
  workspace_dashboard_uuid?: string // 我的工作台 -> 仪表盘 -> 仪表盘ID
  performance_dashboard_uuid?: string // 效能管理 -> 仪表盘 -> 仪表盘ID
}
警告

如果权限校验逻辑依赖权限上下文参数，还需要在使用权限点的模块下配置 needPermissionContext 为true，只有这样才会在权限上下文变动时重新校验权限。

**返回内容: **通过返回体中的is_permission字段的值来决定权限校验是否通过

**示例: **只限制user_uuid为SFBs7BHh的用户

import { Logger } from '@ones-op/node-logger'
import { PluginRequest, PluginResponse } from '@ones-op/node-types'

export async function customPermissionCheck(request: PluginRequest): Promise<PluginResponse> {
  const body = request?.body as any
  Logger.info(JSON.stringify(body, undefined, 2))
  let permission = true
  if (body.uuid == 'SFBs7BHh') {
    permission = false
  }
  return {
    statusCode: 200,
    body: {
      code: 200,
      body: {
        is_permission: permission,
      },
    },
  }
}

示例​

系统顶栏右侧组件

最后于 更新