Permission Management

Version Note

Resource permission management and role management are supported since v5.0.0, policy management is supported since v5.5.5.

@cloudbase/manager-node provides PermissionService, accessible via app.permission, and supports three major features:

Policy Management: query gateway authentication policy list, retrieve and set OPA Rego authentication policies (v5.5.5+)
Role Management: create/query/modify/delete user roles (RBAC), and bind gateway access policies to roles
Resource Permission Management: set and query access permissions for SCF, databases, storage, and other resources (deprecated, please use Policy Management)

OPA Authentication Policy Concepts

Policy management is based on the OPA Rego policy engine. For how OPA authentication policies work, the input context structure, the allow / deny decision matrix, and real-world cases, see OPA Authentication Policy Introduction. For the steps and policy translation reference to migrate from legacy gateway authentication to OPA Rego, see Migration Guide.

describeResourcePolicyList

1. Interface Description

Function: Query the list of gateway authentication policies

Declaration: app.permission.describeResourcePolicyList(options?): Promise<Object>

Version Note

This interface has been added since v5.5.5.

2. Input Parameters

Field	Required	Type	Description
resourceType	No	String	Filter by resource type, available value: `policy`

3. Return Result

Field	Type	Description
RequestId	String	Request unique ID
Data.PolicyList	`ResourcePolicyItem[]`	Policy list
Data.Total	String	Total policy count

ResourcePolicyItem

Field	Type	Description
PolicyId	String	Policy ID
ResourceType	String	Resource type
ResourceId	String	Resource ID
ResourceTitle	String	Resource title
ResourceName	String	Resource name
Effect	String	Effect: `allow`/`deny`
IsAccess	Boolean	Is accessible
RoleId	String	Role ID
RoleIdentity	String	Role identity
RoleName	String	Role name
SafeRule	String	Safe rule

4. Example Code

import CloudBase from '@cloudbase/manager-node'

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

async function test() {
  // Query all policies
  const result = await app.permission.describeResourcePolicyList()
  console.log('Total policies:', result.Data.Total)

  // Filter by resource type
  const filtered = await app.permission.describeResourcePolicyList({
    resourceType: 'policy'
  })
  console.log('Policy list:', filtered.Data.PolicyList)
}

test()

describeEnvAuthzConfig

1. Interface Description

Function: Retrieve authentication policy content

Declaration: app.permission.describeEnvAuthzConfig(options): Promise<Object>

Version Note

This interface has been added since v5.5.5.

2. Input Parameters

Field	Required	Type	Description
key	Yes	String	Policy key name. `authz.user.rego` for user policy, `authz.platform.extension.rego` for platform extension policy

3. Return Result

Field	Type	Description
RequestId	String	Request unique ID
Item.Key	String	Policy key name
Item.Value	String	Policy content

4. Example Code

import CloudBase from '@cloudbase/manager-node'

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

async function test() {
  // Retrieve user policy
  const userPolicy = await app.permission.describeEnvAuthzConfig({
    key: 'authz.user.rego'
  })
  console.log('User policy:', userPolicy.Item.Value)

  // Retrieve platform extension policy
  const extPolicy = await app.permission.describeEnvAuthzConfig({
    key: 'authz.platform.extension.rego'
  })
  console.log('Platform extension policy:', extPolicy.Item.Value)
}

test()

modifyEnvAuthzConfig

1. Interface Description

Function: Set authentication policy

Declaration: app.permission.modifyEnvAuthzConfig(options): Promise<Object>

Version Note

This interface has been added since v5.5.5.

Important

Once a Rego policy is set, the legacy gateway authentication will be invalidated. Please confirm the policy content is correct before executing.

2. Input Parameters

Field	Required	Type	Description
key	Yes	String	Policy key name, fixed as `authz.user.rego`
value	Yes	String	Rego policy content, must start with `package authz.user`

For details on input fields, please refer to OPA Authentication Policy Introduction.

3. Return Result

Field	Type	Description
RequestId	String	Request unique ID
AffectedRows	Number	Affected rows

4. Example Code

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 anonymous users to access cloud functions
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('Affected rows:', result.AffectedRows)
}

test()

Role management is applicable to scenarios such as multi-person collaboration within enterprises and gateway API access control, supporting the binding of Tencent Cloud gateway policies to roles.

createRole

1. API Description

API feature: Create user role

API declaration: app.permission.createRole(options): Promise<CreateRoleResp>

2. Input Parameters

Field	Required	Type	Description
roleName	Required	String	Role name
roleIdentity	Required	String	Unique identifier for the role (in English, cannot be modified after creation)
description	No	String	Role description
memberUids	No	`string[]`	Initial member UID list
policies	No	`PermissionPolicyItem[]`	List of bound permission policies

