权限控制

此模块的 API 可以分为两类：

一类是权限管理、配置接口：

分组（Group）的增删改查接口
- 支持批量、分页
角色（Role）的增删改查接口
- 支持批量、分页
权限（Permission）的增删改查接口
- 支持批量、分页
分组内用户管理
分组内角色管理
角色内用户管理
角色内权限管理

另一类是查询特定用户权限接口：

查询特定用户所有权限列表
查询特定用户所有角色列表
查询特定用户所有分组列表

除了主动查询接口外，我们还支持将权限列表写入用户的 Token，开发者可以在本地使用应用密钥解密得到权限列表。最终的权限列表示例如下：

{    
    "permissionList": ["email:login", "email:read", "email:write", "email:send"]
}

其中 email:login 完全为用户自定义，我们推荐使用 object:action 的格式进行命名。

开发者拿到用户权限列表之后，可以在业务代码层判断用户是否具备某一特定权限，如：

if not "email:login" in user.permissionList:    
    raise PermissionDeniedError

初始化

使用以下接口时，请先完成初始化工作，请参考：

SDK for Node.js

异常处理

所有失败的操作，都需要使用 try catch 捕获异常。操作失败有两种情况：

网络请求出错，常见情况包括：传递参数不合法，这会被 GraphQL 过滤层直接拦截；网络无法连接。
业务逻辑出错，常见情况包括：密码不正确，删除某资源传递的 id 不存在等。

为了方便开发者快速定位出错原因，我们提供一个 formatError 函数：

function formatError(error) {
  if (typeof error === 'string') return error;
  if (error.request) {
    // 网络请求错误
    if(error.response)
      return JSON.stringify(error.response.data);
    else
      return JSON.stringify(error.request);
  } else if (typeof error.message === 'object') {
    // 业务逻辑错误
    if (error.message.message) {
      return JSON.stringify(error.message.message);
    } else {
      return JSON.stringify(error.message);
    }
  } else {
    return error;
  }
}

示例如下：

  try {
    const res = await authing.authz.deleteGroup("不存在的 groupId")
    console.log(res)
  } catch (error) {
    console.log(formatError(error))
  }

分组增删改查

创建分组

Authing.authz.createGroup(input)

参数
- input <Object>
  - name <string> 名称，必填。
  - description <string> 描述，选填。
使用方法

const group = await authing.authz.createGroup({
  name: 'admin',
  description: "系统管理员"
})

返回数据

{
  _id: '5e1edbd74b6419665991f51e',
  name: '管理员835bdf92gth',
  description: '描述信息',
  createdAt: '2020-01-16T20:47:04+08:00',
  updatedAt: '2020-01-16T20:47:04+08:00'
}

修改分组

Authing.authz.updateGroup(input)

参数
- input <Object>
  - _id <string> 分组 ID，必填。
  - name <string> 名称，选填。
  - description <string> 描述，选填。
使用方法

group = await authing.authz.updateGroup({
  _id: "5e1edcb14b6419665991f595",
  description: '新的描述'
})

返回数据

{
  _id: '5e1edcb14b6419665991f595',
  name: 'admin',
  description: '新的描述',
  createdAt: '2020-01-16T20:47:04+08:00',
  updatedAt: '2020-01-16T20:47:04+08:00'
}

本页中的所有修改接口均遵循以下逻辑：

_id 参数必填
出现在 input 中的字段值将替换原有值
没有出现在 input 中的字段值保持不变
传入 input 的多余字段将会被舍弃

查询分组

Authing.authz.group(_id)

参数
- _id <string> 分组 ID，必填。
使用方法

const group = await authing.authz.group("5e1edcb14b6419665991f595")

返回数据

{
  _id: '5e1edcb14b6419665991f595',
  name: 'admin',
  description: '新的描述',
  createdAt: '2020-01-16T20:47:04+08:00',
  updatedAt: '2020-01-16T20:47:04+08:00'
}

查询用户池分组列表

此方法支持分页、排序。

Authing.authz.groupList(options)

参数
- options <Object> 可选
  - sortBy <string> 排序方式，可选。默认为 CREATEDAT_DESC ，表示按照创建时间降序，也就是最新创建的排在最前面。全部的可选值为：
    CREATEDAT_DESC：按照创建时间降序。
    CREATEDAT_ASC ：按照创建时间升序。
    UPDATEDAT_DESC：按照修改时间降序。
    UPDATEDAT_ASC：按照修改时间排序。
  - page <int> 页码，可选。默认为 0，zero-based。
  - count <int> 没页数目，可选。默认为 10。
