权限管理

版本提示

资源权限管理与角色管理自 v5.0.0 起支持，策略管理自 v5.5.5 起支持。

@cloudbase/manager-node 提供 PermissionService，通过 app.permission 访问，支持三大功能：

策略管理：查询网关鉴权策略列表、获取和设置 OPA Rego 鉴权策略（v5.5.5+）
角色管理：创建/查询/修改/删除用户角色（RBAC），并为角色绑定网关访问策略
资源权限管理：设置和查询云函数、数据库、存储等资源的访问权限（已废弃，请使用策略管理）

OPA 鉴权策略概念

策略管理基于 OPA Rego 策略引擎。关于 OPA 鉴权策略的工作机制、input 上下文结构、allow / deny 决策矩阵及实战案例，请参考 OPA 鉴权策略介绍；从旧版网关鉴权迁移到 OPA Rego 的步骤与策略翻译对照表，请参考迁移指南。

describeResourcePolicyList

1. 接口描述

接口功能：查询网关鉴权策略列表

接口声明：app.permission.describeResourcePolicyList(options?): Promise<Object>

版本提示

自 v5.5.5 起新增此接口。

2. 输入参数

字段	必填	类型	说明
resourceType	否	String	按资源类型过滤，可选值：`policy`

3. 返回结果

字段	类型	说明
RequestId	String	请求唯一标识
Data.PolicyList	`ResourcePolicyItem[]`	策略列表
Data.Total	String	策略总数

ResourcePolicyItem

字段	类型	说明
PolicyId	String	策略 ID
ResourceType	String	资源类型
ResourceId	String	资源 ID
ResourceTitle	String	资源标题
ResourceName	String	资源名称
Effect	String	效果：`allow`/`deny`
IsAccess	Boolean	是否可访问
RoleId	String	角色 ID
RoleIdentity	String	角色标识
RoleName	String	角色名称
SafeRule	String	安全规则

4. 示例代码

import CloudBase from '@cloudbase/manager-node'

const app = CloudBase.init({
  secretId: 'Your SecretId',
  secretKey: 'Your SecretKey',
  envId: 'Your envId'
})

async function test() {
  // 查询全部策略
  const result = await app.permission.describeResourcePolicyList()
  console.log('策略总数:', result.Data.Total)

  // 按资源类型过滤
  const filtered = await app.permission.describeResourcePolicyList({
    resourceType: 'policy'
  })
  console.log('策略列表:', filtered.Data.PolicyList)
}

test()

describeEnvAuthzConfig

1. 接口描述

接口功能：获取鉴权策略内容

接口声明：app.permission.describeEnvAuthzConfig(options): Promise<Object>

版本提示

自 v5.5.5 起新增此接口。

2. 输入参数

字段	必填	类型	说明
key	是	String	策略键名。`authz.user.rego` 获取用户策略，`authz.platform.extension.rego` 获取平台扩展策略

3. 返回结果

字段	类型	说明
RequestId	String	请求唯一标识
Item.Key	String	策略键名
Item.Value	String	策略内容

4. 示例代码

import CloudBase from '@cloudbase/manager-node'

const app = CloudBase.init({
  secretId: 'Your SecretId',
  secretKey: 'Your SecretKey',
  envId: 'Your envId'
})

async function test() {
  // 获取用户策略
  const userPolicy = await app.permission.describeEnvAuthzConfig({
    key: 'authz.user.rego'
  })
  console.log('用户策略:', userPolicy.Item.Value)

  // 获取平台扩展策略
  const extPolicy = await app.permission.describeEnvAuthzConfig({
    key: 'authz.platform.extension.rego'
  })
  console.log('平台扩展策略:', extPolicy.Item.Value)
}

test()

modifyEnvAuthzConfig

1. 接口描述

接口功能：设置鉴权策略

接口声明：app.permission.modifyEnvAuthzConfig(options): Promise<Object>

版本提示

自 v5.5.5 起新增此接口。

重要提示

设置 Rego 策略后，旧网关鉴权将直接失效，请确认策略内容正确后再执行。

2. 输入参数

字段	必填	类型	说明
key	是	String	策略键名，固定为 `authz.user.rego`
value	是	String	Rego 策略内容，需以 `package authz.user` 开头

关于 input 字段的详细说明，请参考 OPA 鉴权策略介绍。

3. 返回结果

字段	类型	说明
RequestId	String	请求唯一标识
AffectedRows	Number	影响行数

4. 示例代码

import CloudBase from '@cloudbase/manager-node'

const app = CloudBase.init({
  secretId: 'Your SecretId',
  secretKey: 'Your SecretKey',
  envId: 'Your envId'
})

async function test() {
  const regoContent = `package authz.user

default allow := false

# 放通匿名用户访问云函数
allow if {
  input.cloudbase.resource_type == "functions"
  input.subject.auth_type == "anonymous"
}`

  const result = await app.permission.modifyEnvAuthzConfig({
    key: 'authz.user.rego',
    value: regoContent
  })
  console.log('影响行数:', result.AffectedRows)
}

