# 权限控制

此 模块的 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
}

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

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

# 权限增删改查

# 创建权限

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
}

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

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

# 分组内角色管理

推荐使用 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,
  }
}

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

# 分组批量删除角色

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',
      }
    ] 
  }
}

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

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

# 分组内用户管理

# 查询分组内用户列表

此方法支持分页、排序。

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 捕捉异常,详情见 异常处理 部分。

批量操作,当且仅当所有操作成功时才会返回成功,如果其中任意一个步骤失败,其他所有操作将会 rollback,回退到之前的状态。操作失败需要用 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 捕捉异常,详情见 异常处理 部分。

批量操作,当且仅当所有操作成功时才会返回成功,如果其中任意一个步骤失败,其他所有操作将会 rollback,回退到之前的状态。操作失败需要用 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 捕捉异常,详情见 异常处理 部分。

批量操作,当且仅当所有操作成功时才会返回成功,如果其中任意一个步骤失败,其他所有操作将会 rollback,回退到之前的状态。操作失败需要用 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 捕捉异常,详情见 异常处理 部分。

批量操作,当且仅当所有操作成功时才会返回成功,如果其中任意一个步骤失败,其他所有操作将会 rollback,回退到之前的状态。操作失败需要用 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 捕捉异常,详情见 异常处理 部分。

批量操作,当且仅当所有操作成功时才会返回成功,如果其中任意一个步骤失败,其他所有操作将会 rollback,回退到之前的状态。操作失败需要用 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 捕捉异常,详情见 异常处理 部分。

批量操作,当且仅当所有操作成功时才会返回成功,如果其中任意一个步骤失败,其他所有操作将会 rollback,回退到之前的状态。操作失败需要用 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}