使用方法

const groupList = await authing.authz.groupList()

// 自定义排序方式 / 分页
const {totalCount, list} = await authing.authz.groupList({
    sortBy: "CREATEDAT_DESC",
    page: 1,
    count: 10,
})

返回数据
- totalCount 总数
- list 当前页列表

{
  totalCount: 2,
  list: [
    {
      _id: '5e1fff324b6419665991f6b4',
      name: 'employee',
      description: '正式员工。',
      createdAt: '2020-01-16T20:47:04+08:00',
      updatedAt: '2020-01-16T20:47:04+08:00'
    },
    {
      _id: '5e1edcb34b6419665991f5d9',
      name: 'intern',
      description: '实习生。',
      createdAt: '2020-01-16T20:47:04+08:00',
      updatedAt: '2020-01-16T20:47:04+08:00'
    },
  ]
}

删除分组

Authing.authz.deleteGroup(_id)

参数
- _id 分组 ID，必填。
使用方法

const res = await authing.authz.deleteGroup("5e20082f4b6419665991fa57")

返回数据

操作成功示例

{ 
    message: '操作成功',
    code: 200
}

如果操作失败，需要使用 try catch 捕捉异常，详情见 异常处理 部分。

删除分组会将其与角色、用户之间的关系连带一起删除（角色、用户本身不会删除），不可撤回，请谨慎操作。

且此操作为原子化操作，要么成功，要么全部 rollback。

批量删除分组

Authing.authz.deleteGroupBatch(idList)

参数
- idList: <Array> 分组 ID 列表。
使用方法

const res = await authing.authz.deleteGroupBatch([
    "5e1fff324b6419665991f6b4",
    "5e1edcb34b6419665991f5d9"
])

返回参数

操作成功示例：

{ 
    message: '操作成功',
    code: 200
}

批量操作，当且仅当所有操作成功时才会返回成功，如果其中任意一个步骤失败，其他所有操作将会 rollback，回退到之前的状态。操作失败需要用 try/catch 捕获异常，详情见异常处理部分。

此操作不可撤回，请谨慎操作。

角色增删改查

创建角色

Authing.authz.createRole(input)

参数
- input <Object>
  - name: 名称，必填。
  - description: 描述，必填。
使用方法

const role = await authing.authz.createRole({
  name: 'Invoice Submitter',
  description: '能使用发票工具创建并读取发票工具记录'
})

返回数据

{
  _id: '5e20082f4b6419665991fa57',
  name: 'Invoice Submitter',
  description: '能使用发票工具创建并读取发票工具记录',
  createdAt: '2020-01-16T20:47:04+08:00',
  updatedAt: '2020-01-16T20:47:04+08:00'
}

分组(Group)和角色(Role)有什么区别？

角色是一组权限的集合。
分组侧重于管理用户，一个分组通常拥有多个角色，分组内的用户会继承分组内所有角色的所有权限。

常见的 Group 和 Role 示例：

Group
- admin: 系统管理员，通常包含系统维护者。
- employee: 正式雇员。
- employer: 面试官。
- hr
- intern: 实习生
- ops_engineer: 运维工程师
Role
- Invoice Submitter: 具备发票报销的相关权限。
- Vacation Requester: 具备申请假期的相关权限。
- Corporation Email User: 具备使用公司邮箱的的相关权限。
- Production Server Operator: 具备线上服务器的操作权限。
- HR App User: 具备使用 HR 系统的相关权限。

举例来说：可以这样建立 Role 和 Group 之间的关系：

intern 具备 Corporation Email User 这个角色，但是不具备 Vacation Requester 和 Invoice Submitter 这两个角色。
employee 拥有发票报销和申请假期角色，但是不具备线上服务器的操作权限。
ops_engineer 拥有发票报销、申请假期、线上服务器的角色。

推荐使用 Group organize 用户，用 Role organize 权限，不要直接赋予单个用户某个权限。如果是某个用户临时需要具备某个角色，可以临时授予，结束之后再收回。

修改角色

Authing.authz.updateRole(input)

参数
- input <Object>
  - _id: 角色 ID，必填。
  - name: 角色名称，选填。
  - description：角色描述，选填。
使用方法

const role = await authing.authz.updateRole({
  _id: "5e20082f4b6419665991fa57",
  name: "Invoice Submitter",
  description: '能使用发票工具创建并读取发票工具记录。'
})

返回数据