test()

角色管理适用于企业内部多人协作、网关 API 访问控制等场景，支持为角色绑定腾讯云网关策略。

createRole

1. 接口描述

接口功能：创建用户角色

接口声明：app.permission.createRole(options): Promise<CreateRoleResp>

2. 输入参数

字段	必填	类型	说明
roleName	是	String	角色名称
roleIdentity	是	String	角色唯一标识符（英文，创建后不可修改）
description	否	String	角色描述
memberUids	否	`string[]`	初始成员 UID 列表
policies	否	`PermissionPolicyItem[]`	绑定的权限策略列表

PermissionPolicyItem

当前 ResourceType 仅支持 gateway。

字段	必填	类型	说明
ResourceType	是	String	资源类型，当前仅支持 `gateway`
Resource	是	String	资源标识符。传预设策略时填预设策略字符串；传自定义策略时与 `GatewayPolicyCode` 保持一致
Effect	是	String	效果：`allow`（允许）或 `deny`（拒绝）
GatewayPolicyCode	是	String	网关策略编码。传预设策略时填预设策略字符串；传自定义策略时与 `Resource` 保持一致
GatewayPolicyName	否	String	网关策略名称
GatewayPolicyDescription	否	String	网关策略描述
GatewayPolicyExpression	否	String	网关策略表达式 JSON 字符串

3. 返回结果

字段	类型	说明
RequestId	String	请求唯一标识
Data.RoleId	String	创建的角色 ID
Data.MemberUids	`string[]`	添加的成员 UID 列表
Data.Policies	`PermissionPolicyItem[]`	绑定的策略列表

4. 示例代码

import CloudBase from '@cloudbase/manager-node'

const app = CloudBase.init({
  secretId: 'Your SecretId',
  secretKey: 'Your SecretKey',
  envId: 'Your envId'
})

async function test() {
  const result = await app.permission.createRole({
    roleName: '只读运营',
    roleIdentity: 'read-only-operator',
    description: '运营人员只读角色',
    policies: [
      { ResourceType: 'gateway', Resource: 'FunctionsAccess', Effect: 'allow', GatewayPolicyCode: 'FunctionsAccess' }
    ]
  })
  console.log('创建角色 ID:', result.RoleId)
}

test()

describeRoleList

1. 接口描述

接口功能：查询角色列表，支持按角色 ID、标识、名称筛选

接口声明：app.permission.describeRoleList(options?): Promise<DescribeRoleListResp>

2. 输入参数

字段	必填	类型	说明
pageNumber	否	Number	页码，默认 1
pageSize	否	Number	每页条数，默认 20
roleId	否	String	按角色 ID 精确查询
roleIdentity	否	String	按角色唯一标识查询
roleName	否	String	按角色名称模糊查询
loadDetails	否	Boolean	是否返回成员和策略详情，默认 false

3. 返回结果

字段	类型	说明
RequestId	String	请求唯一标识
Data.TotalCount	Number	系统角色总数
Data.CustomTotalCount	Number	自定义角色总数
Data.SystemRoles	`RoleItem[]`	系统预置角色列表
Data.CustomRoles	`RoleItem[]`	自定义角色列表

RoleItem

字段	类型	说明
RoleId	String	角色 ID
RoleIdentity	String	角色唯一标识
RoleName	String	角色名称
RoleType	String	类型：`system` / `custom`
Description	String	角色描述
Members	`MemberInfo[]`	成员列表（loadDetails=true 时返回）
Policies	`PermissionPolicyItem[]`	策略列表（loadDetails=true 时返回）

modifyRole

1. 接口描述

接口功能：修改角色信息，支持更新名称、描述、成员、策略

接口声明：app.permission.modifyRole(options): Promise<ModifyRoleResp>

2. 输入参数

字段	必填	类型	说明
roleId	是	String	要修改的角色 ID
roleName	否	String	新的角色名称
description	否	String	新的角色描述
addMemberUids	否	`string[]`	新增成员 UID 列表
removeMemberUids	否	`string[]`	移除成员 UID 列表
addPolicies	否	`PermissionPolicyItem[]`	新增策略列表
removePolicies	否	`PermissionPolicyItem[]`	移除策略列表

3. 返回结果

字段	类型	说明
RequestId	String	请求唯一标识
Data.Success	Boolean	是否修改成功
Data.AddedMemberUids	`string[]`	实际添加的成员
Data.RemovedMemberUids	`string[]`	实际移除的成员
Data.AddedPolicies	`PermissionPolicyItem[]`	实际添加的策略
Data.RemovedPolicies	`PermissionPolicyItem[]`	实际移除的策略

deleteRoles

1. 接口描述

接口功能：批量删除角色

接口声明：app.permission.deleteRoles(options): Promise<DeleteRolesResp>

2. 输入参数

字段	必填	类型	说明
roleIds	是	`string[]`	要删除的角色 ID 列表

3. 返回结果

字段	类型	说明
RequestId	String	请求唯一标识
Data.SuccessCount	Number	删除成功数量
Data.FailedCount	Number	删除失败数量