PermissionPolicyItem

Currently ResourceType only supports gateway.

Field	Required	Type	Description
ResourceType	Required	String	Resource type. Currently only supports `gateway`
Resource	Required	String	Resource identifier. Fill in the preset policy string when passing a preset policy; must match `GatewayPolicyCode` when passing a custom policy
Effect	Required	String	Effect: `allow` (is allowed) or `deny` (is denied)
GatewayPolicyCode	Required	String	Gateway policy code. Fill in the preset policy string when passing a preset policy; must match `Resource` when passing a custom policy
GatewayPolicyName	No	String	Gateway policy name
GatewayPolicyDescription	No	String	Gateway policy description
GatewayPolicyExpression	No	String	Gateway policy expression JSON string

3. Return Results

Field	Type	Description
RequestId	String	Unique identifier of the request
Data.RoleId	String	Created Role ID
Data.MemberUids	`string[]`	Added member UID list
Data.Policies	`PermissionPolicyItem[]`	Bound policy list

4. Sample Code

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: 'Read-only Operations',
    roleIdentity: 'read-only-operator',
    description: 'Read-only Operations Role',
    policies: [
      { ResourceType: 'gateway', Resource: 'FunctionsAccess', Effect: 'allow', GatewayPolicyCode: 'FunctionsAccess' }
    ]
  })
  console.log('Created Role ID:', result.RoleId)
}

test()

describeRoleList

1. API Description

API feature: List roles, supporting filtering by role ID, identifier, and name.

API declaration: app.permission.describeRoleList(options?): Promise<DescribeRoleListResp>

2. Input Parameters

Field	Required	Type	Description
pageNumber	No	Number	Page number, default: 1
pageSize	No	Number	Number of items per page, default: 20
roleId	No	String	Exact match by role ID
roleIdentity	No	String	Query by role unique identifier
roleName	No	String	Query by role name with fuzzy search
loadDetails	No	Boolean	Whether to return member and policy details, default false

3. Return Results

Field	Type	Description
RequestId	String	Unique identifier of the request
Data.TotalCount	Number	Total system roles
Data.CustomTotalCount	Number	Total custom roles
Data.SystemRoles	`RoleItem[]`	System predefined role list
Data.CustomRoles	`RoleItem[]`	Custom role list

RoleItem

Field	Type	Description
RoleId	String	Role ID
RoleIdentity	String	Unique identifier for the role
RoleName	String	Role name
RoleType	String	Type: `system` / `custom`
Description	String	Role description
Members	`MemberInfo[]`	Member list (returned when loadDetails=true)
Policies	`PermissionPolicyItem[]`	Policy list (returned when loadDetails=true)

modifyRole

1. API Description

API feature: Modify role information, supporting updates to name, description, members, and policies.

API declaration: app.permission.modifyRole(options): Promise<ModifyRoleResp>

2. Input Parameters

Field	Required	Type	Description
roleId	Required	String	Role ID to be modified
roleName	No	String	New role name
description	No	String	New role description
addMemberUids	No	`string[]`	Added member UID list
removeMemberUids	No	`string[]`	Member UID list to remove
addPolicies	No	`PermissionPolicyItem[]`	Added policies list
removePolicies	No	`PermissionPolicyItem[]`	Policies list to remove

3. Return Results

Field	Type	Description
RequestId	String	Unique identifier of the request
Data.Success	Boolean	whether the modification was successful
Data.AddedMemberUids	`string[]`	Added members
Data.RemovedMemberUids	`string[]`	Removed members
Data.AddedPolicies	`PermissionPolicyItem[]`	Added policies
Data.RemovedPolicies	`PermissionPolicyItem[]`	Removed policies

deleteRoles

1. API Description

API feature: Batch delete roles

API declaration: app.permission.deleteRoles(options): Promise<DeleteRolesResp>

2. Input Parameters

Field	Required	Type	Description
roleIds	Required	`string[]`	List of role IDs to be deleted

3. Return Results

Field	Type	Description
RequestId	String	Unique identifier of the request
Data.SuccessCount	Number	Successful deletion count
Data.FailedCount	Number	Failed deletion count

4. Sample Code

import CloudBase from '@cloudbase/manager-node'

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

async function test() {
  // Query all custom roles
  const { CustomRoles } = await app.permission.describeRoleList({
    loadDetails: true
  })
  console.log('Custom roles count:', CustomRoles?.length)
  
  // Modify role: Add new member
  await app.permission.modifyRole({
    roleId: 'role-123',
    addMemberUids: ['uid-456'],
    roleName: 'Operations Administrator (Updated)'
  })

  // Delete role
  const res = await app.permission.deleteRoles({
    roleIds: ['role-123', 'role-456']
  })
  console.log(`Successfully deleted ${res.SuccessCount} roles`)
}