{
  _id: '5e20082f4b6419665991fa57',
  name: 'Invoice Submitter',
  description: '能使用发票工具创建并读取发票工具记录。',
  createdAt: '2020-01-16T20:47:04+08:00',
  updatedAt: '2020-01-16T20:47:04+08:00'
}

查询角色

Authing.authz.role(_id)

参数
- _id <string> 角色 ID，必填。
使用方法

const role = await authing.authz.role("5e20082f4b6419665991fa57")

返回数据

{
  _id: '5e20082f4b6419665991fa57',
  name: 'Invoice Submitter',
  description: '能使用发票工具创建并读取发票工具记录。'
  createdAt: '2020-01-16T20:47:04+08:00',
  updatedAt: '2020-01-16T20:47:04+08:00'
}

查询用户池角色列表

此方法支持分页、排序。

Authing.authz.roleList(options)

参数
- options <Object> 可选
  - sortBy <string> 排序方式，可选。默认为 CREATEDAT_DESC ，表示按照创建时间降序，也就是最新创建的排在最前面。全部的可选值为：
    CREATEDAT_DESC：按照创建时间降序。
    CREATEDAT_ASC ：按照创建时间升序。
    UPDATEDAT_DESC：按照修改时间降序。
    UPDATEDAT_ASC：按照修改时间排序。
  - page <int> 页码，可选。默认为 0，zero-based。
  - count <int> 没页数目，可选。默认为 10。
使用方法

const roleList = await authing.authz.roleList()

// 自定义排序方式 / 分页
const {totalCount, list} = await authing.authz.roleList({
      sortBy: 'CREATEDAT_DESC',
      page: 2,
      count: 10
})

返回数据
- totalCount 总数
- list 当前页列表

{
  totalCount: 2,
  list: [
    {
      _id: '5e20082f4b6419665991fa57',
      name: 'Invoice Submitter',
      description: '能使用发票工具创建并读取发票工具记录。'
    },
    {
      _id: '5e20082f4b6419665991fa58',
      name: 'Vacation Requester',
      description: '能使用假期申请工具申请假期。'
    },
  ]
}

删除角色

Authing.authz.deleteRole(_id)

参数
- _id 角色 ID，必填。
使用方法

const res = await authing.authz.deleteRole("Role ID")

返回数据

操作成功示例

{ 
    message: '操作成功',
    code: 200, 
}

如果操作失败，需要使用 try catch 捕捉异常，详情见 异常处理 部分。

删除角色会将其与权限、用户之间的关系连带一起删除（权限、用户本身不会删除），不可撤回，请谨慎操作。

且此操作为原子化操作，要么成功，要么全部 rollback。

批量删除角色

Authing.authz.deleteRoleBatch(idList)

参数
- idList: <Array> 分组 ID 列表。
使用方法

const res = await authing.authz.deleteRoleBatch([
    "5e1fff324b6419665991f6b4",
    "5e1edcb34b6419665991f5d9"
])

返回参数

操作成功示例：

{ 
    message: '操作成功',
    code: 200
}

此操作不可撤回，请谨慎操作。

权限增删改查

创建权限

Authing.authz.createPermission(input)

参数
- input <Object>
  - name <string> 名称，必填。
  - description <string> 描述，选填。
使用方法

const group = await authing.authz.createPermission({
  name: 'invoice:submit',
  description: "提交发票报销申请"
})

返回数据

{
  _id: '5e1edbd74b6419665991f51e',
  name: 'invoice:submit',
  description: '提交发票报销申请'
}

推荐使用 subject:action 这类形式命名权限。如：

invoice:submit 提交发票报销申请
invoice:revoke 撤回发票报销申请
invoice:update 修改发起申请详情
invoice:list 查看发起申请历史记录
invoice:read 查看发票申请详情

修改权限

Authing.authz.updatePermission(input)

参数
- input <Object>
  - _id: 角色 ID，必填。
  - name: 角色名称，选填。
  - description：角色描述，选填。
使用方法

const role = await authing.authz.updatePermission({
  _id: "5e20082f4b6419665991fa57",
  name: "invoice:submit",
  description: '提交发票报销申请。'
})

返回数据

{
  _id: '5e20082f4b6419665991fa57',
  name: "invoice:submit",
  description: '提交发票报销申请。'
  createdAt: '2020-01-16T20:47:04+08:00',
  updatedAt: '2020-01-16T20:47:04+08:00'
}

查询权限

Authing.authz.permission(_id)

参数
- _id <string> 权限 ID，必填。
使用方法

