¶ 管理资源与权限

更新时间: 2021-05-18 04:10:47

Authing 基于 ABAC（Attribute Base Access Control，基于属性的权限控制）构建权限模型，

可以和 RBAC （Role Based Access Control，基于角色的访问控制）结合，实现非常灵活、精细化的权限控制。

此模块将此模型抽象成了两个方法: allow, isAllowed。

你可以通过以下方式使用此模块：

import { ManagementClient } from 'authing-js-sdk'
const managementClient = new ManagementClient({
  userPoolId: 'YOUR_USERPOOL_ID',
  secret: 'YOUR_USERPOOL_SECRET',
})
managementClient.acl.allow // 允许某个用户对某个资源进行某个操作
managementClient.acl.isAllowed // 判断某个用户是否对某个资源有某个操作权限

¶ 创建权限分组

managementClient.acl.createNamespace(code, name, description)

创建权限分组

¶ 参数

code <string> 权限分组唯一标识符
name <string> 权限分组名
description <string> 可选，权限分组描述

¶ 示例

managementClient.acl.createNamespace(
  'testNamesapce',
  'Test Namcepace',
  'This is a Test Namespace'
)

¶ 返回值

Promise<DeepPartial<Namespace>>

¶ 示例数据

{
  "appId": null,
  "appName": null,
  "name": "Test Namcepace",
  "code": "testNamesapce",
  "description": "This is a Test Namespace",
  "status": 1,
  "id": 38
}

¶ 获取权限分组列表

managementClient.acl.listNamespaces(page, limit)

获取权限分组列表

¶ 参数

page <number> 页码，默认为 1
limit <number> 每页个数，默认为 10

¶ 示例

managementClient.acl.listNamespace(1, 10)

¶ 返回值

Promise<DeepPartial<{list: Namespace[],totalCount: number}>>

¶ 示例数据

{
  "list": [
    {
      "appId": null,
      "appName": null,
      "name": "Test Namcepace",
      "code": "testNamesapce",
      "description": "This is a Test Namespace",
      "status": 1,
      "id": 38
    }
  ],
  "totalCount": 1
}

¶ 更新权限分组

managementClient.acl.updateNamespace(code, updates)

更新权限分组

¶ 参数

code <number> 权限分组 code
updates <object> 需要更新的数据
updates.code <string> 可选，权限分组唯一标识符
updates.name <string> 可选，权限分组名称
updates.description <string> 可选，权限分组描述

¶ 示例

managementClient.acl.updateNamespace('testNamesapce', {
  name: 'A New Name',
})

¶ 返回值

Promise<DeepPartial<Namespace>>

¶ 示例数据

{
  "id": 38,
  "appId": null,
  "appName": null,
  "name": "Test Namcepace",
  "code": "testNamesapce",
  "description": "A New Name",
  "status": 1
}

¶ 删除权限分组

managementClient().acl.deleteNamespace(code)

删除权限分组

¶ 参数

code <number> 权限分组 CODE

¶ 示例

managementClient.acl.deleteNamespace('testNamesapce')

¶ 返回值

Promise<boolean>

¶ 获取资源列表

AclManagementClient().listResources(options)

根据筛选条件，查询用户池下的资源列表。

¶ 参数

options <object> 筛选条件对象
options.namespace <string> 权限分组命名空间
options.type <string> 资源类型，可选值为 DATA、API、MENU、UI、BUTTON
options.page <string> 分页，获取第几页，默认从 1 开始
options.limit <string> 每页条目数量

¶ 示例

const res = await managementClient.acl.listResources({
  namespace: '600a8f4e37708b363024a3ca',
  page: 1,
  limit: 10,
})

¶ 返回数据

{
  "list": [
    {
      "id": "60646ed1c7a558f935c6d49c",
      "createdAt": "2021-03-31T12:45:05.175Z",
      "updatedAt": "2021-03-31T12:45:05.175Z",
      "userPoolId": "600a8f29cead8fc0127f9da6",
      "code": "pihh4j7j4ehh",
      "actions": [
        {
          "name": "book:write",
          "description": "图书写入操作"
        }
      ],
      "type": "DATA",
      "description": "chair",
      "namespaceId": 22997,
      "apiIdentifier": null,
      "namespace": "600a8f4e37708b363024a3ca"
    }
  ],
  "totalCount": 1
}

¶ 创建资源

AclManagementClient().createResource(options)

创建一个资源。

¶ 参数

options <object> 资源信息对象
options.code <string> 资源标识符
options.namespace <string> 权限分组命名空间
options.type <string> 资源类型，可选值为 DATA、API、MENU、UI、BUTTON
options.actions <Array<{ name: string, description: string }>> 资源操作对象数组。其中 name 为操作名称，填写一个动词，description 为操作描述，填写描述信息
options.description <string> 资源描述信息