test()

modifyResourcePermission

Deprecated

This interface is deprecated. Gateway authentication policies are now managed by OPA. Please use modifyEnvAuthzConfig instead.

1. API Description

API feature: Set access permissions for specified resources.

API declaration: app.permission.modifyResourcePermission(options): Promise<Object>

2. Input Parameters

Field	Required	Type	Description
resourceType	Yes	`PermissionResourceType`	Resource type. Valid values: `function` / `storage` / `table` / `collection`
resource	No	String	Resource name (e.g., function name, collection name). Can be omitted when `resourceType` is `function`
permission	Required	`BasePermission`	Permission type (See table below)
securityRule	No	String	Custom security rule JSON string. Only required when `permission = 'CUSTOM'`

Permission Type (BasePermission)

table / collection

Value	Description
`READONLY`	Read all data, modify own data
`PRIVATE`	Read and modify own data
`ADMINWRITE`	Read all data, cannot modify data
`ADMINONLY`	No permissions
`CUSTOM`	Custom security rules (Only supported for `collection`)

storage

Value	Description
`READONLY`	Readable by all users, writable only by the creator and administrators
`PRIVATE`	Readable and writable only by the creator and administrators
`ADMINWRITE`	Readable by all users, writable only by administrators
`ADMINONLY`	Readable and writable only by administrators
`CUSTOM`	Custom security rules

function

Value	Description
`CUSTOM`	Custom security rules

3. Return Results

Field	Type	Description
RequestId	String	Unique identifier of the request
Data.Success	Boolean	whether the setting was successful

4. Sample Code

import CloudBase from '@cloudbase/manager-node'

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

async function test() {
  // Set the database collection to be readable and writable only by administrators
  await app.permission.modifyResourcePermission({
    resourceType: 'collection',
    resource: 'my-collection',
    permission: 'ADMINONLY'
  })

  // Set custom security rules
  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

Deprecated

This interface is deprecated. Gateway authentication policies are now managed by OPA. Please use describeResourcePolicyList or describeEnvAuthzConfig instead.

1. API Description

API feature: Query the current access permissions of specified resources.

API declaration: app.permission.describeResourcePermission(options): Promise<Object>

2. Input Parameters

Field	Required	Type	Description
resourceType	Yes	`PermissionResourceType`	Resource type: `function` / `storage` / `table` / `collection`
resources	No	`string[]`	List of resource names. For SCF, pass an empty array or do not pass this parameter; for cloud storage, pass the bucket name; for database tables, pass the table name. The list cannot exceed 100 entries.

3. Return Results

Field	Type	Description
RequestId	String	Unique identifier of the request
Data.TotalCount	Number	Total count
Data.PermissionList	`ResourcePermission[]`	Permission list

ResourcePermission

Field	Type	Description
ResourceType	String	Resource type
Resource	String	Resource name
Permission	String	Current permission value
SecurityRule	String	Custom security rule (present when permission is CUSTOM)

describeResourcePolicyList​

1. Interface Description​

2. Input Parameters​

3. Return Result​

4. Example Code​

describeEnvAuthzConfig​

1. Interface Description​

2. Input Parameters​

3. Return Result​

4. Example Code​

modifyEnvAuthzConfig​

1. Interface Description​

2. Input Parameters​

3. Return Result​

4. Example Code​

createRole​

1. API Description​

2. Input Parameters​

3. Return Results​

4. Sample Code​

describeRoleList​

1. API Description​

2. Input Parameters​

3. Return Results​

modifyRole​

1. API Description​

2. Input Parameters​

3. Return Results​

deleteRoles​

1. API Description​

2. Input Parameters​

3. Return Results​

4. Sample Code​

modifyResourcePermission​

1. API Description​

2. Input Parameters​

3. Return Results​

4. Sample Code​

describeResourcePermission​

1. API Description​

2. Input Parameters​

3. Return Results​

describeResourcePolicyList

1. Interface Description

2. Input Parameters

3. Return Result

4. Example Code

describeEnvAuthzConfig

1. Interface Description

2. Input Parameters

3. Return Result

4. Example Code

modifyEnvAuthzConfig

1. Interface Description

2. Input Parameters

3. Return Result

4. Example Code

createRole

1. API Description

2. Input Parameters

3. Return Results

4. Sample Code

describeRoleList

1. API Description

2. Input Parameters

3. Return Results

modifyRole

1. API Description

2. Input Parameters

3. Return Results

deleteRoles

1. API Description

2. Input Parameters

3. Return Results

4. Sample Code

modifyResourcePermission

1. API Description

2. Input Parameters

3. Return Results

4. Sample Code

describeResourcePermission

1. API Description

2. Input Parameters

3. Return Results