const group = await authing.authz.permission("5e20082f4b6419665991fa57")

返回数据

{
  _id: '5e20082f4b6419665991fa57',
  name: "invoice:submit",
  description: '提交发票报销申请。',
  createdAt: '2020-01-16T20:47:04+08:00',
  updatedAt: '2020-01-16T20:47:04+08:00'
}

查询用户池权限列表

此方法支持分页、排序。

Authing.authz.permissionList(options)

参数
- options <Object> 可选
  - sortBy <string> 排序方式，可选。默认为 CREATEDAT_DESC ，表示按照创建时间降序，也就是最新创建的排在最前面。全部的可选值为：
    CREATEDAT_DESC：按照创建时间降序。
    CREATEDAT_ASC ：按照创建时间升序。
    UPDATEDAT_DESC：按照修改时间降序。
    UPDATEDAT_ASC：按照修改时间排序。
  - page <int> 页码，可选。默认为 0，zero-based。
  - count <int> 没页数目，可选。默认为 10。
使用方法

const permissionList = await authing.authz.permissionList()

const permissionList = await authing.authz.permissionList({
  sortBy: 'CREATEDAT_DESC',
  page: 2,
  count: 10
})

返回数据
- totalCount 总数
- list 当前页列表

{
  totalCount: 1,
  list: [
    {
      _id: '5e20082f4b6419665991fa57',
      name: "invoice:submit",
      description: '提交发票报销申请。',
      createdAt: '2020-01-16T20:47:04+08:00',
      updatedAt: '2020-01-16T20:47:04+08:00'
    }
  ]
}

删除权限

Authing.authz.deletePermission(_id)

参数
- _id 权限 ID，必填。
使用方法

const res = await authing.authz.deletePermission("Permission ID")

返回数据

操作成功示例

{ 
    message: '操作成功',
    code: 200
}

如果操作失败，需要使用 try catch 捕捉异常，详情见 异常处理 部分。

删除角色会将其与权限、用户之间的关系连带一起删除（权限、用户本身不会删除），不可撤回，请谨慎操作。

且此操作为原子化操作，要么成功，要么全部 rollback。

批量删除权限

Authing.authz.deletePermissionBatch(idList)

参数
- idList: <Array> 分组 ID 列表。
使用方法

const res = await authing.authz.deletePermissionBatch([
    "5e1fff324b6419665991f6b4",
    "5e1edcb34b6419665991f5d9"
])

返回参数

操作成功示例：

{ 
    message: '操作成功',
    code: 200
}

此操作不可撤回，请谨慎操作。

分组内角色管理

推荐使用 Group 管理用户，用 Role 管理权限，不要直接赋予单个用户某个权限。如果是某个用户临时需要具备某个角色，可以临时授予，结束之后再收回。

查询分组角色列表

Authing.authz.groupRoleList(_id)

参数
- _id <string> 分组 ID
使用方法

const {totalCount, list} = await authing.authz.groupRoleList()

返回数据

{
    list: [
      {
        _id: '5e351f8815e7ca5a3577b6f7',
        createdAt: '2020-02-01T14:49:44+08:00',
        description: '描述',
        name: '角色itbv3w6jrgk',
        updatedAt: '2020-02-01T14:49:44+08:00',
      },
    ],
    totalCount: 1,
  }

分组添加角色

Authing.authz.addRoleToGroup(input, options)

参数：
- input <Object> 必填
  - groupId: <string> 分组 ID，必填。
  - roleId: <string> 角色 ID，必填。
- options <Object> 选填
  - fetchRoles <boolean> 是否在结果中返回最新的角色列表。选填，默认为 false。
使用方法

// 默认，不返回最新的角色列表
const res = await authing.authz.addRoleToGroup({
  roleId: "xxx",
  groupId: "xxx"
})

const res = await authing.authz.addRoleToGroup({
  roleId: "xxx",
  groupId: "xxx"
}, {
  fetchRoles: true
})

返回数据

操作成功示例：

{ 
    message: '操作成功',
    code: 200
}

// 返回最新角色列表
{
  code: 200,
  message: '操作成功',
  data: { 
    totalCount: 1, 
    list: [
      {
        createdAt: '2020-01-16T20:47:04+08:00',
        updatedAt: '2020-01-16T20:47:04+08:00'
      }
    ] 
  }
}

如果操作失败，需要使用 try catch 捕捉异常，详情见 异常处理 部分。

分组删除角色

authing.authz.removeRoleFromGroup(input, options)