¶ 示例

const res = await managementClient.acl.createResource({
  code: 'book',
  type: 'DATA',
  description: 'book',
  actions: [
    {
      name: 'book:write',
      description: '图书写入操作',
    },
  ],
  namespace: '600a8f4e37708b363024a3ca',
})

¶ 返回数据

{
  "userPoolId": "600a8f29cead8fc0127f9da6",
  "code": "book",
  "actions": [
    {
      "name": "book:write",
      "description": "图书写入操作"
    }
  ],
  "type": "DATA",
  "description": "book",
  "namespaceId": 22997,
  "createdAt": "2021-04-06T11:49:07.656Z",
  "updatedAt": "2021-04-06T11:49:07.656Z",
  "id": "606c4ab3d7fb66a8e1517132",
  "apiIdentifier": null
}

¶ 更新资源

AclManagementClient().updateResource(code, options)

更新一个资源。

¶ 参数

code <string> 资源标识符
options <object> 资源信息对象
options.namespace <string> 资源所在的权限分组标识
options.type <string> 资源类型，可选值为 DATA、API、MENU、UI、BUTTON
options.actions <Array<{ name: string, description: string }>> 资源操作对象数组。其中 name 为操作名称，填写一个动词，description 为操作描述，填写描述信息
options.description <string> 资源描述信息

¶ 示例

const updated = await managementClient.acl.updateResource(code, {
  description: '新的描述',
  type: 'DATA',
  actions: [
    { name: 'write', description: '图书写入操作2' },
    { name: 'read', description: '图书读取操作2' },
  ],
  namespace: '600a8f4e37708b363024a3ca',
})

¶ 返回数据

{
  "id": "606c4ab3d7fb66a8e1517132",
  "createdAt": "2021-04-06T11:49:07.656Z",
  "updatedAt": "2021-04-06T11:59:26.879Z",
  "userPoolId": "600a8f29cead8fc0127f9da6",
  "code": "book",
  "actions": [
    {
      "name": "book:write",
      "description": "图书写入操作2"
    },
    {
      "name": "book:read",
      "description": "图书读取操作2"
    }
  ],
  "type": "DATA",
  "description": "新的描述",
  "namespaceId": 22997,
  "apiIdentifier": null
}

¶ 删除资源

AclManagementClient().deleteResource(code, namespace)

¶ 参数

code <string> 资源标识符
namespace <string> 资源所在的权限分组标识

¶ 示例

let deleted = await managementClient.acl.deleteResource(
  code,
  '600a8f4e37708b363024a3ca'
)

deleted === true

¶ 返回数据

true

¶ 允许某个用户对某个资源进行某个操作

AclManagementClient().allow(userId, action, resource, namespace)

允许某个用户对某个资源进行某个操作。

¶ 参数

userId <string> 用户 ID
action <string> 操作名称，推荐使用 <resourceType>:<actionName> 的格式，如 books:edit, books:list
resource <string> 资源名称, 必须为 <resourceType>:<resourceId> 格式或者为 _, 如 _,books:123,books:\*
namespace <string> 权限分组的 code，详情请见使用权限分组管理权限资源；

¶ 示例

managementClient.acl.allow('USERID1', 'books:123', 'books:read')
managementClient.acl.isAllowed('USERID1', 'books:123', 'books:read') // true
managementClient.acl.isAllowed('USERID1', 'books:123', 'books:edit') // false

managementClient.acl.allow('USERID2', 'books:*', 'books:*')
managementClient.acl.isAllowed('USERID2', 'books:123', 'books:read') // true
managementClient.acl.isAllowed('USERID2', 'books:124', 'books:edit') // true

¶ 返回值

Promise<CommonMessage>

¶ 判断某个用户是否对某个资源有某个操作权限

AclManagementClient().isAllowed(userId, action, resource, namesapce)

判断某个用户是否对某个资源有某个操作权限

¶ 参数

userId <string> 用户 ID
action <string> 操作名称，推荐使用 <resourceType>:<actionName> 的格式，如 books:edit, books:list
resource <string> 资源名称, 必须为 <resourceType>:<resourceId> 格式或者为 _, 如 _,books:123,books:\*
options: 其他选项，可选
- options.namespace: 资源所属权限分组 code, 详情请见使用权限分组管理权限资源;

¶ 示例

managementClient.acl.isAllowed('USERID', 'books:*', 'books:edit', {
  namespace: 'default'
})

¶ 返回值

Promise<boolean> 是否具备操作权限

¶ 获取用户被授权的所有资源列表

UsersManagementClient.listAuthorizedResources(userId, namespace, { resourceType: ResourceType.MENU, })