4. 示例代码

import CloudBase from '@cloudbase/manager-node'

const app = CloudBase.init({
  secretId: 'Your SecretId',
  secretKey: 'Your SecretKey',
  envId: 'Your envId'
})

async function test() {
  // 查询所有自定义角色
  const { CustomRoles } = await app.permission.describeRoleList({
    loadDetails: true
  })
  console.log('自定义角色数量：', CustomRoles?.length)
  
  // 修改角色：添加新成员
  await app.permission.modifyRole({
    roleId: 'role-123',
    addMemberUids: ['uid-456'],
    roleName: '运营管理员（更新）'
  })

  // 删除角色
  const res = await app.permission.deleteRoles({
    roleIds: ['role-123', 'role-456']
  })
  console.log(`删除成功 ${res.SuccessCount} 个角色`)
}

test()

modifyResourcePermission

已废弃

此接口已废弃，网关鉴权策略已由 OPA 接管，请使用 modifyEnvAuthzConfig 替代。

1. 接口描述

接口功能：设置指定资源的访问权限

接口声明：app.permission.modifyResourcePermission(options): Promise<Object>

2. 输入参数

字段	必填	类型	说明
resourceType	是	`PermissionResourceType`	资源类型，取值：`function` / `storage` / `table` / `collection`
resource	否	String	资源名称（如函数名、集合名）。当 `resourceType` 为 `function` 时可不传
permission	是	`BasePermission`	权限类型（见下表）
securityRule	否	String	自定义安全规则 JSON 字符串，仅 `permission = 'CUSTOM'` 时传入

权限类型（BasePermission）

table / collection

值	说明
`READONLY`	读取全部数据，修改本人数据
`PRIVATE`	读取和修改本人数据
`ADMINWRITE`	读取全部数据，不可修改数据
`ADMINONLY`	无权限
`CUSTOM`	自定义安全规则（仅 `collection` 支持）

storage

值	说明
`READONLY`	所有用户可读，仅创建者和管理员可写
`PRIVATE`	仅创建者及管理员可读写
`ADMINWRITE`	所有用户可读，仅管理员可写
`ADMINONLY`	仅管理员可读写
`CUSTOM`	自定义安全规则

function

值	说明
`CUSTOM`	自定义安全规则

3. 返回结果

字段	类型	说明
RequestId	String	请求唯一标识
Data.Success	Boolean	是否设置成功

4. 示例代码

import CloudBase from '@cloudbase/manager-node'

const app = CloudBase.init({
  secretId: 'Your SecretId',
  secretKey: 'Your SecretKey',
  envId: 'Your envId'
})

async function test() {
  // 设置数据库集合为仅管理员可读写
  await app.permission.modifyResourcePermission({
    resourceType: 'collection',
    resource: 'my-collection',
    permission: 'ADMINONLY'
  })

  // 设置自定义安全规则
  await app.permission.modifyResourcePermission({
    resourceType: 'collection',
    resource: 'user-data',
    permission: 'CUSTOM',
    securityRule: JSON.stringify({
      read: 'auth.uid == doc.uid',
      write: 'auth.uid == doc.uid'
    })
  })
}

test()

describeResourcePermission

已废弃

此接口已废弃，网关鉴权策略已由 OPA 接管，请使用 describeResourcePolicyList 或 describeEnvAuthzConfig 替代。

1. 接口描述

接口功能：查询指定资源的当前访问权限

接口声明：app.permission.describeResourcePermission(options): Promise<Object>

2. 输入参数

字段	必填	类型	说明
resourceType	是	`PermissionResourceType`	资源类型：`function` / `storage` / `table` / `collection`
resources	否	`string[]`	资源名称列表，云函数不传或传空数组、云存储传存储桶名、数据库表传表名，不能超过100条。

3. 返回结果

字段	类型	说明
RequestId	String	请求唯一标识
Data.TotalCount	Number	总条数
Data.PermissionList	`ResourcePermission[]`	权限列表

ResourcePermission

字段	类型	说明
ResourceType	String	资源类型
Resource	String	资源名称
Permission	String	当前权限值
SecurityRule	String	自定义安全规则（CUSTOM 时有值）

describeResourcePolicyList​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

describeEnvAuthzConfig​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

modifyEnvAuthzConfig​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

createRole​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

describeRoleList​

1. 接口描述​

2. 输入参数​

3. 返回结果​

modifyRole​

1. 接口描述​

2. 输入参数​

3. 返回结果​

deleteRoles​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

modifyResourcePermission​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

describeResourcePermission​

1. 接口描述​

2. 输入参数​

3. 返回结果​

describeResourcePolicyList

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码

describeEnvAuthzConfig

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码

modifyEnvAuthzConfig

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码

createRole

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码

describeRoleList

1. 接口描述

2. 输入参数

3. 返回结果

modifyRole

1. 接口描述

2. 输入参数

3. 返回结果

deleteRoles

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码

modifyResourcePermission

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码

describeResourcePermission

1. 接口描述

2. 输入参数

3. 返回结果