参数
- input <Object>
  - groupId 分组 ID,必填。
  - roleId 角色 ID, 必填。
- options <Object> 选填
  - fetchRoles <boolean> 是否在结果中返回最新的角色列表。选填，默认为 false。
使用方法

await authing.authz.removeRoleFromGroup({
  roleId: "xxx",
  groupId: "xxx"
})

const res = await authing.authz.removeRoleFromGroup({
  roleId: "xxx",
  groupId: "xxx"
}, {
  fetchRoles: true
})

返回数据

操作成功示例：

{ 
    message: '操作成功',
    code: 200
}

// 返回最新角色列表
{
  code: 200,
  message: '操作成功',
  data: { 
    totalCount: 1, 
    list: [
      {
        _id: '5e2148ddce7f3e37be7c86d4',
        createdAt: '2020-01-17T13:40:45+08:00',
        description: '描述',
        name: '角色km4ia4a7a4o',
        updatedAt: '2020-01-17T13:40:45+08:00',
      }
    ] 
  }
}

如果操作失败，需要使用 try catch 捕捉异常，详情见 异常处理 部分。

分组批量添加角色

Authing.authz.addRoleToGroupBatch(input, options)

参数：
- input <Object> 必填
  - groupId: 分组 ID，必填。
  - roleIdList: 角色 ID 列表，必填。
- options <Object> 选填
  - fetchRoles <boolean> 是否在结果中返回最新的角色列表。选填，默认为 false。
使用方法

const res = await authing.authz.addRoleToGroupBatch({
  roleIdList: [
    "id1",
    "id2"
  ],
  groupId: "id"
})

const res = await authing.authz.addRoleToGroupBatch({
  roleIdList: [
    "id1",
    "id2"
  ],
  groupId: "id"
}， {
  fetchRoles: true
})

返回数据

操作成功示例：

{ 
    message: '操作成功',
    code: 200
}

// 返回最新的角色列表
{ 
    message: '操作成功',
    code: 200,
    data: {
      list: [
        {
          _id: '5e2148ddce7f3e37be7c86d4',
          createdAt: '2020-01-17T13:40:45+08:00',
          description: '描述',
          name: '角色km4ia4a7a4o',
          updatedAt: '2020-01-17T13:40:45+08:00',
        },
        {
          _id: '5e2148ddce7f3e37be7c86d2',
          createdAt: '2020-01-17T13:40:45+08:00',
          description: '描述',
          name: '角色fwhlsn81uku',
          updatedAt: '2020-01-17T13:40:45+08:00',
        },
        {
          _id: '5e2148ddce7f3e37be7c86ca',
          createdAt: '2020-01-17T13:40:45+08:00',
          description: '描述',
          name: '角色7eoxpb0km7y',
          updatedAt: '2020-01-17T13:40:45+08:00',
        },
        {
          _id: '5e2148ddce7f3e37be7c86c9',
          createdAt: '2020-01-17T13:40:45+08:00',
          description: '描述',
          name: '角色gqgp9vzfey',
          updatedAt: '2020-01-17T13:40:45+08:00',
        },
      ],
      totalCount: 4,
  }
}

分组批量删除角色

Authing.authz.removeRoleFromGroupBatch(input, options)

参数
- input <Object> 必填
  - groupId: 分组 ID，必填。
    roleIdList: 角色 ID 列表，必填。
- options <object> 选填
  - fetchRoles <boolean> 是否在结果中返回最新的角色列表。选填，默认为 false。
使用方法

const res = await authing.authz.removeRoleFromGroupBatch({
  roleIdList: [
    "id1",
    "id2"
  ],
  groupId: "id"
})

const res = await authing.authz.removeRoleFromGroupBatch({
  roleIdList: [
    "id1",
    "id2"
  ],
  groupId: "id"
}, {
  fetchRoles: true
})

返回参数

操作成功示例：

{ 
    message: '操作成功',
    code: 200
}

// 返回最新角色列表
{
  code: 200,
  message: '操作成功',
  data: { 
    totalCount: 1, 
    list: [
      {
        _id: '5e2148ddce7f3e37be7c86d4',
        createdAt: '2020-01-17T13:40:45+08:00',
        description: '描述',
        name: '角色km4ia4a7a4o',
        updatedAt: '2020-01-17T13:40:45+08:00',
      }
    ] 
  }
}

此操作不可撤回，请谨慎操作。

分组内用户管理

查询分组内用户列表

此方法支持分页、排序。

Authing.authz.groupUserList(_id, options)