获取一个用户被授权的所有资源，用户被授权的所有资源里面包括从角色、分组、组织机构继承的资源。

¶ 参数

userId <string> 用户 ID；
namespace <string> 权限分组的 code，详情请见使用权限分组管理权限资源；
resourceType <string> 可选，资源类型，默认会返回所有有权限的资源，现有资源类型如下：
- DATA: 数据类型；
- API: API 类型数据；
- MENU: 菜单类型数据；
- BUTTON: 按钮类型数据。

¶ 示例

import { ResourceType } from 'authing-js-sdk'

managementClient.users.listAuthorizedResources('USERID', 'NAMESPACE_CODE', {
  resourceType: ResourceType.MENU,
})

¶ 示例数据

type 为资源类型；
code: 资源描述符，如果是 DATA 类型资源，格式为 resourceType:resourceId，如 books:* 表示所有书籍，books:1 表示 ID 为 1 的书籍。
actions: 用户被授权对该资源的操作。

{
  "totalCount": 12,
  "list": [
    {
      "code": "menu_a",
      "type": "MENU"
    },
    {
      "code": "menu_b",
      "type": "MENU"
    },
    {
      "code": "books:1",
      "type": "DATA",
      "actions": ["books:delete", "books:update"]
    }
  ]
}

¶ 获取角色被授权的所有资源列表

RolesManagementClient.listAuthorizedResources(code, namespace, { resourceType: ResourceType.MENU, })

获取一个角色被授权的所有资源。

¶ 参数

code <string> 角色 code；
namespace <string> 权限分组的 code，详情请见使用权限分组管理权限资源；
resourceType <string> 可选，资源类型，默认会返回所有有权限的资源，现有资源类型如下：
- DATA: 数据类型；
- API: API 类型数据；
- MENU: 菜单类型数据；
- BUTTON: 按钮类型数据。

¶ 示例

import { ResourceType } from 'authing-js-sdk'

managementClient.roles.listAuthorizedResources('ROLE_CODE', 'NAMESPACE_CODE', {
  resourceType: ResourceType.MENU,
})

¶ 示例数据

type 为资源类型；
code: 资源描述符，如果是 DATA 类型资源，格式为 resourceType:resourceId，如 books:* 表示所有书籍，books:1 表示 ID 为 1 的书籍。
actions: 用户被授权对该资源的操作。

{
  "totalCount": 12,
  "list": [
    {
      "code": "menu_a",
      "type": "MENU"
    },
    {
      "code": "menu_b",
      "type": "MENU"
    },
    {
      "code": "books:1",
      "type": "DATA",
      "actions": ["books:delete", "books:update"]
    }
  ]
}

¶ 获取分组被授权的所有资源列表

GroupsManagementClient.listAuthorizedResources(code, namespace, { resourceType: ResourceType.MENU, })

获取一个分组被授权的所有资源。

¶ 参数

code <string> 分组 code；
namespace <string> 权限分组的 code，详情请见使用权限分组管理权限资源；
resourceType <string> 可选，资源类型，默认会返回所有有权限的资源，现有资源类型如下：
- DATA: 数据类型；
- API: API 类型数据；
- MENU: 菜单类型数据；
- BUTTON: 按钮类型数据。

¶ 示例

import { ResourceType } from 'authing-js-sdk'

managementClient.groups.listAuthorizedResources(
  'GROUP_CODE',
  'NAMESPACE_CODE',
  {
    resourceType: ResourceType.MENU,
  }
)

¶ 示例数据

type 为资源类型；
code: 资源描述符，如果是 DATA 类型资源，格式为 resourceType:resourceId，如 books:* 表示所有书籍，books:1 表示 ID 为 1 的书籍。
actions: 用户被授权对该资源的操作。

{
  "totalCount": 12,
  "list": [
    {
      "code": "menu_a",
      "type": "MENU"
    },
    {
      "code": "menu_b",
      "type": "MENU"
    },
    {
      "code": "books:1",
      "type": "DATA",
      "actions": ["books:delete", "books:update"]
    }
  ]
}

¶ 获取部门被授权的所有资源列表

OrgManagementClient.listAuthorizedResourcesByNodeId(nodeId, namespace, { resourceType: ResourceType.MENU, })

获取一个部门被授权的所有资源。

¶ 参数

nodeId <string> 部门 id；
namespace <string> 权限分组的 code，详情请见使用权限分组管理权限资源
resourceType <string> 可选，资源类型，默认会返回所有有权限的资源，现有资源类型如下：
- DATA: 数据类型；
- API: API 类型数据；
- MENU: 菜单类型数据；
- BUTTON: 按钮类型数据。

¶ 示例

import { ResourceType } from 'authing-js-sdk'

managementClient.org.listAuthorizedResourcesByNodeId(
  'NODE_ID',
  'NAMESPACE_CODE',
  {
    resourceType: ResourceType.MENU,
  }
)