参数
- _id: 分组ID
- options <Object> 可选
  - sortBy <string> 排序方式，可选。默认为 CREATEDAT_DESC ，表示按照创建时间降序，也就是最新创建的排在最前面。全部的可选值为：
    CREATEDAT_DESC：按照创建时间降序。
    CREATEDAT_ASC ：按照创建时间升序。
    UPDATEDAT_DESC：按照修改时间降序。
    UPDATEDAT_ASC：按照修改时间排序。
  - page <int> 页码，可选。默认为 0，zero-based。
  - count <int> 没页数目，可选。默认为 10。
使用方法

const {totalCount, list} = await authing.authz.groupUserList("xxxx")

// 或者
const {totalCount, list}  = await authing.authz.groupUserList("xxx", {
  sortBy: 'CREATEDAT_DESC',
  page: 2,
  count: 10
})

返回数据
- totalCount 总数
- list 当前页列表

{
  list: [
    {
      _id: '5e35239215e7ca5a3577b8af',
      blocked: false,
      browser: '',
      company: '',
      email: 'o2sozsya3mm@authing.cn',
      emailVerified: false,
      isDeleted: false,
      lastIP: null,
      lastLogin: '2020-02-01T15:06:58+08:00',
      loginsCount: 0,
      nickname: '',
      oauth: '',
      phone: '',
      photo: 'https://usercontents.authing.cn/authing-avatar.png',
      registerInClient: '5e1be38ab1599657b6477022',
      registerMethod: 'default:username-password',
      signedUp: '2020-02-01T15:06:58+08:00',
      token: null,
      tokenExpiredAt: 'Invalid date',
      unionid: null,
      userLocation: null,
      userLoginHistory: null,
      username: 'o2sozsya3mm@authing.cn',
    },
  ],
  totalCount: 15,
}

分组添加用户

Authing.authz.addUserToGroup(input, options)

参数：
- input <Object>
  - groupId: 分组 ID，必填。
  - userId: 用户 ID，必填。
- options <object> 选填
  - fetchUsers <boolean> 是否在结果中返回最新的用户列表。选填，默认为 false。
使用方法

const res = await authing.authz.addUserToGroup({
  userId: "",
  groupId: ""
})

返回数据

操作成功示例：

{ 
    message: '操作成功',
    code: 200
}

如果操作失败，需要使用 try catch 捕捉异常，详情见 异常处理 部分。

分组删除用户

Authing.authz.removeUserFromGroup(input, options)

参数：
- input: <Object>
  - groupId: <string> 分组 ID，必填。
  - userId: <string> 用户 ID，必填。
- options <object> 选填
  - fetchUsers <boolean> 是否在结果中返回最新的用户列表。选填，默认为 false。
使用方法

const res = await authing.authz.removeUserFromGroup({
  userId: "",
  groupId: ""
})

返回数据

操作成功示例：

{ 
    message: '操作成功',
    code: 200
}

如果操作失败，需要使用 try catch 捕捉异常，详情见 异常处理 部分。

分组批量添加用户

Authing.authz.addUserToGroupBatch(input, options)

参数：
- input: <Object>
  - groupId: 分组 ID，必填。
  - userIdList: 用户 ID，必填。
- options <object> 选填
  - fetchUsers <boolean> 是否在结果中返回最新的用户列表。选填，默认为 false。
使用方法

const res = await authing.authz.addUserToGroup({
  userIdList: ["", ""],
  groupId: ""
})

返回数据

操作成功示例：

{ 
    message: '操作成功',
    code: 200
}

如果操作失败，需要使用 try catch 捕捉异常，详情见 异常处理 部分。

分组批量删除用户

Authing.authz.removeUserFromGroupBatch(input, options)

参数：
- input: <Object>
  - groupId: 分组 ID，必填。
  - userIdList: 用户 ID 列表，必填。
- options <object> 选填
  - fetchUsers <boolean> 是否在结果中返回最新的用户列表。选填，默认为 false。
使用方法

const res = await authing.authz.removeUserFromGroupBatch({
  userIdList: ["", ""],
  groupId: ""
})

返回数据

操作成功示例：

{ 
    message: '操作成功',
    code: 200
}

如果操作失败，需要使用 try catch 捕捉异常，详情见 异常处理 部分。

此操作不可撤回，请谨慎操作。

角色内用户管理

查询具备某角色的用户列表

此方法支持分页、排序。

Authing.authz.roleUserList(_id, options)

参数
- _id: 角色ID
- options <Object> 可选
  - sortBy <string> 排序方式，可选。默认为 CREATEDAT_DESC ，表示按照创建时间降序，也就是最新创建的排在最前面。全部的可选值为：
    CREATEDAT_DESC：按照创建时间降序。
    CREATEDAT_ASC ：按照创建时间升序。
    UPDATEDAT_DESC：按照修改时间降序。
    UPDATEDAT_ASC：按照修改时间排序。
  - page <int> 页码，可选。默认为 0，zero-based。
  - count <int> 没页数目，可选。默认为 10。
使用方法

const {totalCount, list} = await authing.authz.roleUserList("xxxx")

// 或者
const {totalCount, list}  = await authing.authz.roleUserList("xxx", {
  sortBy: 'CREATEDAT_DESC',
  page: 2,
  count: 10
})

返回数据
- totalCount 总数
- list 当前页列表

{
  list: [
    {
      _id: '5e35239215e7ca5a3577b8af',
      blocked: false,
      browser: '',
      company: '',
      email: 'o2sozsya3mm@authing.cn',
      emailVerified: false,
      isDeleted: false,
      lastIP: null,
      lastLogin: '2020-02-01T15:06:58+08:00',
      loginsCount: 0,
      nickname: '',
      oauth: '',
      phone: '',
      photo: 'https://usercontents.authing.cn/authing-avatar.png',
      registerInClient: '5e1be38ab1599657b6477022',
      registerMethod: 'default:username-password',
      signedUp: '2020-02-01T15:06:58+08:00',
      token: null,
      tokenExpiredAt: 'Invalid date',
      unionid: null,
      userLocation: null,
      userLoginHistory: null,
      username: 'o2sozsya3mm@authing.cn',
    },
  ],
  totalCount: 15,
}

授权用户某角色

Authing.authz.assignRoleToUser(input, options)

参数：
- options <Object> 必填
  - userId: <string> 用户 ID，必填。
  - roleId: <string> 角色 ID，必填。
- input <Object> 选填
  - fetchUsers <boolean> 是否在结果中返回角色中包含的最新用户列表。选填，默认为 false。
使用方法

const res = await authing.authz.assignRoleToUser({
  roleId: "",
  userId: ""
})

返回数据

操作成功示例：

{ 
    message: '操作成功',
    code: 200
}

如果操作失败，需要使用 try catch 捕捉异常，详情见 异常处理 部分。

一个用户最多同时具有 50 个角色。

批量授权用户某角色

Authing.authz.assignRoleToUserBatch(input, options)

参数：
- input <Object> 必填
  - userId: <string> 用户 ID，必填。
  - roleId: <string> 角色 ID，必填。
- options <Object> 选填
  - fetchUsers <boolean> 是否在结果中返回角色中包含的最新用户列表。选填，默认为 false。
使用方法

const res = await authing.authz.assignRoleToUserBatch({
  roleId: "",
  userIdList: []
})

// 返回最新列表
const res = await authing.authz.assignRoleToUserBatch({
  roleId: "",
  userIdList: []
}, {
  fecthUsers: true
)

返回数据

操作成功示例：

{ 
    message: '操作成功',
    code: 200
}

如果操作失败，需要使用 try catch 捕捉异常，详情见 异常处理 部分。

撤权用户某角色

Authing.authz.revokeRoleFromUser(input, options)

参数：
- input <Object> 必填
  - userId: <string> 用户 ID，必填。
  - roleId: <string> 角色 ID，必填。
- options <Object> 选填
  - fetchUsers <boolean> 是否在结果中返回角色中包含的最新用户列表。选填，默认为 false。
使用方法

const res = await authing.authz.revokeRoleFromUser({
  roleId: "",
  userId: ""
})

返回数据

操作成功示例：

{ 
    message: '操作成功',
    code: 200
}

如果操作失败，需要使用 try catch 捕捉异常，详情见 异常处理 部分。

批量撤权用户某角色

Authing.authz.revokeRoleFromUser(input, options)

参数：
- input <Object> 必填
  - userId: <string> 用户 ID，必填。
  - roleId: <string> 角色 ID，必填。
- options <Object> 选填
  - fetchUsers <boolean> 是否在结果中返回角色中包含的最新用户列表。选填，默认为 false。
使用方法

const res = await authing.authz.revokeRoleFromUser({
  roleId: "",
  userIdList: []
})

返回数据

操作成功示例：

{ 
    message: '操作成功',
    code: 200
}

如果操作失败，需要使用 try catch 捕捉异常，详情见 异常处理 部分。

角色内权限管理

查询某角色具备的所有权限

此方法支持分页、排序。

Authing.authz.rolePermissionList(_id)

参数
- _id: <string> 角色ID
使用方法

const {totalCount, list} = await authing.authz.rolePermissionList("xxxx")

// 或者
const {totalCount, list}  = await authing.authz.rolePermissionList("xxx"})