¶ 示例数据

type 为资源类型；
code: 资源描述符，如果是 DATA 类型资源，格式为 resourceType:resourceId，如 books:* 表示所有书籍，books:1 表示 ID 为 1 的书籍。
actions: 用户被授权对该资源的操作。

{
  "totalCount": 12,
  "list": [
    {
      "code": "menu_a",
      "type": "MENU"
    },
    {
      "code": "menu_b",
      "type": "MENU"
    },
    {
      "code": "books:1",
      "type": "DATA",
      "actions": ["books:delete", "books:update"]
    }
  ]
}

¶ 将一个（类）资源批量授权给用户、角色、分组、组织机构

AclManagementClient.authorizeResource(params)

将一个（类）资源授权给用户、角色、分组、组织机构，且可以分别指定不同的操作权限。

¶ 参数

namespace: 权限分组 code；
resourceType: 资源类型，现有资源类型如下：
- DATA: 数据类型；
- API: API 类型数据；
- MENU: 菜单类型数据；
- BUTTON: 按钮类型数据。；
resource: 资源，如一类资源可以表示为 order，某一个资源可以表示为 order:123；
opts: 一个数组
- targetType: 授权对象类型，如 USER, ROLE, GROUP, ORG
- targetIdentifier: 授权对象唯一标志符，如用户 ID、角色 code、分组 code、组织机构 ID；
- actions: 授权的操作列表，可选。MENU、Button 类型数据不需要指定 actions。

¶ 示例

将菜单类型数据 menuA 授权给用户 USER_ID 和部门 DEPARTMENT_ID：

import { ResourceType, PolicyAssignmentTargetType } from 'authing-js-sdk'

await managementClient.acl.authorizeResource({
  namespace: 'default',
  resourceType: ResourceType.Menu,
  resource: 'menuA',
  opts: [
    {
      targetType: PolicyAssignmentTargetType.User,
      targetIdentifier: 'USER_ID',
    }.
    {
      targetType: PolicyAssignmentTargetType.Org,
      targetIdentifier: 'DEPARTMENT_ID'
    }
  ]
});

将服务器（ESC）1 的开机权限授予角色 A，开机、关机权限授权给角色 B：

import { ResourceType, PolicyAssignmentTargetType } from 'authing-js-sdk'

await managementClient.acl.authorizeResource({
  namespace: 'default',
  resourceType: ResourceType.Data,
  resource: 'ecs:1',
  opts: [
    {
      targetType: PolicyAssignmentTargetType.Role,
      targetIdentifier: 'A',
      actions: [
        'ecs:Start'
      ]
    }.
    {
      targetType: PolicyAssignmentTargetType.Role,
      targetIdentifier: 'B',
      actions: [
        'ecs:Start',
        'ecs:Stop'
      ]
    }
  ]
});

¶ 获取具备某些资源操作权限的主体

AclManagementClient().getAuthorizedTargets(options)

传入权限分组、资源标识、资源类型、操作权限项、主体类型，返回具备资源操作权限的主体标识符。

¶ 参数

options <object> 筛选条件对象；
namespace <string> 权限分组的 code，详情请见使用权限分组管理权限资源
resourceType <string> 资源类型，现有资源类型如下：
- DATA: 数据类型；
- API: API 类型数据；
- MENU: 菜单类型数据；
- BUTTON: 按钮类型数据。
resource: 资源 code
actions <object> 操作
- actions.op <string>，可选值为 AND、OR，表示 list 中的操作关系是和还是或。
- actions.list <string[]>，操作，例如 ['read', 'write']
targetType <string>，主体类型，可选值为 USER、ROLE、ORG、GROUP，含义为用户、角色、组织机构节点、用户分组。

¶ 示例

获取权限分组 6063f88dabb536e9a23a6c80 中，具备 DATA 类型资源 book 的 write 或 read 权限的用户。

let res = await managementClient.acl.getAuthorizedTargets({
  namespace: '6063f88dabb536e9a23a6c80',
  resource: 'book',
  resourceType: 'DATA',
  actions: {
    op: 'OR',
    list: ['write', 'read'],
  },
  targetType: 'USER',
})

¶ 示例数据

targetType 为主体类型；
targetIdentifier: 主体标识符，可能是用户 ID、角色 ID、组织结构节点 ID、用户分组 ID；
actions: 用户被授权对该资源的操作；

{
  "totalCount": 1,
  "list": [
    {
      "targetType": "USER",
      "targetIdentifier": "6063fcd01d0d2e39d4596904",
      "actions": ["write"]
    }
  ]
}

本文是否有解决您的问题？

如果遇到其他问题，你可以在 authing-chat/community 联系我们。