返回数据
- totalCount 总数
- list 当前页列表

 {
    list: [
      {
        _id: '5e35259315e7ca5a3577b9d9',
        createdAt: '2020-02-01T15:15:31+08:00',
        description: '描述',
        name: '权限cassasb4vz',
        updatedAt: '2020-02-01T15:15:31+08:00',
      },
    ],
    totalCount: 1,
  }

角色添加权限

Authing.authz.addPermissionToRole(input, options)

参数：
- input <Object>
  - permissionId: <string> 权限 ID，必填。
  - roleId: <string> 角色 ID，必填。
- options <object> 选填
  - fetchPermissions <boolean> 是否在结果中返回最新的权限列表。选填，默认为 false。
使用方法

const res = await authing.authz.addPermissionToRole({
  roleId: "",
  permissionId: ""
})

返回数据

操作成功示例：

{ 
    message: '操作成功',
    code: 200
}

如果操作失败，需要使用 try catch 捕捉异常，详情见 异常处理 部分。

角色批量添加权限

Authing.authz.addPermissionToRoleBatch(input, options)

参数：
- input <Object>
  - permissionIdList: <Array> 权限 ID 列表，必填。
  - roleId: <string> 角色 ID，必填。
- options <object> 选填
  - fetchPermissions <boolean> 是否在结果中返回最新的权限列表。选填，默认为 false。
使用方法

const res = await authing.authz.addPermissionToRole({
  roleId: "",
  permissionIdList: ["",""]
})

返回数据

操作成功示例：

{ 
    message: '操作成功',
    code: 200
}

如果操作失败，需要使用 try catch 捕捉异常，详情见 异常处理 部分。

角色删除权限

Authing.authz.removePermissionFromRole(input, options)

参数：
- input <Object>
  - permissionId: <string> 权限 ID，必填。
  - roleId: <string> 角色 ID，必填。
- options <object> 选填
  - fetchPermissions <boolean> 是否在结果中返回最新的权限列表。选填，默认为 false。
使用方法

const res = await authing.authz.removePermissionFromRole({
  roleId: "",
  permissionId: ""
})

返回数据

操作成功示例：

{ 
    message: '操作成功',
    code: 200
}

如果操作失败，需要使用 try catch 捕捉异常，详情见 异常处理 部分。

角色批量删除权限

Authing.authz.removePermissionFromRoleBatch(input, options)

参数：
- input <Object>
  - permissionId: <string> 权限 ID，必填。
  - roleId: <string> 角色 ID，必填。
- options <object> 选填
  - fetchPermissions <boolean> 是否在结果中返回最新的权限列表。选填，默认为 false。
使用方法

const res = await authing.authz.removePermissionFromRoleBatch({
  roleId: "",
  permissionIdList: ["",""]
})

返回数据

操作成功示例：

{ 
    message: '操作成功',
    code: 200
}

如果操作失败，需要使用 try catch 捕捉异常，详情见 异常处理 部分。

错误码

角色权限管理的相关错误码以 39xx 开头。

如何获取错误码? 如下所示：

try {
  const group = await authing.authz.group("NOGTEXIST")
} catch (error) {
  const errcode = error.message.code
  assert(errcode === 3901)
}

错误码

说明

2020

尚未登录，无访问权限

3901

Group 不存在

3902

无权操作此 Group

3903

Role 不存在

3904

无权操作此 Role

3905

Permission 不存在

3906

无权操作此 Permission

3907

删除 Group 失败

3910

Role ${role.name} 已在 Group ${group.name} 中了

3911

Role ${role.name} 不在 Group ${group.name} 中

3912

User ${user._id} 已在 Group ${group.name} 中了

3913

User ${user._id} 不在 Group ${group.name} 中

3914

删除 Permission 失败

3915

删除 Role 失败

3916

Permission ${permission.name} 已在 Role ${role.name} 中了

3917

Permission ${permission.name} 不在 Role ${role.name} 中

3918

User ${user._id} 已具备 Role ${role.name}

3919

User ${user._id} 不具备 Role ${role.name}

PreviousSDK for Node.js Next查询用户权限

Last updated 4 years ago